Class: BSON::Decimal128

Inherits:
Object
  • Object
show all
Includes:
JSON, Comparable
Defined in:
lib/bson/decimal128.rb,
lib/bson/decimal128/builder.rb

Defined Under Namespace

Modules: Builder

Constant Summary collapse

BSON_TYPE =

A Decimal128 is type 0x13 in the BSON spec.

Since:

  • 4.2.0

::String.new(19.chr, encoding: BINARY).freeze
EXPONENT_OFFSET =

Exponent offset.

Since:

  • 4.2.0

6176
MIN_EXPONENT =

Minimum exponent.

Since:

  • 4.2.0

-6176
MAX_EXPONENT =

Maximum exponent.

Since:

  • 4.2.0

6111
MAX_DIGITS_OF_PRECISION =

Maximum digits of precision.

Since:

  • 4.2.0

34
EXTENDED_JSON_KEY =

Key for this type when converted to extended json.

Since:

  • 4.2.0

"$numberDecimal"
NATIVE_TYPE =

The native type to which this object can be converted.

Since:

  • 4.2.0

BigDecimal

Class Method Summary collapse

Instance Method Summary collapse

Methods included from JSON

#to_json

Constructor Details

#initialize(object) ⇒ Decimal128

Create a new Decimal128 from a string or a BigDecimal instance.

Examples:

Create a Decimal128 from a BigDecimal.

Decimal128.new(big_decimal)

Parameters:

  • object (String, BigDecimal) —

    The BigDecimal or String to use for instantiating a Decimal128.

Raises:

Since:

  • 4.2.0



123
124
125
126
127
128
129
130
131
 
# File 'lib/bson/decimal128.rb', line 123

def initialize(object)
  if object.is_a?(String)
    set_bits(*Builder::FromString.new(object).bits)
  elsif object.is_a?(BigDecimal)
    set_bits(*Builder::FromBigDecimal.new(object).bits)
  else
    raise Error::InvalidDecimal128Argument.new
  end
end

Class Method Details

.from_bits(low, high) ⇒ BSON::Decimal128

Instantiate a Decimal128 from high and low bits.

Examples:

Create a Decimal128 from high and low bits.

BSON::Decimal128.from_bits(high, low)

Parameters:

  • high (Integer) —

    The high order bits.

  • low (Integer) —

    The low order bits.

Returns:

Since:

  • 4.2.0



265
266
267
268
269
 
# File 'lib/bson/decimal128.rb', line 265

def from_bits(low, high)
  decimal = allocate
  decimal.send(:set_bits, low, high)
  decimal
end

.from_bson(buffer, **options) ⇒ BSON::Decimal128

Deserialize the decimal128 from raw BSON bytes.

Examples:

Get the decimal128 from BSON.

Decimal128.from_bson(bson)

Parameters:

  • buffer (ByteBuffer) —

    The byte buffer.

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :mode (nil | :bson) —

    Decoding mode to use.

Returns:

Since:

  • 4.2.0



234
235
236
 
# File 'lib/bson/decimal128.rb', line 234

def from_bson(buffer, **options)
  from_bits(*buffer.get_decimal128_bytes.unpack('Q<*'))
end

.from_string(string) ⇒ BSON::Decimal128

Instantiate a Decimal128 from a string.

Examples:

Create a Decimal128 from a string.

BSON::Decimal128.from_string("1.05E+3")

Parameters:

  • string (String) —

    The string to parse.

Returns:

Raises:

  • (BSON::Error:InvalidDecimal128String) —

    If the provided string is invalid.

Since:

  • 4.2.0



250
251
252
 
# File 'lib/bson/decimal128.rb', line 250

def from_string(string)
  from_bits(*Builder::FromString.new(string).bits)
end

Instance Method Details

#<=>(other) ⇒ Object 



103
104
105
106
107
108
109
110
 
# File 'lib/bson/decimal128.rb', line 103

def <=>(other)
  to_d <=> case other
    when Decimal128
      other.to_d
    else
      other
    end
end

