class Sass::Script::Value::Number - sass-3.4.14 Documentation

# class Sass::Script::Value::Number

A SassScript object representing a number. SassScript numbers can have decimal values, and can also have units. For example, `12`, `1px`, and `10.45em` are all valid values.

Numbers can also have more complex units, such as `1px*em/in`. These cannot be inputted directly in Sass code at the moment.

### Constants

CONVERSION_TABLE

  A two-dimensional hash from two units to the conversion ratio between them. Multiply `X` by `CONVERSION_TABLE[Y]` to convert it to `Y`.

MUTUALLY_CONVERTIBLE

  A hash from each known unit to the set of units that it's mutually convertible with.

NO_UNITS

  Used so we don't allocate two new arrays for each new number.

OPERATIONS

### Attributes

denominator_units[R]

A list of units in the denominator of the number. For example, `1px*em/in*cm` would return `[“in”, “cm”]` @return [Array<String>]

numerator_units[R]

A list of units in the numerator of the number. For example, `1px*em/in*cm` would return `[“px”, “em”]` @return [Array<String>]

original[RW]

The original representation of this number. For example, although the result of `1px/2px` is `0.5`, the value of `#original` is `“1px/2px”`.

This is only non-nil when the original value should be used as the CSS value, as in `font: 1px/2px`.

@return [Boolean, nil]

value[R]

The Ruby value of the number.

@return [Numeric]

### Public Class Methods

new(value, numerator_units = NO_UNITS, denominator_units = NO_UNITS) click to toggle source

@param value [Numeric] The value of the number @param #numerator_units [::String, Array<::String>] See {#numerator_units} @param #denominator_units [::String, Array<::String>] See {#denominator_units}

Calls superclass method Sass::Script::Value::Base.new

    # File lib/sass/script/value/number.rb, line 60
    def initialize(value, numerator_units = NO_UNITS, denominator_units = NO_UNITS)
      numerator_units = [numerator_units] if numerator_units.is_a?(::String)
      denominator_units = [denominator_units] if denominator_units.is_a?(::String)
      super(value)
      @numerator_units = numerator_units
      @denominator_units = denominator_units
      normalize!
    end

precision() click to toggle source

    # File lib/sass/script/value/number.rb, line 36
    def self.precision
      @precision ||= 5
    end

precision=(digits) click to toggle source

Sets the number of digits of precision For example, if this is `3`, `3.1415926` will be printed as `3.142`.

    # File lib/sass/script/value/number.rb, line 43
    def self.precision=(digits)
      @precision = digits.round
      @precision_factor = 10.0**@precision
    end

precision_factor() click to toggle source

the precision factor used in numeric output it is derived from the `precision` method.

    # File lib/sass/script/value/number.rb, line 50
    def self.precision_factor
      @precision_factor ||= 10.0**precision
    end

### Private Class Methods

round(num) click to toggle source

@private

    # File lib/sass/script/value/number.rb, line 379
    def self.round(num)
      if num.is_a?(Float) && (num.infinite? || num.nan?)
        num
      elsif num % 1 == 0.0
        num.to_i
      else
        ((num * precision_factor).round / precision_factor).to_f
      end
    end

### Public Instance Methods

coerce(num_units, den_units) click to toggle source

Returns this number converted to other units. The conversion takes into account the relationship between e.g. mm and cm, as well as between e.g. in and cm.

If this number has no units, it will simply return itself with the given units.

An incompatible coercion, e.g. between px and cm, will raise an error.

