sorted_containers 0.1.1 → 1.1.0

data/lib/sorted_containers/sorted_array.rb

@@ -2,8 +2,23 @@
 
 # The SortedContainers module provides data structures for sorted collections.
 # rubocop:disable Metrics/ClassLength
+require "English"
 module SortedContainers
-  # The SortedArray class is a sorted array implementation.
+  # SortedArray is an array that maintains its elements in sorted order.
+  #
+  # It contains most of the same methods as a regular Array, but some methods
+  # have been removed because they would not make sense for a sorted array. For
+  # example, the #rotate, #shuffle, and #reverse methods have been removed.
+  #
+  # SortedArray also has the additional following methods:
+  # - #add
+  # - #update
+  # - #bisect_left
+  # - #bisect_right
+  #
+  # There are also methods that have been obtimized using the sorted nature of
+  # the array. For example, the #include? method has been optimized to use
+  # binary search.
   class SortedArray
     include Enumerable
 
@@ -11,7 +26,7 @@ module SortedContainers
     # Sublists are split when they exceed 2 * load_factor
     DEFAULT_LOAD_FACTOR = 1000
 
-    attr_reader :size
+    attr_reader :size, :load_factor
     alias length size
 
     # Initializes a new SortedArray object.
@@ -21,128 +36,91 @@ module SortedContainers
     def initialize(iterable = [], load_factor: DEFAULT_LOAD_FACTOR)
       @lists = []
       @maxes = []
-      @index = []
+      @array_index = []
       @offset = 0
       @load_factor = load_factor
       @size = 0
       update(iterable)
     end
 
-    # rubocop:disable Metrics/MethodLength
-
-    # Adds a value to the sorted array.
+    # Returns a new SortedArray populated with the given objects.
     #
-    # @param value [Object] The value to add.
-    def add(value)
-      if @maxes.empty?
-        @lists.append([value])
-        @maxes.append(value)
-      else
-        pos = internal_bisect_right(@maxes, value)
-
-        if pos == @maxes.size
-          pos -= 1
-          @lists[pos].push(value)
-          @maxes[pos] = value
-        else
-          sub_pos = internal_bisect_right(@lists[pos], value)
-          @lists[pos].insert(sub_pos, value)
-        end
-        expand(pos)
-      end
-      @size += 1
+    # @param args [Array] The objects to populate the array with.
+    # @return [SortedArray] The populated array.
+    def self.[](*args)
+      new(args)
     end
 
-    # rubocop:enable Metrics/MethodLength
-
-    # Alias for add
+    # Returns a new SortedArray with the values from the union of the two arrays.
     #
-    # @param value [Object] The value to add.
-    def <<(value)
-      add(value)
+    # @param other [SortedArray] The other array to union with.
+    # @return [SortedArray] The union of the two arrays.
+    def intersection(other)
+      self.class.new(to_a & other.to_a, load_factor: @load_factor)
     end
+    alias & intersection
 
-    # Returns a string representation of the sorted array.
+    # When non-negative, multiplies returns a new Array with each value repeated `int` times.
     #
-    # @return [String] A string representation of the sorted array.
-    def to_s
-      "SortedArray(#{to_a})"
+    # @param num [Integer] The integer to multiply the array by.
+    # @return [SortedArray] The multiplied sorted array.
+    def multiply(num)
+      self.class.new(to_a * num, load_factor: @load_factor)
     end
+    alias * multiply
 
-    # Checks if Array is empty
+    # Returns a new SortedArray with the values from both arrays.
     #
-    # @return [Boolean]
-    def empty?
-      @size.zero?
+    # @param other [SortedArray] The other array to add.
+    # @return [SortedArray] The combined array.
+    def +(other)
+      self.class.new(to_a + other.to_a, load_factor: @load_factor)
     end
 
-    # Returns an index to insert `value` in the sorted list.
-    #
-    # If the `value` is already present, the insertion point will be before
-    # (to the left of) any existing values.
+    # Returns a new SortedArray with the values from the difference of the two arrays.
     #
-    # Runtime complexity: `O(log(n))` -- approximate.
-    #
-    # @param value [Object] The value to insert.
-    # @return [Integer] The index to insert the value.
-    def bisect_left(value)
-      return 0 if @maxes.empty?
-
-      pos = internal_bisect_left(@maxes, value)
-
-      return @size if pos == @maxes.size
-
-      idx = internal_bisect_left(@lists[pos], value)
-      loc(pos, idx)
+    # @param other [SortedArray] The other array to subtract.
+    # @return [SortedArray] The difference of the two arrays.
+    def difference(other)
+      self.class.new(to_a - other.to_a, load_factor: @load_factor)
     end
+    alias - difference
 
-    # Returns an index to insert `value` in the sorted list.
-    #
-    # If the `value` is already present, the insertion point will be after
-    # (to the right of) any existing values.
-    #
-    # Runtime complexity: `O(log(n))` -- approximate.
+    # Returns -1, 0, or 1 if +self+ is less than, equal to, or greater than other. For each index +i+ in +self+,
+    # evaluates +self[i] <=> other[i]+
     #
-    # @param value [Object] The value to insert.
-    # @return [Integer] The index to insert the value.
-    def bisect_right(value)
-      return 0 if @maxes.empty?
-
-      pos = internal_bisect_right(@maxes, value)
+    # @param other [SortedArray] The other array to compare.
+    # @return [Integer] -1, 0, or 1 as self is less than, equal to, or greater than other.
+    def <=>(other)
+      return size <=> other.size if size != other.size
 
-      return @size if pos == @maxes.size
+      each_with_index do |value, index|
+        return value <=> other[index] if value != other[index]
+      end
 
-      idx = internal_bisect_right(@lists[pos], value)
-      loc(pos, idx)
+      0
     end
 
