bson 4.1.1 → 5.2.0

data/lib/bson/decimal128.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2016-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'bigdecimal'
+require 'bson/decimal128/builder'
+
+module BSON
+
+  class Decimal128
+    include JSON
+    include Comparable
+
+    # A Decimal128 is type 0x13 in the BSON spec.
+    #
+    # @since 4.2.0
+    BSON_TYPE = ::String.new(19.chr, encoding: BINARY).freeze
+
+    # Exponent offset.
+    #
+    # @since 4.2.0
+    EXPONENT_OFFSET = 6176
+
+    # Minimum exponent.
+    #
+    # @since 4.2.0
+    MIN_EXPONENT = -6176
+
+    # Maximum exponent.
+    #
+    # @since 4.2.0
+    MAX_EXPONENT = 6111
+
+    # Maximum digits of precision.
+    #
+    # @since 4.2.0
+    MAX_DIGITS_OF_PRECISION = 34
+
+    # Key for this type when converted to extended json.
+    #
+    # @since 4.2.0
+    EXTENDED_JSON_KEY = "$numberDecimal"
+
+    # The native type to which this object can be converted.
+    #
+    # @since 4.2.0
+    NATIVE_TYPE = BigDecimal
+
+    # 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.
+    #
+    # @example Get the Decimal128 as a JSON-serializable object.
+    #   decimal.as_json
+    #
+    # @return [ String | nil ] The decimal128 as a String or nil for non-representable numbers.
+    def as_json(*args)
+      value = to_s
+      value unless %w[NaN Infinity -Infinity].include?(value)
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**_options)
+      { EXTENDED_JSON_KEY => to_s }
+    end
+
+    # Check equality of the decimal128 object with another object.
+    #
+    # @example Check if the decimal128 object is equal to the other.
+    #   decimal == other
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 4.2.0
+    def ==(other)
+      return false unless other.is_a?(Decimal128)
+      @high == other.instance_variable_get(:@high) &&
+          @low == other.instance_variable_get(:@low)
+    end
+    alias :eql? :==
+
+    def <=>(other)
+      to_d <=> case other
+        when Decimal128
+          other.to_d
+        else
+          other
+        end
+    end
+
+    # Create a new Decimal128 from a string or a BigDecimal instance.
+    #
+    # @example Create a Decimal128 from a BigDecimal.
+    #   Decimal128.new(big_decimal)
+    #
+    # @param [ String, BigDecimal ] object The BigDecimal or String to use for
+    #   instantiating a Decimal128.
+    #
+    # @raise [ BSON::Error::InvalidDecimal128Argument ] When argument is not a String or BigDecimal.
+    #
+    # @since 4.2.0
+    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
+
+    # Get the BSON type for Decimal128.
+    def bson_type
+      BSON_TYPE
+    end
+
+    # Get the decimal128 as its raw BSON data.
+    #
+    # @example Get the raw bson bytes in a buffer.
+    #   decimal.to_bson
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 4.2.0
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_decimal128(@low, @high)
+    end
+
+    # Get the hash value for the decimal128.
+    #
+    # @example Get the hash value.
+    #   decimal.hash
+    #
+    # @return [ Integer ] The hash value.
+    #
+    # @since 4.2.0
+    def hash
+      num = @high << 64
+      num |= @low
+      num.hash
+    end
+
+    # Get a nice string for use with object inspection.
+    #
+    # @example Inspect the decimal128 object.
+    #   decimal128.inspect
+    #
+    # @return [ String ] The decimal as a string.
+    #
+    # @since 4.2.0
+    def inspect
+      "BSON::Decimal128('#{to_s}')"
+    end
+
+    # Get the string representation of the decimal128.
+    #
+    # @example Get the decimal128 as a string.
+    #   decimal128.to_s
+    #
+    # @return [ String ] The decimal128 as a string.
+    #
+    # @since 4.2.0
+    def to_s
+      @string ||= Builder::ToString.new(self).string
+    end
+    alias :to_str :to_s
+
+    # 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:
+    #
+    # @example
+    #  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"
+    #
+    # Note that the the BSON::Decimal128 object can represent -NaN, sNaN,
+    # and -sNaN while Ruby's BigDecimal cannot.
+    #
+    # @return [ BigDecimal ] The decimal as a BigDecimal.
+    def to_d
+      @big_decimal ||= BigDecimal(to_s)
+    end
+    alias :to_big_decimal :to_d
+
+    private
+
+    def set_bits(low, high)
+      @low = low
+      @high = high
+    end
+
+    class << self
+
+      # Deserialize the decimal128 from raw BSON bytes.
+      #
+      # @example Get the decimal128 from BSON.
+      #   Decimal128.from_bson(bson)
+      #
+      # @param [ ByteBuffer ] buffer The byte buffer.
+      #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
+      # @return [ BSON::Decimal128 ] The decimal object.
+      #
+      # @since 4.2.0
+      def from_bson(buffer, **options)
+        from_bits(*buffer.get_decimal128_bytes.unpack('Q<*'))
+      end
+
+      # Instantiate a Decimal128 from a string.
+      #
+      # @example Create a Decimal128 from a string.
+      #   BSON::Decimal128.from_string("1.05E+3")
+      #
+      # @param [ String ] string The string to parse.
+      #
+      # @raise [ BSON::Error:InvalidDecimal128String ] If the provided string is invalid.
+      #
+      # @return [ BSON::Decimal128 ] The new decimal128.
+      #
+      # @since 4.2.0
+      def from_string(string)
+        from_bits(*Builder::FromString.new(string).bits)
+      end
+
+      # Instantiate a Decimal128 from high and low bits.
+      #
+      # @example Create a Decimal128 from high and low bits.
+      #   BSON::Decimal128.from_bits(high, low)
+      #
+      # @param [ Integer ] high The high order bits.
+      # @param [ Integer ] low The low order bits.
+      #
+      # @return [ BSON::Decimal128 ] The new decimal128.
+      #
+      # @since 4.2.0
+      def from_bits(low, high)
+        decimal = allocate
+        decimal.send(:set_bits, low, high)
+        decimal
+      end
+    end
+  end
+end

