class SassC::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

epsilon() click to toggle source

Used in checking equality of floating point numbers. Any numbers within an ‘epsilon` of each other are considered functionally equal. The value for epsilon is one tenth of the current numeric precision.

# File lib/sassc/script/value/number.rb, line 63
def self.epsilon
  Thread.current[:sass_numeric_epsilon] ||= 1 / (precision_factor * 10)
end
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 SassC::Script::Value::new
# File lib/sassc/script/value/number.rb, line 73
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
  @options = nil
  normalize!
end
precision() click to toggle source
# File lib/sassc/script/value/number.rb, line 39
def self.precision
  Thread.current[:sass_numeric_precision] || Thread.main[:sass_numeric_precision] || 10
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`. The numeric precision is stored as a thread local for thread safety reasons. To set for all threads, be sure to set the precision on the main thread.

# File lib/sassc/script/value/number.rb, line 48
def self.precision=(digits)
  Thread.current[:sass_numeric_precision] = digits.round
  Thread.current[:sass_numeric_precision_factor] = nil
  Thread.current[:sass_numeric_epsilon] = nil
end
precision_factor() click to toggle source

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

# File lib/sassc/script/value/number.rb, line 56
def self.precision_factor
  Thread.current[:sass_numeric_precision_factor] ||= 10.0**precision
end

Private Class Methods

basically_equal?(num1, num2) click to toggle source

Checks whether two numbers are within an epsilon of each other. @return [Boolean]

# File lib/sassc/script/value/number.rb, line 233
def self.basically_equal?(num1, num2)
  (num1 - num2).abs < epsilon
end
round(num) click to toggle source

@private

# File lib/sassc/script/value/number.rb, line 238
def self.round(num)
  if num.is_a?(Float) && (num.infinite? || num.nan?)
    num
  elsif basically_equal?(num % 1, 0.0)
    num.round
  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/sassc/script/value/number.rb, line 192
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/sassc/script/value/number.rb, line 203
def comparable_to?(other)
  operate(other, :+)
  true
rescue Sass::UnitConversionError
  false
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/sassc/script/value/number.rb, line 90
def eql?(other)
  basically_equal?(value, other.value) && numerator_units == other.numerator_units &&
    denominator_units == other.denominator_units
end
hash() click to toggle source
# File lib/sassc/script/value/number.rb, line 83
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/sassc/script/value/number.rb, line 110
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')

  # Sometimes numeric formatting will result in a decimal number with a trailing zero (x.0)
  if str =~ /(.*)\.0$/
    str = $1
  end

  # We omit a leading zero before the decimal point in compressed mode.
  if @options && options[:style] == :compressed
    str.sub!(/^(-)?0\./, '\1.')
  end

  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/sassc/script/value/number.rb, line 143
def int?
  basically_equal?(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 Number#unitless? The unitless? method may be more readable.

# File lib/sassc/script/value/number.rb, line 162
def is_unit?(unit)
  if unit
    denominator_units.size == 0 && numerator_units.size == 1 && numerator_units.first == unit
  else
    unitless?
  end
end
to_i() click to toggle source

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

Calls superclass method SassC::Script::Value#to_i
# File lib/sassc/script/value/number.rb, line 137
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/sassc/script/value/number.rb, line 98
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
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/sassc/script/value/number.rb, line 214
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/sassc/script/value/number.rb, line 148
def unitless?
  @numerator_units.empty? && @denominator_units.empty?
end

Private Instance Methods

basically_equal?(num1, num2) click to toggle source

@private @see Sass::Script::Number.basically_equal?

# File lib/sassc/script/value/number.rb, line 227
def basically_equal?(num1, num2)
  self.class.basically_equal?(num1, num2)
end
coercion_factor(from_units, to_units) click to toggle source
# File lib/sassc/script/value/number.rb, line 270
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/sassc/script/value/number.rb, line 282
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/sassc/script/value/number.rb, line 365
def conversion_factor(from_unit, to_unit)
  CONVERSION_TABLE[from_unit][to_unit]
end
convertable?(units) click to toggle source
# File lib/sassc/script/value/number.rb, line 369
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/sassc/script/value/number.rb, line 295
def normalize!
  return if unitless?
  @numerator_units, @denominator_units =
    sans_common_units(@numerator_units, @denominator_units)

  @denominator_units.each_with_index do |d, i|
    next unless convertable?(d) && (u = @numerator_units.find {|n| convertable?([n, d])})
    @value /= conversion_factor(d, u)
    @denominator_units.delete_at(i)
    @numerator_units.delete_at(@numerator_units.index(u))
  end
end
operate(other, operation) click to toggle source
# File lib/sassc/script/value/number.rb, line 250
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/sassc/script/value/number.rb, line 376
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