-    # Deletes a value from the sorted array.
+    # Returns true if the arrays size and values are equal.
     #
-    # @param value [Object] The value to delete.
-    def delete(value)
-      return if @maxes.empty?
-
-      pos = internal_bisect_left(@maxes, value)
-
-      return if pos == @maxes.size
-
-      idx = internal_bisect_left(@lists[pos], value)
+    # @param other [SortedArray] The other array to compare.
+    # @return [Boolean] True if the arrays are equal, false otherwise.
+    def ==(other)
+      return false unless other.is_a?(SortedArray)
 
-      internal_delete(pos, idx) if @lists[pos][idx] == value
-    end
-
-    # Tries to match the behavior of Array#[]
-    # alias for slice
-    #
-    # @param args [Integer, Range, Enumerator::ArithmeticSequence] The index or range of values to retrieve.
-    # @return [Object, Array] The value or values at the specified index or range.
-    def [](*args)
-      slice(*args)
+      size == other.size && each_with_index.all? { |value, index| value == other[index] }
     end
 
     # rubocop:disable Metrics/MethodLength
 
-    # Tries to match the behavior of Array#slice
+    # Returns elements from array at the specified index or range. Does not modify the array.
+    #
+    # If a single index is provided, returns the value at that index.
+    #
+    # If a range is provided, returns the values in that range.
+    #
+    # If a start index and length are provided, returns the values starting from the start index and
+    # continuing for the given length.
     #
     # @param args [Integer, Range, Enumerator::ArithmeticSequence] The index or range of values to retrieve.
     # @return [Object, Array] The value or values at the specified index or range.
@@ -167,13 +145,22 @@ module SortedContainers
         raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1..2)"
       end
     end
+    alias [] slice
+
     # rubocop:enable Metrics/MethodLength
 
     # rubocop:disable Metrics/MethodLength
     # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
 
-    # Tries to match the behavior of Array#slice!
+    # Removes elements from array at the specified index or range and returns them. Modifies the array.
+    #
+    # If a single index is provided, returns the value at that index.
+    #
+    # If a range is provided, returns the values in that range.
+    #
+    # If a start index and length are provided, returns the values starting from the start index and
+    # continuing for the given length.
     #
     # @param args [Integer, Range, Enumerator::ArithmeticSequence] The index or range of values to retrieve.
     # @return [Object, Array] The value or values at the specified index or range.
@@ -210,14 +197,486 @@ module SortedContainers
     # rubocop:enable Metrics/AbcSize
     # rubocop:enable Metrics/CyclomaticComplexity
 