data/lib/bson/document.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -35,8 +37,43 @@ module BSON
   class Document < ::Hash
 
     # Get a value from the document for the provided key. Can use string or
-    # symbol access, but the fastest will be to always provide a key that is of
-    # the same type as the stored keys.
+    # symbol access, with string access being the faster of the two.
+    #
+    # @overload fetch(key)
+    #   Returns a value from the hash for the given key. If the key does
+    #   not exist, raises KeyError exception.
+    #
+    # @overload fetch(key, default)
+    #   Returns a value from the hash for the given key. If the key does not
+    #   exist, returns *default*.
+    #
+    # @overload fetch(key, &block)
+    #   Returns a value from the hash for the given key. If the key does not
+    #   exist, returns the value of the block called with the key.
+    #
+    # @example Get an element for the key.
+    #   document.fetch("field")
+    #
+    # @example Get an element for the key by symbol with a default.
+    #   document.fetch(:field, 'foo')
+    #
+    # @example Get an element for the key by symbol with a block default.
+    #   document.fetch(:field) { |key| key.upcase }
+    #
+    # @param [ String, Symbol ] key The key to look up.
+    # @param [ Object ] default Returned value if key does not exist.
+    # @yield [key] Block returning default value for the given key.
+    #
+    # @return [ Object ] The found value. Raises KeyError if none found.
+    #
+    # @since 4.4.0
+    def fetch(key, *args, &block)
+      key = convert_key(key)
+      super(key, *args, &block)
+    end
+
+    # Get a value from the document for the provided key. Can use string or
+    # symbol access, with string access being the faster of the two.
     #
     # @example Get an element for the key.
     #   document["field"]
@@ -44,7 +81,7 @@ module BSON
     # @example Get an element for the key by symbol.
     #   document[:field]
     #
-    # @param [ String, Symbol ] key The key to lookup.
+    # @param [ String, Symbol ] key The key to look up.
     #
     # @return [ Object ] The found value, or nil if none found.
     #
@@ -53,7 +90,49 @@ module BSON
       super(convert_key(key))
     end
 