@param num_units [Array<String>] The numerator units to coerce this number into.

    See {\#numerator\_units}

@param den_units [Array<String>] The denominator units to coerce this number into.

    See {\#denominator\_units}

@return [Number] The number with the new units @raise [Sass::UnitConversionError] if the given units are incompatible with the number's

    current units

    # File lib/sass/script/value/number.rb, line 345
    def coerce(num_units, den_units)
      Number.new(if unitless?
                   value
                 else
                   value * coercion_factor(@numerator_units, num_units) /
                     coercion_factor(@denominator_units, den_units)
                 end, num_units, den_units)
    end

comparable_to?(other) click to toggle source

@param other [Number] A number to decide if it can be compared with this number. @return [Boolean] Whether or not this number can be compared with the other.

    # File lib/sass/script/value/number.rb, line 356
    def comparable_to?(other)
      operate(other, :+)
      true
    rescue Sass::UnitConversionError
      false
    end

div(other) click to toggle source

The SassScript `/` operation. Its functionality depends on the type of its argument:

{Number} : Divides this number by the other, converting units appropriately.

{Value} : See {Value::Base#div}.

@param other [Value] The right-hand side of the operator @return [Value] The result of the operation

Calls superclass method Sass::Script::Value::Base#div

    # File lib/sass/script/value/number.rb, line 161
    def div(other)
      if other.is_a? Number
        res = operate(other, :/)
        if original && other.original
          res.original = "#{original}/#{other.original}"
        end
        res
      else
        super
      end
    end

eq(other) click to toggle source

The SassScript `==` operation.

@param other [Value] The right-hand side of the operator @return [Boolean] Whether this number is equal to the other object

    # File lib/sass/script/value/number.rb, line 191
    def eq(other)
      return Bool::FALSE unless other.is_a?(Sass::Script::Value::Number)
      this = self
      begin
        if unitless?
          this = this.coerce(other.numerator_units, other.denominator_units)
        else
          other = other.coerce(@numerator_units, @denominator_units)
        end
      rescue Sass::UnitConversionError
        return Bool::FALSE
      end
      Bool.new(this.value == other.value)
    end

eql?(other) click to toggle source

Hash-equality works differently than `==` equality for numbers. Hash-equality must be transitive, so it just compares the exact value, numerator units, and denominator units.

    # File lib/sass/script/value/number.rb, line 213
    def eql?(other)
      value == other.value && numerator_units == other.numerator_units &&
        denominator_units == other.denominator_units
    end

gt(other) click to toggle source

The SassScript `>` operation.

@param other [Number] The right-hand side of the operator @return [Boolean] Whether this number is greater than the other @raise [NoMethodError] if `other` is an invalid type

    # File lib/sass/script/value/number.rb, line 223
    def gt(other)
      raise NoMethodError.new(nil, :gt) unless other.is_a?(Number)
      operate(other, :>)
    end

gte(other) click to toggle source

The SassScript `>=` operation.

@param other [Number] The right-hand side of the operator @return [Boolean] Whether this number is greater than or equal to the other @raise [NoMethodError] if `other` is an invalid type

    # File lib/sass/script/value/number.rb, line 233
    def gte(other)
      raise NoMethodError.new(nil, :gte) unless other.is_a?(Number)
      operate(other, :>=)
    end

hash() click to toggle source

    # File lib/sass/script/value/number.rb, line 206
    def hash
      [value, numerator_units, denominator_units].hash
    end

inspect(opts = {}) click to toggle source

Returns a readable representation of this number.

This representation is valid CSS (and valid SassScript) as long as there is only one unit.

@return [String] The representation

    # File lib/sass/script/value/number.rb, line 273
    def inspect(opts = {})
      return original if original

      value = self.class.round(self.value)
      str = value.to_s

      # Ruby will occasionally print in scientific notation if the number is
      # small enough. That's technically valid CSS, but it's not well-supported
      # and confusing.
      str = ("%0.#{self.class.precision}f" % value).gsub(/0*$/, '') if str.include?('e')

      unitless? ? str : "#{str}#{unit_str}"
    end

Also aliased as: to_sass
int?() click to toggle source

@return [Boolean] Whether or not this number is an integer.

    # File lib/sass/script/value/number.rb, line 296
    def int?
      value % 1 == 0.0
    end

is_unit?(unit) click to toggle source

Checks whether the number has the numerator unit specified.

@example

    number = Sass::Script::Value::Number.new(10, "px")
    number.is_unit?("px") => true
    number.is_unit?(nil) => false

@param unit [::String, nil] The unit the number should have or nil if the number

    should be unitless.

@see #unitless? The unitless? method may be more readable.

    # File lib/sass/script/value/number.rb, line 315
    def is_unit?(unit)
      if unit
        denominator_units.size == 0 && numerator_units.size == 1 && numerator_units.first == unit
      else
        unitless?
      end
    end

legal_units?() click to toggle source

@return [Boolean] Whether or not this number has units that can be represented in CSS

    (that is, zero or one \{#numerator\_units}).

    # File lib/sass/script/value/number.rb, line 325
    def legal_units?
      (@numerator_units.empty? || @numerator_units.size == 1) && @denominator_units.empty?
    end

lt(other) click to toggle source

The SassScript `<` operation.

@param other [Number] The right-hand side of the operator @return [Boolean] Whether this number is less than the other @raise [NoMethodError] if `other` is an invalid type

    # File lib/sass/script/value/number.rb, line 243
    def lt(other)
      raise NoMethodError.new(nil, :lt) unless other.is_a?(Number)
      operate(other, :<)
    end

lte(other) click to toggle source

The SassScript `<=` operation.

@param other [Number] The right-hand side of the operator @return [Boolean] Whether this number is less than or equal to the other @raise [NoMethodError] if `other` is an invalid type

    # File lib/sass/script/value/number.rb, line 253
    def lte(other)
      raise NoMethodError.new(nil, :lte) unless other.is_a?(Number)
      operate(other, :<=)
    end

minus(other) click to toggle source

The SassScript binary `-` operation (e.g. `$a - $b`). Its functionality depends on the type of its argument:

{Number} : Subtracts this number from the other, converting units if possible.

{Value} : See {Value::Base#minus}.

@param other [Value] The right-hand side of the operator @return [Value] The result of the operation @raise [Sass::UnitConversionError] if `other` is a number with incompatible units

Calls superclass method Sass::Script::Value::Base#minus

    # File lib/sass/script/value/number.rb, line 106
    def minus(other)
      if other.is_a? Number
        operate(other, :-)
      else
        super
      end
    end

mod(other) click to toggle source

The SassScript `%` operation.

@param other [Number] The right-hand side of the operator @return [Number] This number modulo the other @raise [NoMethodError] if `other` is an invalid type @raise [Sass::UnitConversionError] if `other` has incompatible units

    # File lib/sass/script/value/number.rb, line 179
    def mod(other)
      if other.is_a?(Number)
        operate(other, :%)
      else
        raise NoMethodError.new(nil, :mod)
      end
    end

plus(other) click to toggle source

The SassScript `+` operation. Its functionality depends on the type of its argument:

{Number} : Adds the two numbers together, converting units if possible.

{Color} : Adds this number to each of the RGB color channels.

{Value} : See {Value::Base#plus}.

@param other [Value] The right-hand side of the operator @return [Value] The result of the operation @raise [Sass::UnitConversionError] if `other` is a number with incompatible units

Calls superclass method Sass::Script::Value::Base#plus

    # File lib/sass/script/value/number.rb, line 84
    def plus(other)
      if other.is_a? Number
        operate(other, :+)
      elsif other.is_a?(Color)
        other.plus(self)
      else
        super
      end
    end

times(other) click to toggle source

The SassScript `*` operation. Its functionality depends on the type of its argument:

{Number} : Multiplies the two numbers together, converting units appropriately.

{Color} : Multiplies each of the RGB color channels by this number.

@param other [Number, Color] The right-hand side of the operator @return [Number, Color] The result of the operation @raise [NoMethodError] if `other` is an invalid type

    # File lib/sass/script/value/number.rb, line 140
    def times(other)
      if other.is_a? Number
        operate(other, :*)
      elsif other.is_a? Color
        other.times(self)
      else
        raise NoMethodError.new(nil, :times)
      end
    end

to_i() click to toggle source

@return [Fixnum] The integer value of the number @raise [Sass::SyntaxError] if the number isn't an integer

Calls superclass method Sass::Script::Value::Base#to_i

    # File lib/sass/script/value/number.rb, line 290
    def to_i
      super unless int?
      value.to_i
    end

to_s(opts = {}) click to toggle source

@return [String] The CSS representation of this number @raise [Sass::SyntaxError] if this number has units that can't be used in CSS

    (e.g. `px*in`)

    # File lib/sass/script/value/number.rb, line 261
    def to_s(opts = {})
      return original if original
      raise Sass::SyntaxError.new("#{inspect} isn't a valid CSS value.") unless legal_units?
      inspect
    end

to_sass(opts = {})
Alias for: inspect
unary_minus() click to toggle source

The SassScript unary `-` operation (e.g. `-$a`).

@return [Number] The negative value of this number

    # File lib/sass/script/value/number.rb, line 124
    def unary_minus
      Number.new(-value, @numerator_units, @denominator_units)
    end

unary_plus() click to toggle source

The SassScript unary `+` operation (e.g. `+$a`).

@return [Number] The value of this number

    # File lib/sass/script/value/number.rb, line 117
    def unary_plus
      self
    end

unit_str() click to toggle source

Returns a human readable representation of the units in this number. For complex units this takes the form of: numerator_unit1 * numerator_unit2 / denominator_unit1 * denominator_unit2 @return [String] a string that represents the units in this number

    # File lib/sass/script/value/number.rb, line 367
    def unit_str
      rv = @numerator_units.sort.join("*")
      if @denominator_units.any?
        rv << "/"
        rv << @denominator_units.sort.join("*")
      end
      rv
    end

unitless?() click to toggle source

@return [Boolean] Whether or not this number has no units.

    # File lib/sass/script/value/number.rb, line 301
    def unitless?
      @numerator_units.empty? && @denominator_units.empty?
    end

### Private Instance Methods

coercion_factor(from_units, to_units) click to toggle source

    # File lib/sass/script/value/number.rb, line 411
    def coercion_factor(from_units, to_units)
      # get a list of unmatched units
      from_units, to_units = sans_common_units(from_units, to_units)

      if from_units.size != to_units.size || !convertable?(from_units | to_units)
        raise Sass::UnitConversionError.new(
          "Incompatible units: '#{from_units.join('*')}' and '#{to_units.join('*')}'.")
      end

      from_units.zip(to_units).inject(1) {|m, p| m * conversion_factor(p[0], p[1])}
    end

compute_units(this, other, operation) click to toggle source

    # File lib/sass/script/value/number.rb, line 423
    def compute_units(this, other, operation)
      case operation
      when :*
        [this.numerator_units + other.numerator_units,
         this.denominator_units + other.denominator_units]
      when :/
        [this.numerator_units + other.denominator_units,
         this.denominator_units + other.numerator_units]
      else
        [this.numerator_units, this.denominator_units]
      end
    end

conversion_factor(from_unit, to_unit) click to toggle source

    # File lib/sass/script/value/number.rb, line 506
    def conversion_factor(from_unit, to_unit)
      CONVERSION_TABLE[from_unit][to_unit]
    end

convertable?(units) click to toggle source

    # File lib/sass/script/value/number.rb, line 510
    def convertable?(units)
      units = Array(units).to_set
      return true if units.empty?
      return false unless (mutually_convertible = MUTUALLY_CONVERTIBLE[units.first])
      units.subset?(mutually_convertible)
    end

normalize!() click to toggle source

    # File lib/sass/script/value/number.rb, line 436
    def normalize!
      return if unitless?
      @numerator_units, @denominator_units =
        sans_common_units(@numerator_units, @denominator_units)

      @denominator_units.each_with_index do |d, i|
        if convertable?(d) && (u = @numerator_units.find(&method(:convertable?)))
          @value /= conversion_factor(d, u)
          @denominator_units.delete_at(i)
          @numerator_units.delete_at(@numerator_units.index(u))
        end
      end
    end

operate(other, operation) click to toggle source

    # File lib/sass/script/value/number.rb, line 391
    def operate(other, operation)
      this = self
      if OPERATIONS.include?(operation)
        if unitless?
          this = this.coerce(other.numerator_units, other.denominator_units)
        else
          other = other.coerce(@numerator_units, @denominator_units)
        end
      end
      # avoid integer division
      value = :/ == operation ? this.value.to_f : this.value
      result = value.send(operation, other.value)

      if result.is_a?(Numeric)
        Number.new(result, *compute_units(this, other, operation))
      else # Boolean op
        Bool.new(result)
      end
    end

sans_common_units(units1, units2) click to toggle source

    # File lib/sass/script/value/number.rb, line 517
    def sans_common_units(units1, units2)
      units2 = units2.dup
      # Can't just use -, because we want px*px to coerce properly to px*mm
      units1 = units1.map do |u|
        j = units2.index(u)
        next u unless j
        units2.delete_at(j)
        nil
      end
      units1.compact!
      return units1, units2
    end