-    # Retrieves the last value in the sorted array.
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
+
+    # Sets the value at the specified index or range.
+    #
+    # If a single index is provided, sets the value at that index.
+    #
+    # If a range is provided, sets the values in that range.
+    #
+    # If a start index and length are provided, sets the values starting from the start index and
+    # continuing for the given length.
+    #
+    # @overload []=(index, value)
+    #   @param index [Integer] The index of the value to set.
+    #   @param value [Object] The value to set.
+    # @overload []=(range, value)
+    #   @param range [Range] The range of values to set.
+    #   @param value [Object] The value to set.
+    # @overload []=(start, length, value)
+    #   @param start [Integer] The index to start from.
+    #   @param length [Integer] The length of the values to set.
+    #   @param value [Object, Array] The value or values to set.
+    # @return [Object, Array] The value or values at the specified index or range.
+    def []=(*args)
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 2..3)" if args.size < 2
+
+      value = args.pop
+      case args.size
+      when 1
+        if args[0].is_a?(Integer)
+          index = args[0]
+          delete_at(index)
+          add(value)
+        elsif args[0].is_a?(Range)
+          range = args[0]
+          values = get_values_from_range(range)
+          values.each { |val| delete(val) }
+          if value.is_a?(Array)
+            value.each { |val| add(val) }
+          else
+            add(value)
+          end
+        else
+          raise TypeError, "no implicit conversion of #{args[0].class} into Integer"
+        end
+      when 2
+        start, length = args
+        values = get_values_from_start_and_length(start, length)
+        values.each { |val| delete(val) }
+        add(value)
+      else
+        raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 2..3)"
+      end
+    end
+
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # Calculates the set of unambiguous abbreviations for the strings in +self+.
+    #
+    #   require 'abbrev'
+    #   SortedArray.new(%w{ car cone }).abbrev
+    #   #=> {"car"=>"car", "ca"=>"car", "cone"=>"cone", "con"=>"cone", "co"=>"cone"}
+    #
+    # The optional +pattern+ parameter is a pattern or a string. Only input
+    # strings that match the pattern or start with the string are included in the
+    # output hash.
+    #
+    #   SortedArray.new(%w{ fast boat day }).abbrev(/^.a/)
+    #   #=> {"fast"=>"fast", "fas"=>"fast", "fa"=>"fast", "day"=>"day", "da"=>"day"}
+    #
+    # @param pattern [Regexp, String] The pattern to match.
+    # @return [Hash] The set of unambiguous abbreviations.
+    # See also Abbrev.abbrev
+    def abbrev(pattern = nil)
+      to_a.abbrev(pattern)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+
+    # Adds a value to the sorted array.
+    #
+    # @param value [Object] The value to add.
+    def add(value)
+      if @maxes.empty?
+        @lists.append([value])
+        @maxes.append(value)
+      else
+        raise ArgumentError, "value must be comparable" unless @maxes[0] <=> value
+
+        pos = internal_bisect_right(@maxes, value)
+
+        if pos == @maxes.size
+          pos -= 1
+          @lists[pos].push(value)
+          @maxes[pos] = value
+        else
+          sub_pos = internal_bisect_right(@lists[pos], value)
+          @lists[pos].insert(sub_pos, value)
+        end
+        expand(pos)
+      end
+      @size += 1
+      self
+    end
+    alias << add
+    alias push add
+    alias append add
+
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
+
+    # Returns the first element in +self+ that is an +Array+ whose first element +==+ +obj+:
+    #
+    # @param obj [Object] The object to search for.
+    # @return [Array] The first element in +self+ that is an +Array+ whose first element +==+ +obj+.
+    def assoc(obj)
+      index = bsearch_index { |x| x.is_a?(Array) && x.first >= obj }
+      index.nil? ? nil : self[index]
+    end
+
+    # Returns the element at +Integer+ offset +index+; does not modify +self+.
+    # If +index+ is negative, counts from the end of +self+.
+    # Returns +nil+ if the +index+ is out of range.
+    # Will raise +TypeError+ if the +index+ is not an +Integer+.
+    #
+    # @param index [Integer] The index of the value to retrieve.
+    # @return [Object] The value at the specified index.
+    def at(index)
+      raise TypeError, "no implicit conversion of #{index.class} into Integer" unless index.is_a?(Integer)
+
+      self[index.to_i]
+    end
+
+    # Returns an element from +self+ selected by a binary search.
+    #
+    # @yield [value] The block to search with.
+    # @return [Object] The value selected by the binary search.
+    def bsearch(&block)
+      index_result = bsearch_index(&block)
+
+      return nil if index_result.nil?
+
+      self[index_result]
+    end
+
+    # Returns an index of an element from +self+ selected by a binary search.
+    #
+    # @yield [value] The block to search with.
+    # @return [Integer] The index of the value selected by the binary search.
+    def bsearch_index(&block)
+      return nil if @maxes.empty?
+
+      pos = @maxes.bsearch_index(&block) || 0
+
+      idx = @lists[pos].bsearch_index(&block)
+      loc(pos, idx)
+    end
+
+    # Clears the sorted array, removing all values.
+    #
+    # @return [SortedArray] The cleared sorted array.
+    def clear
+      @lists.map(&:clear)
+      @lists.clear
+      @maxes.clear
+      @array_index.clear
+      @offset = 0
+      @size = 0
+      self
+    end
+
+    # Calls the block, if given, with each element of +self+;
+    # returns +self+ after the block has been executed.
+    #
+    # If no block is given, returns an Enumerator.
+    #
+    # @yield [value] The block to map with.
+    # @return [SortedArray, Enumerator] The mapped array.
+    def map!
+      return to_enum(:map!) unless block_given?
+
+      new_values = []
+      # rubocop:disable Style/MapIntoArray
+      each { |value| new_values << yield(value) }
+      # rubocop:enable Style/MapIntoArray
+      clear
+      # Experimitation shows that it's faster to add all values at once
+      # rather than adding them one by one
+      update(new_values)
+      self
+    end
+    alias collect! map!
+
+    # Adds the elements of one or more arrays to the SortedArray.
+    #
+    # @param other_arrays [Array] The arrays to concatenate.
+    # @return [SortedArray] +self+. The SortedArray with the concatenated values.
+    def concat(*other_arrays)
+      other_arrays.each do |array|
+        update(array)
+      end
+      self
+    end
+
+    # Returns the count of elements, based on an argument or block criterion, if given.
+    # With no argument and no block given, returns the number of elements:
+    # With argument object given, returns the number of elements that are == to object:
+    # Uses binary search to find the first and last index of the value.
+    #
+    # @param value [Object] The value to count.
+    # @yield [value] The block to count with.
+    # @return [Integer] The count of elements.
+    def count(value = nil)
+      # If block is given, we call super to use the Enumerable#count method
+      return super() if block_given?
+      return @size unless value
+
+      left_index = bisect_left(value)
+      right_index = bisect_right(value)
+      right_index - left_index
+    end
+
+    # Deletes a value from the sorted array.
+    #
+    # @param value [Object] The value to delete.
+    def delete(value)
+      return if @maxes.empty?
+
+      pos = internal_bisect_left(@maxes, value)
+
+      return if pos == @maxes.size
+
+      idx = internal_bisect_left(@lists[pos], value)
+
+      internal_delete(pos, idx) if @lists[pos][idx] == value
+    end
+
+    # Deletes the value at the specified index.
+    #
+    # @param index [Integer] The index of the value to delete.
+    def delete_at(index)
+      return nil if index.abs >= @size
+
+      pos, idx = pos(index)
+      internal_delete(pos, idx)
+    end
+
+    # Removes each element from the array for which block evaluates to true.
+    #
+    # @yield [value] The block to delete with.
+    # @return [SortedArray] +self+. The array with the deleted values.
+    def delete_if
+      return to_enum(:delete_if) unless block_given?
+
+      to_delete = []
+      each do |value|
+        to_delete << value if yield(value)
+      end
+      to_delete.each { |value| delete(value) }
+      self
+    end
+
+    # Finds and returns the object in nested objects that is specified by +index+ and +identifiers+.
+    # The nested objects may be instances of various classes. See Dig methods.
+    #
+    # @param index [Integer] The index of the value to retrieve.
+    # @param identifiers [Array] The identifiers to retrieve the value.
+    # @return [Object] The value at the specified index.
+    def dig(index, *identifiers)
+      result = self[index]
+      return nil if result.nil?
+
+      identifiers.each do |identifier|
+        raise TypeError, "#{result.class} does not have #dig method" unless result.respond_to?(:dig)
+
+        # rubocop:disable Style/SingleArgumentDig
+        result = result.dig(identifier)
+        # rubocop:enable Style/SingleArgumentDig
+        return nil if result.nil?
+      end
+
+      result
+    end
+
+    # rubocop:disable Naming/MethodParameterName
+
+    # Returns a new SortedArray containing all but the first +n+ elements, where +n+ is a non-negative integer.
+    # Does not modify the +self+.
+    #
+    # @param n [Integer] The number of elements to drop.
+    # @return [SortedArray] The array with the dropped values.
+    def drop(n)
+      raise ArgumentError, "attempt to drop negative size" if n.negative?
+      return self.class.new(load_factor: @load_factor) if n >= @size
+
+      self.class.new(to_a.drop(n), load_factor: @load_factor)
+    end
+
+    # rubocop:enable Naming/MethodParameterName
+
+    # Returns a new SortedArray containing all but the first elements for which the block returns true.
+    # Does not modify the +self+.
+    # If no block is given, an Enumerator is returned instead.
+    #
+    # @yield [value] The block to drop with.
+    # @return [SortedArray, Enumerator] The array with the dropped values.
+    def drop_while
+      return to_enum(:drop_while) unless block_given?
+
+      self.class.new(super(), load_factor: @load_factor)
+    end
+
+    # Iterates over each value in the sorted array.
+    #
+    # @yield [value] Gives each value to the block.
+    # @return [Enumerator] If no block is given, an Enumerator is returned.
+    def each(&block)
+      return to_enum(:each) unless block_given?
+
+      @lists.each do |sublist|
+        sublist.each(&block)
+      end
+    end
+
+    # Iterates over each index in the sorted array.
+    #
+    # @yield [index] Gives each index to the block.
+    # @return [Enumerator] If no block is given, an Enumerator is returned.
+    def each_index(&block)
+      return to_enum(:each_index) unless block_given?
+
+      0.upto(@size - 1, &block)
+    end
+
+    # Checks if Array is empty
+    #
+    # @return [Boolean]
+    def empty?
+      @size.zero?
+    end
+
+    # Returns +true+ if for every element in +self+ there is a corresponding element in +other+
+    # that are equal using +Object#eql?+.
+    #
+    # This method is different from method +SortedArray#==+,
+    # which compares using method +Object#==+
+    #
+    # @param other [SortedArray] The other array to compare.
+    # @return [Boolean] True if the arrays are equal, false otherwise.
+    def eql?(other)
+      return false unless other.is_a?(SortedArray)
+
+      size == other.size && each_with_index.all? { |value, index| value.eql?(other[index]) }
+    end
+
+    # Returns the element at the specified index, or returns a default value if the index is out of range.
+    # Raises an IndexError if the index is out of range and no default is given.
+    # If a block is given, it is called with the index. The block will supplant the default value if both are given.
+    #
+    # @param index [Integer] The index of the value to retrieve.
+    # @param args [Object] The default value to return if the index is out of range.
+    def fetch(index, *args)
+      return self[index] if index.abs < @size
+
+      return yield(index) if block_given?
+
+      return args[0] if args.size.positive?
+
+      raise IndexError, "index #{index} outside of array bounds: #{-size}...#{size}"
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
+
+    # Fills the array with the given value.
+    #
+    # @overload fill(value)
+    #   @param value [Object] The value to fill the array with.
+    # @overload fill(value, start)
+    #   @param value [Object] The value to fill the array with.
+    #   @param start [Integer] The index to start filling from.
+    # @overload fill(value, start, length)
+    #   @param value [Object] The value to fill the array with.
+    #   @param start [Integer] The index to start filling from.
+    #   @param length [Integer] The length of the values to fill.
+    # @overload fill(value, range)
+    #   @param value [Object] The value to fill the array with.
+    #   @param range [Range] The range of values to fill.
+    # @overload fill
+    #   @yield [index] The block to fill with.
+    # @overload fill(start)
+    #   @param start [Integer] The index to start filling from.
+    #   @yield [index] The block to fill with.
+    # @overload fill(start, length)
+    #   @param start [Integer] The index to start filling from.
+    #   @param length [Integer] The length of the values to fill.
+    #   @yield [index] The block to fill with.
+    # @overload fill(range)
+    #   @param range [Range] The range of values to fill.
+    #   @yield [index] The block to fill with.
+    # @return [SortedArray] +self+. The filled array.
+    def fill(*args, &block)
+      unless block_given?
+        value = args.shift
+        block = proc { value }
+      end
+
+      case args.size
+      when 0
+        fill_range_unsafe(0..@size - 1, block)
+      when 1
+        if args[0].is_a?(Integer)
+          start = args[0]
+          start += @size if start.negative?
+          fill_range_unsafe(start..@size - 1, block)
+        elsif args[0].is_a?(Range)
+          fill_range_unsafe(args[0], block)
+        end
+      when 2
+        start, length = args
+        start += @size if start.negative?
+        fill_range_unsafe(start...(start + length), block)
+      end
+
+      sort! # resort will re-initialize the index and maxes
+      self
+    end
+
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength
+
+    # Calls the block, if given, with each element of +self+;
+    # returns +self+ with the elements for which the block returns a truthy value.
+    #
+    # If no block is given, returns an Enumerator.
+    #
+    # @yield [value] The block to filter with.
+    # @return [SortedArray, Enumerator] The filtered array.
+    def select!
+      return to_enum(:select!) unless block_given?
+
+      indexes_to_delete = []
+      each_with_index do |value, index|
+        indexes_to_delete << index unless yield(value)
+      end
+      indexes_to_delete.reverse.each { |index| delete_at(index) }
+      self
+    end
+    alias filter! select!
+
+    # Returns the first index of the value in the sorted array, or returns
+    # the first index that returns true when passed to the block.
     #