-    # Set a value on the document. Will normalize symbol keys into strings.
+    # Stores a key-value pair in the current document.
+    #
+    # Since BSON documents provide deep indifferent access (both strings and
+    # symbols are accepted as keys, recursively), the value may be converted
+    # to facilitate indifferent access. This conversion is performed for
+    # built-in Array and Hash classes, and other classes can override
+    # +to_bson_normalized_value+ method to provide custom conversion logic.
+    # For example:
+    #
+    #     doc = BSON::Document.new
+    #     doc[:a] = {b: {c: 'd'}}
+    #     doc['a']['b']['c']
+    #     # => "d"
+    #
+    # Note that due to this conversion, the object that is stored in the
+    # receiver Document may be different from the object supplied as the
+    # right hand side of the assignment. In Ruby, the result of assignment
+    # is the right hand side, not the return value of []= method.
+    # Because of this, modifying the result of assignment generally does not
+    # work as intended:
+    #
+    #     doc = BSON::Document.new
+    #     foo = (doc[:a] = {b: {c: 'd'}})
+    #     # foo is original Hash with symbol keys
+    #     foo['test'] = 'test'
+    #     # doc is not modified
+    #     doc
+    #     # => {"a"=>{"b"=>{"c"=>"d"}}}
+    #
+    # This behavior can be encountered when defaulting document contents with
+    # []= in a method, such as:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation
+    #     end
+    #
+    # The above method should be written as follows to allow chaining:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation and @doc[:foo]
+    #     end
     #
     # @example Set a value on the document.
     #   document[:test] = "value"
@@ -144,7 +223,7 @@ module BSON
     #
     # @param [ BSON::Document, Hash ] other The document/hash to merge with.
     #
-    # @eturn [ BSON::Document ] The result of the merge.
+    # @return [ BSON::Document ] The result of the merge.
     #
     # @since 3.0.0
     def merge(other, &block)
@@ -159,7 +238,7 @@ module BSON
     #
     # @param [ BSON::Document, Hash ] other The document/hash to merge with.
     #
-    # @eturn [ BSON::Document ] The result of the merge.
+    # @return [ BSON::Document ] The result of the merge.
     #
     # @since 3.0.0
     def merge!(other)
@@ -172,6 +251,97 @@ module BSON
 
     alias :update :merge!
 
+    if instance_methods.include?(:dig)
+      # Retrieves the value object corresponding to the each key objects repeatedly.
+      # Will normalize symbol keys into strings.
+      #
+      # @example Get value from nested sub-documents, handling missing levels.
+      #   document # => { :key1 => { "key2" => "value"}}
+      #   document.dig(:key1, :key2) # => "value"
+      #   document.dig("key1", "key2") # => "value"
+      #   document.dig("foo", "key2") # => nil
+      #
+      # @param [ Array<String, Symbol> ] *keys Keys, which constitute a "path" to the nested value.
+      #
+      # @return [ Object, NilClass ] The requested value or nil.
+      #
+      # @since 3.0.0
+      def dig(*keys)
+        super(*keys.map{|key| convert_key(key)})
+      end
+    end
+
+    # Slices a document to include only the given keys.
+    # Will normalize symbol keys into strings.
+    # (this method is backported from ActiveSupport::Hash)
+    #
+    # @example Get a document/hash with only the `name` and `age` fields present
+    #   document # => { _id: <ObjectId>, :name => "John", :age => 30, :location => "Earth" }
+    #   document.slice(:name, 'age') # => { "name": "John", "age" => 30 }
+    #   document.slice('name') # => { "name" => "John" }
+    #   document.slice(:foo) # => {}
+    #
+    # @param [ Array<String, Symbol> ] *keys Keys, that will be kept in the resulting document
+    #
+    # @return [ BSON::Document ] The document with only the selected keys
+    #
+    # @since 4.3.1
+    def slice(*keys)
+      keys.each_with_object(self.class.new) do |key, hash|
+        if key?(key)
+          hash[key] = self[key]
+        end
+      end
+    end
+
+    # Returns a new document consisting of the current document minus the
+    # specified keys.
+    #
+    # The keys to be removed can be specified as either strings or symbols.
+    #
+    # @example Get a document/hash with only the `name` and `age` fields removed
+    #   document # => { _id: <ObjectId>, :name => 'John', :age => 30, :location => 'Earth' }
+    #   document.except(:name, 'age') # => { _id: <ObjectId>, location: 'Earth' }
+    #
+    # @param [ Array<String, Symbol> ] *keys Keys, that will be removed in the resulting document
+    #
+    # @return [ BSON::Document ] The document with the specified keys removed.
+    #
+    # @note This method is always defined, even if Hash already contains a
+    #   definition of #except, because ActiveSupport unconditionally defines
+    #   its version of #except which doesn't work for BSON::Document which
+    #   causes problems if ActiveSupport is loaded after bson-ruby is.
+    def except(*keys)
+      copy = dup
+      keys.each {|key| copy.delete(key)}
+      copy
+    end
+
+    def symbolize_keys!
+      raise ArgumentError, 'symbolize_keys! is not supported on BSON::Document instances. Please convert the document to hash first (using #to_h), then call #symbolize_keys! on the Hash instance'
+    end
+
+    def deep_symbolize_keys!
+      warn <<~WARN
+        [DEPRECATION] `deep_symbolize_keys!` is not supported on BSON::Document instances.
+        Please convert the document to a Hash first (using `#to_h`), then call `#deep_symbolize_keys!` on the Hash.
+        This will raise an error starting with the v6.0.0 release.
+      WARN
+    end
+
+    # Override the Hash implementation of to_bson_normalized_value.
+    #
+    # BSON::Document is already of the correct type and already provides
+    # indifferent access to keys, hence no further conversions are necessary.
+    #
+    # Attempting to perform Hash's conversion on Document instances converts
+    # DBRefs to Documents which is wrong.
+    #
+    # @return [ BSON::Document ] The normalized hash.
+    def to_bson_normalized_value
+      self
+    end
+
     private
 
     def convert_key(key)