#==(other) ⇒ true, false Also known as: eql?

Check equality of the decimal128 object with another object.

Examples:

Check if the decimal128 object is equal to the other.

decimal == other

Parameters:

  • other (Object) —

    The object to check against.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 4.2.0



96
97
98
99
100
 
# File 'lib/bson/decimal128.rb', line 96

def ==(other)
  return false unless other.is_a?(Decimal128)
  @high == other.instance_variable_get(:@high) &&
      @low == other.instance_variable_get(:@low)
end

#as_extended_json(**_options) ⇒ Hash

Converts this object to a representation directly serializable to Extended JSON (github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).

Parameters:

  • opts (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    The extended json representation.



82
83
84
 
# File 'lib/bson/decimal128.rb', line 82

def as_extended_json(**_options)
  { EXTENDED_JSON_KEY => to_s }
end

#as_json(*args) ⇒ String | nil

Return a string representation of the Decimal128 use in standard application-level JSON serialization. Returns nil for non-real numbers such as NaN and Infinity to be compatible with ActiveSupport. This method is intentionally different from #as_extended_json.

Examples:

Get the Decimal128 as a JSON-serializable object.

decimal.as_json

Returns:

  • (String | nil) —

    The decimal128 as a String or nil for non-representable numbers.



70
71
72
73
 
# File 'lib/bson/decimal128.rb', line 70

def as_json(*args)
  value = to_s
  value unless %w[NaN Infinity -Infinity].include?(value)
end

#bson_type ⇒ Object

Get the BSON type for Decimal128.



134
135
136
 
# File 'lib/bson/decimal128.rb', line 134

def bson_type
  BSON_TYPE
end

#hash ⇒ Integer

Get the hash value for the decimal128.

Examples:

Get the hash value.

decimal.hash

Returns:

Since:

  • 4.2.0



160
161
162
163
164
 
# File 'lib/bson/decimal128.rb', line 160

def hash
  num = @high << 64
  num |= @low
  num.hash
end

#inspect ⇒ String

Get a nice string for use with object inspection.

Examples:

Inspect the decimal128 object.

decimal128.inspect

Returns:

  • (String) —

    The decimal as a string.

Since:

  • 4.2.0



174
175
176
 
# File 'lib/bson/decimal128.rb', line 174

def inspect
  "BSON::Decimal128('#{to_s}')"
end

#to_bson(buffer = ByteBuffer.new) ⇒ BSON::ByteBuffer

Get the decimal128 as its raw BSON data.

Examples:

Get the raw bson bytes in a buffer.

decimal.to_bson

Returns:

See Also:

Since:

  • 4.2.0



148
149
150
 
# File 'lib/bson/decimal128.rb', line 148

def to_bson(buffer = ByteBuffer.new)
  buffer.put_decimal128(@low, @high)
end

#to_d ⇒ BigDecimal Also known as: to_big_decimal

Get a Ruby BigDecimal object corresponding to this Decimal128. Note that, when converting to a Ruby BigDecimal, non-zero significant digits are preserved but trailing zeroes may be lost. See the following example:

Note that the the BSON::Decimal128 object can represent -NaN, sNaN, and -sNaN while Ruby’s BigDecimal cannot.

Examples:

decimal128 = BSON::Decimal128.new("0.200")
  => BSON::Decimal128('0.200')
big_decimal = decimal128.to_d
  => #<BigDecimal:7fc619c95388,'0.2E0',9(18)>
big_decimal.to_s
  => "0.2E0"

Returns:



208
209
210
 
# File 'lib/bson/decimal128.rb', line 208

def to_d
  @big_decimal ||= BigDecimal(to_s)
end

#to_s ⇒ String Also known as: to_str

Get the string representation of the decimal128.

Examples:

Get the decimal128 as a string.

decimal128.to_s

Returns:

  • (String) —

    The decimal128 as a string.

Since:

  • 4.2.0



186
187
188
 
# File 'lib/bson/decimal128.rb', line 186

def to_s
  @string ||= Builder::ToString.new(self).string
end