-    # @return [Object] The last value in the array.
-    def last
+    # This method will binary search if value is given,
+    # if a block is given, it will iterate through the array.
+    #
+    # @overload find_index(value)
+    #   @param value [Object] The value to find.
+    # @overload find_index
+    #   @yield [value] The block to find with.
+    # @return [Integer] The index of the value.
+    def find_index(value = nil)
       return nil if @size.zero?
 
-      @lists.last.last
+      if block_given?
+        each_with_index { |val, idx| return idx if yield(val) }
+        nil
+      else
+        bsearch_index { |val| val >= value }
+      end
     end
+    alias index find_index
 
     # Retrieves the first value in the sorted array.
     #
@@ -228,99 +687,173 @@ module SortedContainers
       @lists.first.first
     end
 
-    # Deletes the value at the specified index.
+    # Returns a new SortedArray that is a recursive flattening of the array.
     #
-    # @param index [Integer] The index of the value to delete.
-    def delete_at(index)
-      return nil if index.abs >= @size
+    # Each non-array element is unchanged, and each array element is recursively flattened.
+    # When the optional level argument is given, the recursion is limited to that level.
+    #
+    # @param level [Integer] The level to flatten to.
+    # @return [SortedArray] The flattened array.
+    def flatten(level = nil)
+      self.class.new(to_a.flatten(level), load_factor: @load_factor)
+    end
 