data/lib/bson/environment.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -30,7 +32,20 @@ module BSON
     #
     # @since 2.0.0
     def jruby?
-      defined?(JRUBY_VERSION)
+      @jruby ||= defined?(JRUBY_VERSION)
+    end
+
+    # Determine if we are using Ruby version 1.9.
+    #
+    # @example Are we running with Ruby version 1.9?
+    #   Environment.ruby_1_9?
+    #
+    # @return [ true, false ] If the Ruby version is 1.9.
+    #
+    # @since 4.2.0
+    # @deprecated
+    def ruby_1_9?
+      @ruby_1_9 ||= RUBY_VERSION < '2.0.0'
     end
   end
 end

data/lib/bson/error/bson_decode_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Exception raised when BSON decoding fails.
+    class BSONDecodeError < Error
+    end
+  end
+end

data/lib/bson/error/ext_json_parse_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Exception raised when Extended JSON parsing fails.
+    class ExtJSONParseError < Error
+    end
+  end
+end

data/lib/bson/error/illegal_key.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Raised when validating keys and a key is illegal in MongoDB
+    class IllegalKey < Error
+
+      # Instantiate the exception.
+      #
+      # @example Instantiate the exception.
+      #   BSON::Error::IllegalKey.new(string)
+      #
+      # @param [ String ] string The illegal string.
+      #
+      # @api private
+      def initialize(string)
+        super("'#{string}' is an illegal key in MongoDB. Keys may not start with '$' or contain a '.'.")
+      end
+    end
+  end
+end

data/lib/bson/error/invalid_binary_type.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Raised when providing an invalid type to the Binary.
+    class InvalidBinaryType < Error
+
+      # @return [ Object ] The invalid type.
+      attr_reader :type
+
+      # Instantiate the new error.
+      #
+      # @example Instantiate the error.
+      #   InvalidBinaryType.new(:error)
+      #
+      # @param [ Object ] type The invalid type.
+      #
+      # @api private
+      def initialize(type)
+        @type = type
+      end
+
+      # Get the custom error message for the exception.
+      #
+      # @example Get the message.
+      #   error.message
+      #
+      # @return [ String ] The error message.
+      def message
+        "#{type.inspect} is not a valid binary type. " +
+          "Please use one of #{BSON::Binary::SUBTYPES.keys.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/bson/error/invalid_dbref_argument.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+    
+    # Raised when trying to create a BSON::DBRef from an object that is an invalid DBRef.
+    class InvalidDBRefArgument < Error
+    end
+  end
+end
+

data/lib/bson/error/invalid_decimal128_argument.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Raised when trying to create a Decimal128 from an object that is neither a String nor a BigDecimal.
+    class InvalidDecimal128Argument < Error
+
+      # The custom error message for this error.
+      MESSAGE = 'A Decimal128 can only be created from a String or BigDecimal.'
+
+      # Get the custom error message for the exception.
+      #
+      # @example Get the message.
+      #   error.message
+      #
+      # @return [ String ] The error message.
+      def message
+        MESSAGE
+      end
+    end
+  end
+end
+

data/lib/bson/error/invalid_decimal128_range.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module BSON
+  class Error
+
+    # Raised when the exponent is outside the valid range.
+    class InvalidDecimal128Range < Error
+
+      # The custom error message for this error.
+      #
+      # @deprecated
+      MESSAGE = 'Value out of range for Decimal128 representation.'
+
+      # Get the custom error message for the exception.
+      #
+      # @example Get the message.
+      #   error.message
+      #
+      # @return [ String ] The error message.
+      def message
+        MESSAGE
+      end
+    end
+  end
+end
+