class Numerals::Format

A Format object holds formatting options and performs formatted input/output operations on numbers.

Formatting options are grouped into aspects:

Some aspects (Rounding, Mode & Symbols) are handled with aspect-definining classes Rounding, Format::Mode and Format::Symbols.

Exact input applies only to numeric types that can hold limited precision values such as Float, Flt::Num or BigDecimal. It specifies that the numeric value is to be taken as an exact quantity. Otherwise, the numeric value is interpreted as a rounded approximation of some original exact value (so it represents a range of exact number which would all be rounded to the same approximation). Rational and Integer types are always exact and not affected by this option.

Rounding defines how numbers are rounded into text form or how values represented in text round to numeric values. So it specifies the precision of the result and whether the result is an approximation or an exact quantity.

Mode defines de formatting style.

Symbols contains the details of how digits and other symbols are represented in text form and the final text notation used.

The input-rounding property can set to either a Rounding object or just a rounding mode symbol (:half_even, etc.). It is used to define which rounding mode is implied when reading textual numeric expressions into approximate numeric values. It affects how approximate numbers are written to text because the text representation of approximate values should be read back into the original value. If a Rounding object is assigned only the mode is used, and it is ignored if the rounding is exact. #

Attributes

exact_input[R]
input_rounding[R]
mode[R]
notation[R]
rounding[R]
symbols[R]

Public Class Methods

<<(*args) click to toggle source
# File lib/numerals/format/sugar.rb, line 4
def self.<<(*args)
  Format[].<<(*args)
end
>>(*args) click to toggle source
# File lib/numerals/format/sugar.rb, line 8
def self.>>(*args)
  Format[].>>(*args)
end
assemble(id, output, format, text_parts) click to toggle source
# File lib/numerals/format/notation.rb, line 37
def self.assemble(id, output, format, text_parts)
  notation(id, format).assemble(output, text_parts)
end
define_notation(id, notation_class) click to toggle source
# File lib/numerals/format/notation.rb, line 25
def self.define_notation(id, notation_class)
  unless notation_class.class == Class && notation_class.superclass == Notation
    raise "Notation class must be derived from Format::Notation"
  end
  @notations[id] = notation_class
end
disassemble(id, format, text) click to toggle source
# File lib/numerals/format/notation.rb, line 41
def self.disassemble(id, format, text)
  notation(id, format).disassemble(text)
end
new(*args) click to toggle source
# File lib/numerals/format/format.rb, line 46
def initialize(*args)
  @exact_input = false
  @rounding = Rounding[:short]
  @mode = Mode[]
  @symbols = Symbols[]
  @notation = :text
  @input_rounding = nil
  set! *args
end
notation(id, format) click to toggle source
# File lib/numerals/format/notation.rb, line 32
def self.notation(id, format)
  @notations[id].new(format) || raise("Unknown notation #{id.inspect}")
end

Public Instance Methods

<<(*args) click to toggle source
# File lib/numerals/format/sugar.rb, line 12
def <<(*args)
  FormattingStream[self].<<(*args)
end
>>(*args) click to toggle source
# File lib/numerals/format/sugar.rb, line 16
def >>(*args)
  FormattingStream[self].>>(*args)
end
base() click to toggle source
# File lib/numerals/format/format.rb, line 59
def base
  @rounding.base
end
case_sensitive?() click to toggle source
# File lib/numerals/format/format.rb, line 134
def case_sensitive?
  @symbols.case_sensitive?
end
dup() click to toggle source
# File lib/numerals/format/format.rb, line 182
def dup
  # we need deep copy
  Format[parameters]
end
input_rounding?() click to toggle source
# File lib/numerals/format/format.rb, line 78
def input_rounding?
  !@input_rounding.nil?
end
input_rounding_mode() click to toggle source
# File lib/numerals/format/format.rb, line 82
def input_rounding_mode
  input_rounding? ? @input_rounding.mode : nil
end
inspect() click to toggle source
# File lib/numerals/format/format.rb, line 130
def inspect
  to_s
end
padded?() click to toggle source
# File lib/numerals/format/format.rb, line 67
def padded?
  padding.padded?
end
padding() click to toggle source
# File lib/numerals/format/format.rb, line 63
def padding
  @symbols.padding
end
parameters() click to toggle source
# File lib/numerals/format/format.rb, line 108
def parameters
  {
    rounding: @rounding,
    exact_input: @exact_input,
    mode: @mode,
    symbols: @symbols,
    notation: @notation,
    input_rounding: input_rounding? ? @input_rounding : nil
  }
end
significand_base() click to toggle source

Presentation base for the significand

# File lib/numerals/format/format.rb, line 72
def significand_base
  base**@mode.base_scale
end
to_s() click to toggle source
# File lib/numerals/format/format.rb, line 119
def to_s
  args = []
  args << "exact_input: true" if @exact_input
  args << "rounding: #{@rounding}"
  args << "mode: #{@mode}"
  args << "symbols: #{@symbols}"
  args << "notation: #{@notation.inspect}" if @notation != :text
  args << "input_rounding: #{input_rounding_mode.inspect}" if input_rounding?
  "Format[#{args.join(', ')}]"
end

Private Instance Methods

extract_options(*args) click to toggle source
# File lib/numerals/format/format.rb, line 222
def extract_options(*args)
  options = {}
  args = args.first if args.size == 1 && args.first.kind_of?(Array)
  args.each do |arg|
    case arg
    when Hash
      options.merge! arg
    when Rounding
      options[:rounding] = arg
    when Mode
      options[:mode] = arg
    when Symbols
      options[:symbols] = arg
    when Symbols::Digits
      options[:digits] = arg
    when Symbols::Padding
      options[:padding] = arg
    when Format
      options.merge! arg.parameters
    when :exact_input
      options[:exact_input] = true
    when :hexbin
      options.merge!(
        base: 2,
        mode: {
          base_scale: 4,
          mode: :scientific,
          sci_int_digits: 1
        },
        symbols: {
          exponent: 'p', base_prefix: '0x'
        }
      )
    when :gen, :general, :sci, :scientific, :fix; :fixed
      options[:mode] = Mode[arg]
    when :short, :free, :simplify, :preserve
      options[:precision] = arg
    when  :half_even, :half_down, :half_up, :down, :up, :ceiling, :floor, :up05
      options[:rounding_mode] = arg
    when :case_sensitive
      options[:case_sensitive] = true
    when Symbol
      options[:notation] = arg
    when Integer
      options[:base] = arg
    else
      raise "Invalid Format definition"
    end
  end
  options
end