-      pos, idx = pos(index)
-      internal_delete(pos, idx)
+    # Flattens the array in place.
+    #
+    # Each non-array element is unchanged, and each array element is recursively flattened.
+    # When the optional level argument is given, the recursion is limited to that level.
+    #
+    # @param level [Integer] The level to flatten to.
+    # @return [SortedArray] +self+. The flattened array.
+    def flatten!(level = nil)
+      values = to_a.flatten(level)
+      clear
+      update(values)
+      self
     end
 
-    # rubocop:disable Metrics/MethodLength
+    # Returns the integer hash value for the sorted array.
+    # Two arrays with the same content will have the same hash value.
+    #
+    # @return [Integer] The hash value.
+    def hash
+      @lists.hash
+    end
 
-    # Pops the last value from the sorted array.
+    # Checks if the sorted array contains a value.
     #
-    # @return [Object] The last value in the array.
-    def pop
-      return nil if @size.zero?
+    # @param value [Object] The value to check.
+    # @return [Boolean] True if the value is found, false otherwise.
+    def include?(value)
+      i = internal_bisect_left(@maxes, value)
+      return false if i == @maxes.size
 
-      value = @lists.last.pop
-      if @lists.last.empty?
-        @lists.pop
-        @maxes.pop
-        @index.clear
-      else
-        @maxes[-1] = @lists.last.last
+      sublist = @lists[i]
+      idx = internal_bisect_left(sublist, value)
+      idx < sublist.size && sublist[idx] == value
+    end
+
+    # Returns a string representation of the sorted array.
+    #
+    # @return [String] A string representation of the sorted array.
+    def inspect
+      "#<#{self.class} size=#{@size} array_index=#{@array_index} " \
+        "offset=#{@offset} maxes=#{@maxes} items=#{@lists}>"
+    end
+
+    # Returns +true+ if the SortedArray and +other+ have at least one element in common, otherwise returns +false+
+    # Elements are compared using +eql?+
+    #
+    # @param other [SortedArray] The other array to compare.
+    # @return [Boolean] +true+ if the array and +other+ have at least one element in common, otherwise +false+
+    def intersect?(other)
+      each do |value|
+        return true if other.include_eql?(value)
       end
-      @size -= 1
-      value
+      false
     end
-    # rubocop:enable Metrics/MethodLength
 
-    # rubocop:disable Metrics/MethodLength
+    # Returns a +String+ formed by joining each element of the array with the given separator.
+    #
+    # @param separator [String] The separator to join the elements with.
+    # @return [String] The joined string.
+    def join(separator = $OUTPUT_FIELD_SEPARATOR)
+      to_a.join(separator)
+    end
 
-    # Shifts the first value from the sorted array.
+    # Retains those elements for which the block returns a truthy value; deletes all other elements; returns +self+
     #
-    # @return [Object] The first value in the array.
-    def shift
-      return nil if @size.zero?
+    # Returns an Enumerator if no block is given.
+    #
+    # @yield [value] The block to keep with.
+    # @return [SortedArray, Enumerator] The array with the kept values.
+    def keep_if
+      return to_enum(:keep_if) unless block_given?
 
-      value = @lists.first.shift
-      if @lists.first.empty?
-        @lists.shift
-        @maxes.shift
-        @index.clear
-      else
-        @maxes[0] = @lists.first.first
+      (@size - 1).downto(0) do |index|
+        delete_at(index) unless yield(self[index])
       end
-      @size -= 1
-      value
+      self
     end
-    # rubocop:enable Metrics/MethodLength
 
-    # Returns the count of elements, based on an argument or block criterion, if given.
-    # With no argument and no block given, returns the number of elements:
-    # With argument object given, returns the number of elements that are == to object:
-    # Uses binary search to find the first and last index of the value.
+    # Retrieves the last value in the sorted array.
     #
-    # @param value [Object] The value to count.
-    # @yield [value] The block to count with.
-    # @return [Integer] The count of elements.
-    def count(value = nil)
-      return super() if block_given?
-      return @size unless value
+    # @return [Object] The last value in the array.
+    def last
+      return nil if @size.zero?
 
-      left_index = bisect_left(value)
-      right_index = bisect_right(value)
-      right_index - left_index
+      @lists.last.last
     end
 
-    # Clears the sorted array, removing all values.
+    # Replaces the contents of +self+ with the contents of +other+.
+    #
+    # @param other [SortedArray] The other array to replace with.
+    # @return [SortedArray] +self+. The replaced array.
+    def replace(other)
+      @lists = other.lists.map(&:dup)
+      @maxes = other.maxes.dup
+      @array_index = other.array_index.dup
+      @offset = other.offset
+      @load_factor = other.load_factor
+      @size = other.size
+      self
+    end
+
+    # Returns a string representation of the sorted array.
     #
-    # @return [void]
-    def clear
-      @lists.clear
-      @maxes.clear
-      @index.clear
-      @offset = 0
-      @size = 0
+    # @return [String] A string representation of the sorted array.
+    def to_s
+      "SortedArray(#{to_a})"
     end
 
