Module: BSON::Integer

Defined in:
lib/bson/integer.rb

Overview

Injects behaviour for encoding and decoding integer values to and from raw bytes as specified by the BSON spec.

See Also:

Since:

  • 2.0.0

Constant Summary collapse

MAX_32BIT =

The maximum 32 bit integer value.

Since:

  • 2.0.0

(1 << 31) - 1
MAX_64BIT =

The maximum 64 bit integer value.

Since:

  • 2.0.0

(1 << 63) - 1
MIN_32BIT =

The minimum 32 bit integer value.

Since:

  • 2.0.0

-(1 << 31)
MIN_64BIT =

The minimum 64 bit integer value.

Since:

  • 2.0.0

-(1 << 63)
BSON_INDEX_SIZE =

The BSON index size.

Since:

  • 2.0.0

1024.freeze
BSON_ARRAY_INDEXES =

A hash of index values for array optimization.

Since:

  • 2.0.0

::Array.new(BSON_INDEX_SIZE) do |i|
  (i.to_s.force_encoding(BINARY) << NULL_BYTE).freeze
end.freeze

Instance Method Summary collapse

Instance Method Details

#as_extended_json(**options) ⇒ Hash | Integer

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

This method returns the integer itself if relaxed representation is requested, otherwise a $numberInt hash if the value fits in 32 bits and a $numberLong otherwise. Regardless of which representation is requested, a value that does not fit in 64 bits raises RangeError.

Parameters:

  • opts (Hash)

    a customizable set of options

Returns:

  • (Hash | Integer)

    The extended json representation.

Since:

  • 2.0.0


174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# File 'lib/bson/integer.rb', line 174

def as_extended_json(**options)
  # The behavior of native integers' serialization to extended json is
  # not specified. Following our bson serialization logic in this file,
  # produce explicit $numberInt or $numberLong, choosing $numberInt if
  # the integer fits in 32 bits. In Ruby integers can be arbitrarily
  # big; integers that do not fit into 64 bits raise an error as we do not
  # want to silently perform an effective type conversion of integer ->
  # decimal.

  unless bson_int64?
    raise RangeError, "Integer #{self} is too big to be represented as a MongoDB integer"
  end

  if options[:mode] == :relaxed || options[:mode] == :legacy
    self
  elsif bson_int32?
    {'$numberInt' => to_s}
  else
    {'$numberLong' => to_s}
  end
end

#bson_int32?true, false

Is this integer a valid BSON 32 bit value?

Examples:

Is the integer a valid 32 bit value?

1024.bson_int32?

Returns:

  • (true, false)

    If the integer is 32 bit.

Since:

  • 2.0.0


65
66
67
# File 'lib/bson/integer.rb', line 65

def bson_int32?
  (MIN_32BIT <= self) && (self <= MAX_32BIT)
end

#bson_int64?true, false

Is this integer a valid BSON 64 bit value?

Examples:

Is the integer a valid 64 bit value?

1024.bson_int64?

Returns:

  • (true, false)

    If the integer is 64 bit.

Since:

  • 2.0.0


77
78
79
# File 'lib/bson/integer.rb', line 77

def bson_int64?
  (MIN_64BIT <= self) && (self <= MAX_64BIT)
end

#bson_typeString

Get the BSON type for this integer. Will depend on whether the integer is 32 bit or 64 bit.

Examples:

Get the BSON type for the integer.

1024.bson_type

Returns:

  • (String)

    The single byte BSON type.

See Also:

Since:

  • 2.0.0


92
93
94
# File 'lib/bson/integer.rb', line 92

def bson_type
  bson_int32? ? Int32::BSON_TYPE : (bson_int64? ? Int64::BSON_TYPE : out_of_range!)
end

#to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?) ⇒ BSON::ByteBuffer

Get the integer as encoded BSON.

Examples:

Get the integer as encoded BSON.

1024.to_bson

Returns:

See Also:

Since:

  • 2.0.0


106
107
108
109
110
111
112
113
114
# File 'lib/bson/integer.rb', line 106

def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
  if bson_int32?
    buffer.put_int32(self)
  elsif bson_int64?
    buffer.put_int64(self)
  else
    out_of_range!
  end
end

#to_bson_int32(encoded) ⇒ String

Convert the integer to a 32 bit (4 bytes) raw bytes string.

Examples:

Convert the integer to it's 32 bit bytes.

1024.to_bson_int32

Parameters:

  • encoded (String)

    The string to encode to.

Returns:

  • (String)

    The encoded string.

Since:

  • 2.0.0


126
127
128
# File 'lib/bson/integer.rb', line 126

def to_bson_int32(encoded)
  append_bson_int32(encoded)
end

#to_bson_int64(encoded) ⇒ String

Convert the integer to a 64 bit (8 bytes) raw bytes string.

Examples:

Convert the integer to it's 64 bit bytes.

1024.to_bson_int64

Parameters:

  • encoded (String)

    The string to encode to.

Returns:

  • (String)

    The encoded string.

Since:

  • 2.0.0


140
141
142
143
144
145
146
# File 'lib/bson/integer.rb', line 140

def to_bson_int64(encoded)
  append_bson_int32(encoded)
  encoded << ((self >> 32) & 255)
  encoded << ((self >> 40) & 255)
  encoded << ((self >> 48) & 255)
  encoded << ((self >> 56) & 255)
end

#to_bson_key(validating_keys = Config.validating_keys?) ⇒ String

Convert the integer to a BSON string key.

Examples:

Convert the integer to a BSON key string.

1.to_bson_key

Parameters:

  • validating_keys (true, false) (defaults to: Config.validating_keys?)

    If BSON should validate the key.

Returns:

  • (String)

    The string key.

Since:

  • 2.0.0


158
159
160
# File 'lib/bson/integer.rb', line 158

def to_bson_key(validating_keys = Config.validating_keys?)
  self
end