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
A list of units in the denominator of the number. For example, ‘1px*em/in*cm` would return `[“in”, “cm”]` @return [Array<String>]
A list of units in the numerator of the number. For example, ‘1px*em/in*cm` would return `[“px”, “em”]` @return [Array<String>]
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]
The Ruby value of the number.
@return [Numeric]
Public Class Methods
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
@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}
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
# File lib/sassc/script/value/number.rb, line 39 def self.precision Thread.current[:sass_numeric_precision] || Thread.main[:sass_numeric_precision] || 10 end
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
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
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
@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
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
@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
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
# File lib/sassc/script/value/number.rb, line 83 def hash [value, numerator_units, denominator_units].hash end
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
@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
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
@return [Boolean] Whether or not this number has units that can be represented in CSS
(that is, zero or one \{#numerator\_units}).
# File lib/sassc/script/value/number.rb, line 172 def legal_units? (@numerator_units.empty? || @numerator_units.size == 1) && @denominator_units.empty? end
@return [Integer] The integer value of the number @raise [Sass::SyntaxError] if the number isn’t an integer
SassC::Script::Value#to_i
# File lib/sassc/script/value/number.rb, line 137 def to_i super unless int? value.to_i end
@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
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
@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
@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
# 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
# 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
# File lib/sassc/script/value/number.rb, line 365 def conversion_factor(from_unit, to_unit) CONVERSION_TABLE[from_unit][to_unit] end
# 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
# 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
# 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
# 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