-    # Checks if the sorted array contains a value.
+    # Returns an index to insert +value+ in the sorted list.
     #
-    # @param value [Object] The value to check.
-    # @return [Boolean] True if the value is found, false otherwise.
-    def include?(value)
-      i = internal_bisect_left(@maxes, value)
-      return false if i == @maxes.size
+    # If the +value+ is already present, the insertion point will be before
+    # (to the left of) any existing values.
+    #
+    # Runtime complexity: +O(log(n))+ -- approximate.
+    #
+    # @param value [Object] The value to insert.
+    # @return [Integer] The index to insert the value.
+    def bisect_left(value)
+      return 0 if @maxes.empty?
 
-      sublist = @lists[i]
-      idx = internal_bisect_left(sublist, value)
-      idx < sublist.size && sublist[idx] == value
+      pos = internal_bisect_left(@maxes, value)
+
+      return @size if pos == @maxes.size
+
+      idx = internal_bisect_left(@lists[pos], value)
+      loc(pos, idx)
+    end
+
+    # Returns an index to insert +value+ in the sorted list.
+    #
+    # If the +value+ is already present, the insertion point will be after
+    # (to the right of) any existing values.
+    #
+    # Runtime complexity: +O(log(n))+ -- approximate.
+    #
+    # @param value [Object] The value to insert.
+    # @return [Integer] The index to insert the value.
+    def bisect_right(value)
+      return 0 if @maxes.empty?
+
+      pos = internal_bisect_right(@maxes, value)
+
+      return @size if pos == @maxes.size
+
+      idx = internal_bisect_right(@lists[pos], value)
+      loc(pos, idx)
     end
 
+    # Shifts the first value from the sorted array.
+    #
+    # @return [Object] The first value in the array.
+    def shift
+      return nil if @size.zero?
+
+      delete_at(0)
+    end
     # rubocop:disable Metrics/MethodLength
     # rubocop:disable Metrics/AbcSize
 
@@ -355,7 +888,7 @@ module SortedContainers
       @size = values.length
 
       # Clear the index as it might be outdated
-      @index.clear
+      @array_index.clear
     end
     # rubocop:enable Metrics/MethodLength
     # rubocop:enable Metrics/AbcSize
@@ -364,22 +897,27 @@ module SortedContainers
     #
     # @return [Array] An array representation of the sorted array.
     def to_a
-      @lists.flatten
+      @lists.flatten(1)
     end
+    alias to_ary to_a
 
-    # Array is already sorted. Duplicates the sorted array and returns it.
+    # Creates a new SortedArray and resorts the values.
+    # Usefull when the values are modified and the array needs to be resorted.
     #
     # @return [SortedArray] The sorted array.
     def sort
-      # No need to sort, already sorted
-      dup
+      values = to_a
+      self.class.new(values, load_factor: @load_factor)
     end
 
-    # Returns self, as the array is already sorted.
+    # Resorts the values in the array.
+    # Usefull when the values are modified and the array needs to be resorted.
     #
     # @return [SortedArray] The sorted array.
     def sort!
-      # No need to sort, already sorted
+      values = to_a
+      clear
+      update(values)
       self
     end
 
@@ -391,25 +929,13 @@ module SortedContainers
       new_instance = self.class.new
       new_instance.lists = @lists.map(&:dup)
       new_instance.maxes = @maxes.dup
-      new_instance.index = @index.dup
+      new_instance.array_index = @array_index.dup
       new_instance.offset = @offset
       new_instance.load_factor = @load_factor
       new_instance.size = @size
       new_instance
     end
 
-    # When non-negative, multiplies returns a new Array with each value repeated `int` times.
-    #
-    # @param num [Integer] The integer to multiply the array by.
-    # @return [SortedArray] The multiplied sorted array.
-    def multiply(num)
-      values = @lists.flatten * num
-      new_instance = self.class.new
-      new_instance.update(values)
-      new_instance
-    end
-    alias * multiply
-
     # Returns the maximum value in the sorted array.
     #
     # @return [Object] The maximum value in the array.
@@ -424,15 +950,238 @@ module SortedContainers
       @lists.first&.first
     end
 
-    # Iterates over each value in the sorted array.
+    # Returns a 2-element array containing the minimum and maximum values in the sorted array.
+    # If a block is given, the result of the block is computed for each value in the array,
+    # and the minimum and maximum values are computed from the result.
+    #
+    # @yield [value] The block to compute with.
+    # @return [Array] A 2-element array containing the minimum and maximum values.
+    def minmax
+      if block_given?
+        each.reduce([nil, nil]) do |(min_value, max_value), value|
+          min_value = value if min_value.nil? || yield(value, min_value).negative?
+          max_value = value if max_value.nil? || yield(value, max_value).positive?
+          [min_value, max_value]
+        end
+      else
+        [min, max]
+      end
+    end
+
+    # Packs the values in the array into a binary sequence.
+    # @see Array#pack
+    #
+    # @param template [String] The template to pack the values with.
+    # @param buffer [String] The buffer to pack the values into.
+    # @return [String] The packed values.
+    def pack(template, buffer: nil)
+      to_a.pack(template, buffer: buffer)
+    end
+
+    # rubocop:disable Naming/MethodParameterName
+    # rubocop:disable Metrics/MethodLength
+
+    # Pops the last value from the sorted array.
+    #
+    # @param n [Integer] The number of values to pop.
+    # @return [Object] The last value in the array.
+    def pop(n = nil)
+      return nil if @size.zero?
+
+      if n.nil?
+        index = @size - 1
+        delete_at(index)
+      else
+        values = []
+        n.times do
+          return values if @size.zero?
+
+          index = @size - 1
+          values.prepend(delete_at(index))
+        end
+        values
+      end
+    end
+
+    # rubocop:enable Naming/MethodParameterName
+    # rubocop:enable Metrics/MethodLength
+
+    # Computes and returns or yields all combinations of elements from all the Arrays,
+    # including both +self+ and +other_arrays+.
+    #
+    # @param other_arrays [SortedArray] The arrays to combine with.
+    # @yield [value] The block to combine with.
+    # @return [SortedArray] The combined array.
+    def product(*other_arrays, &block)
+      arrays = other_arrays.map(&:to_a)
+      self.class.new(
+        to_a.product(*arrays, &block),
+        load_factor: @load_factor
+      )
+    end
+
+    # Returns the first element in +self+ that is an +Array+ whose second element +==+ +obj+:
+    #
+    # Time complexity: O(n)
+    #
+    # @param obj [Object] The object to search for.
+    # @return [Array] The first element in +self+ that is an +Array+ whose second element +==+ +obj+.
+    def rassoc(obj)
+      index = find_index { |x| x.is_a?(Array) && x[1] >= obj }
+      index.nil? ? nil : self[index]
+    end
+
+    # Deletes every element of +self+ for which block evaluates to true.
+    #
+    # Returns +self+ if any changes were made, otherwise returns +nil+.
+    #
+    # Returns an Enumerator if no block is given.
+    #
+    # @yield [value] The block to reject with.
+    # @return [SortedArray, Enumerator] The rejected array.
+    def reject!
+      return to_enum(:reject!) unless block_given?
+
+      indexes_to_delete = []
+      each_with_index do |value, index|
+        indexes_to_delete << index if yield(value)
+      end
+      return nil if indexes_to_delete.empty?
+
+      indexes_to_delete.reverse.each { |index| delete_at(index) }
+      self
+    end
+
+    # Iterates over the sorted array in reverse order.
     #
     # @yield [value] Gives each value to the block.
-    def each(&block)
-      @lists.each do |sublist|
-        sublist.each(&block)
+    # @return [Enumerator] If no block is given, an Enumerator is returned.
+    def reverse_each(&block)
+      return to_enum(:reverse_each) unless block_given?
+
+      @lists.reverse_each do |sublist|
+        sublist.reverse_each(&block)
       end
     end
 
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
+
+    # Returns the index of the last element for which object +==+ element.
+    #
+    # Returns an Enumerator if no block or value is given.
+    #
+    # When a block is given but no value, the block is used to find the last element.
+    #
+    # @overload rindex(value)
+    #   @param value [Object] The value to find.
+    # @overload rindex
+    #   @yield [value] The block to find with.
+    # @return [Integer] The index of the value.
+    def rindex(value = nil)
+      return to_enum(:rindex, value) unless block_given? || value
+      return nil if @size.zero?
+
+      if value.nil?
+        reverse_each.with_index do |val, idx|
+          return @size - idx - 1 if yield(val)
+        end
+        nil
+      else
+        warn "given block not used" if block_given?
+        index = bisect_right(value)
+        self[index - 1] == value ? index - 1 : nil
+      end
+    end
+
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # rubocop:disable Naming/MethodParameterName
+
+    # Returns random elements from +self+.
+    #
+    # If +n+ is given, returns an array of +n+ random elements.
+    # If +n+ is not given, returns a single random element.
+    #
+    # @param n [Integer] The number of random elements to return.
+    # @param random [Random] The random number generator to use.
+    # @return [Object, Array] The random element(s).
+    def sample(n = nil, random: Random)
+      return nil if @size.zero?
+
+      if n.nil?
+        index = random.rand(@size)
+        self[index]
+      else
+        raise ArgumentError, "negative sample number" if n.negative?
+
+        n.times.map { self[random.rand(@size)] }
+      end
+    end
+
+    # rubocop:enable Naming/MethodParameterName
+
+    # Returns a new SortedArray that is the union of +self+ and +other_arrays+.
+    # Duplicates are removed.
+    #
+    # @param other_arrays [Array] The arrays to union with.
+    # @return [SortedArray] The unioned array.
+    def union(*other_arrays)
+      self.class.new(to_a | other_arrays.flatten, load_factor: @load_factor)
+    end
+    alias | union
+
+    # Returns a new SortedArray containing the unique values in +self+.
+    #
+    # @return [SortedArray] The unique array.
+    def uniq(&block)
+      self.class.new(to_a.uniq(&block), load_factor: @load_factor)
+    end
+
+    # Removes duplicate values from the sorted array.
+    # Returns +self+ if any changes were made, otherwise returns +nil+.
+    # If a block is given, it will use the block to determine uniqueness.
+    #
+    # @yield [value] The block to determine uniqueness.
+    # @return [SortedArray, nil] The array with the unique values.
+    def uniq!(&block)
+      values = to_a.uniq(&block)
+
+      return nil if values.size == @size
+
+      clear
+      update(values)
+      self
+    end
+
+    # Returns a new SortedArray containing the values from the given indexes and ranges.
+    #
+    # @param indexes [Integer, Range] The indexes and ranges to get values from.
+    # @return [Array] The values from the given indexes and ranges.
+    def values_at(*indexes)
+      indexes.map do |index|
+        if index.is_a?(Range)
+          get_values_from_range(index)
+        else
+          get_value_at_index(index)
+        end
+      end.flatten
+    end
+
+    # Combines each element of the sorted array with the corresponding elements from other arrays.
+    #
+    # @param other_arrays [Array] The other arrays to zip with the sorted array.
+    # @param block [Proc] An optional block to apply to each zipped element.
+    # @return [SortedArray] A new SortedArray containing the zipped elements.
+    def zip(*other_arrays, &block)
+      self.class.new(to_a.zip(*other_arrays, &block), load_factor: @load_factor)
+    end
+
     private
 
     # Performs a left bisect on the array.
@@ -441,7 +1190,7 @@ module SortedContainers
     # @param value [Object] The value to bisect with.
     # @return [Integer] The index where the value should be inserted.
     def internal_bisect_left(array, value)
-      array.bsearch_index { |x| x >= value } || array.size
+      array.bsearch_index { |x| (x <=> value) >= 0 } || array.size
     end
 
     # Performs a right bisect on the array.
@@ -450,7 +1199,26 @@ module SortedContainers
     # @param value [Object] The value to bisect with.
     # @return [Integer] The index where the value should be inserted.
     def internal_bisect_right(array, value)
-      array.bsearch_index { |x| x > value } || array.length
+      array.bsearch_index { |x| (x <=> value) == 1 } || array.length
+    end
+
+    # Updates the index within the range with the block.
+    # Does not update index or maxes. Distrupts the sorted order.
+    #
+    # @param range [Range] The range to update.
+    # @param block [Proc] The block that takes the index and returns the value.
+    def fill_range_unsafe(range, block)
+      range.each { |index| internal_change_unsafe(index, block.call(index)) }
+    end
+
+    # Updates the element at index with the value.
+    # Does not update index or maxes. Distrupts the sorted order.
+    #
+    # @param index [Integer] The index of the value to update.
+    # @param value [Object] The value to update.
+    def internal_change_unsafe(index, value)
+      pos, idx = pos(index)
+      @lists[pos][idx] = value
     end
 
     # Gets the value at a given index. Supports negative indices.
@@ -571,14 +1339,14 @@ module SortedContainers
         @maxes[pos] = @lists[pos].last
         @lists.insert(pos + 1, half)
         @maxes.insert(pos + 1, half.last)
-        @index.clear
-      elsif @index.size.positive?
+        @array_index.clear
+      elsif @array_index.size.positive?
         child = @offset + pos
         while child.positive?
-          @index[child] += 1
+          @array_index[child] += 1
           child = (child - 1) >> 1
         end
-        @index[0] += 1
+        @array_index[0] += 1
       end
     end
     # rubocop:enable Metrics/AbcSize
@@ -602,24 +1370,24 @@ module SortedContainers
       if len_list > (@load_factor >> 1)
         @maxes[pos] = list.last
 
-        if @index.size.positive?
+        if @array_index.size.positive?
           child = @offset + pos
           while child.positive?
-            @index[child] -= 1
+            @array_index[child] -= 1
             child = (child - 1) >> 1
           end
-          @index[0] -= 1
+          @array_index[0] -= 1
         end
       elsif @lists.length > 1
         pos += 1 if pos.zero?
 
         prev = pos - 1
-        @lists[prev].concat(list)
+        @lists[prev].concat(@lists[pos])
         @maxes[prev] = @lists[prev].last
 
         @lists.delete_at(pos)
         @maxes.delete_at(pos)
-        @index.clear
+        @array_index.clear
 
         expand(prev)
       elsif len_list.positive?
@@ -627,7 +1395,7 @@ module SortedContainers
       else
         @lists.delete_at(pos)
         @maxes.delete_at(pos)
-        @index.clear
+        @array_index.clear
       end
       value
     end
@@ -663,7 +1431,7 @@ module SortedContainers
     #
     # Finally, the index is built by concatenating these lists together:
     #
-    #     @index = [14, 5, 9, 3, 2, 4, 5]
+    #     @array_index = [14, 5, 9, 3, 2, 4, 5]
     #
     # An offset storing the start of the first row is also stored:
     #
@@ -677,7 +1445,7 @@ module SortedContainers
 
       # Early return if there is only one sublist
       if row0.length == 1
-        @index = row0
+        @array_index = row0
         @offset = 0
         return
       end
@@ -691,7 +1459,7 @@ module SortedContainers
 
       # Return early if only one row is needed
       if row1.length == 1
-        @index = row1 + row0
+        @array_index = row1 + row0
         @offset = 1
         return
       end
@@ -708,7 +1476,7 @@ module SortedContainers
       end
 
       # Flatten the tree into the index array
-      tree.reverse_each { |level| @index.concat(level) }
+      tree.reverse_each { |level| @array_index.concat(level) }
       @offset = (the_size * 2) - 1
     end
     # rubocop:enable Metrics/AbcSize
@@ -788,14 +1556,14 @@ module SortedContainers
 
       return 0, idx if idx < @lists[0].size
 
-      build_index if @index.empty?
+      build_index if @array_index.empty?
 
       pos = 0
       child = 1
-      len_index = @index.size
+      len_index = @array_index.size
 
       while child < len_index
-        index_child = @index[child]
+        index_child = @array_index[child]
 
         if idx < index_child
           pos = child
@@ -823,7 +1591,7 @@ module SortedContainers
     def loc(pos, idx)
       return idx if pos.zero?
 
-      build_index if @index.empty?
+      build_index if @array_index.empty?
 
       # Increment pos to point in the index to @lists[pos].size.
       total = 0
@@ -835,7 +1603,7 @@ module SortedContainers
 
         # Right-child nodes are at even indices. At such indices
         # account the total below the left child node.
-        total += @index[pos - 1] if pos.even?
+        total += @array_index[pos - 1] if pos.even?
 
         # Advance pos to the parent node.
         pos = (pos - 1) >> 1
@@ -846,7 +1614,16 @@ module SortedContainers
 
     protected
 
-    attr_accessor :lists, :maxes, :index, :offset, :load_factor
+    # Checks if the sorted array includes a value using eql?.
+    #
+    # @param value [Object] The value to check.
+    # @return [Boolean] True if the value is found, false otherwise.
+    def include_eql?(value)
+      index = find_index(value)
+      index ? self[index].eql?(value) : false
+    end
+
+    attr_accessor :lists, :maxes, :array_index, :offset
 
     attr_writer :size
   end