sequel 5.106.0 → 5.108.0

data/lib/sequel/extensions/pg_array_ops.rb

@@ -54,15 +54,20 @@
 #   ia.join            # array_to_string(int_array_column, '')
 #   ia.join(':')       # array_to_string(int_array_column, ':')
 #   ia.join(':', ' ')  # array_to_string(int_array_column, ':', ' ')
-#   ia.unnest          # unnest(int_array_column)
-#   ia.unnest(:b)      # unnest(int_array_column, b)
-#
-# On PostgreSQL 18+, the following are supported:
-#
+#   ia.ndims           # array_ndims(int_array_column)
+#   ia.position(3)     # array_position(int_array_column, 3, 1)
+#   ia.position(3, 2)  # array_position(int_array_column, 3, 2)
+#   ia.positions(3)    # array_positions(int_array_column, 3)
+#   ia.prepend(3)      # array_prepend(3, int_array_column)
+#   ia.reverse             # array_reverse(int_array_column)
+#   ia.sample(3)       # array_sample(int_array_column, 3)
+#   ia.shuffle         # array_shuffle(int_array_column)
 #   ia.sort                # array_sort(int_array_column)
 #   ia.sort(desc: true)    # array_sort(int_array_column, true)
 #   ia.sort(nulls: :first) # array_sort(int_array_column, false, true)
-#   ia.reverse             # array_reverse(int_array_column)
+#   ia.trim(1)         # trim_array(int_array_column, 1)
+#   ia.unnest          # unnest(int_array_column)
+#   ia.unnest(:b)      # unnest(int_array_column, b)
 # 
 # See the PostgreSQL array function and operator documentation for more
 # details on what these functions and operators do.
@@ -153,6 +158,13 @@ module Sequel
         function(:array_dims)
       end
 
+      # Call the array_ndims method:
+      #
+      #   array_op.ndims # array_ndims(array)
+      def ndims
+        function(:array_ndims)
+      end
+
       # Convert the array into an hstore using the hstore function.
       # If given an argument, use the two array form:
       #
@@ -164,9 +176,9 @@ module Sequel
         else
           Sequel.function(:hstore, self, wrap_array(arg))
         end
-        # :nocov:
+        # simplecov:disable
         if Sequel.respond_to?(:hstore_op)
-        # :nocov:
+        # simplecov:enable
           v = Sequel.hstore_op(v)
         end
         v
@@ -188,6 +200,28 @@ module Sequel
         function(:array_lower, dimension)
       end
       
+      # Call the array_position method:
+      #
+      #   array_op.position(1)    # array_position(array, 1, 1)
+      #   array_op.position(1, 2) # array_position(array, 1, 2)
+      def position(element, offset = 1)
+        function(:array_position, element, offset)
+      end
+      
+      # Call the array_positions method:
+      #
+      #   array_op.positions(1) # array_positions(array, 1)
+      def positions(element)
+        function(:array_positions, element)
+      end
+      
+      # Call the array_prepend method:
+      #
+      #   array_op.prepend(1) # array_prepend(1, array)
+      def prepend(element)
+        SQL::Function.new(:array_prepend, element, self)
+      end
+      
       # Use the overlaps (&&) operator:
       #
       #   array_op.overlaps(:a) # (array && a)
@@ -195,7 +229,7 @@ module Sequel
         bool_op(OVERLAPS, wrap_array(other))
       end
 
-      # Use the concatentation (||) operator:
+      # Use the concatenation (||) operator:
       #
       #   array_op.push(:a) # (array || a)
       #   array_op.concat(:a) # (array || a)
@@ -231,6 +265,20 @@ module Sequel
         function(:array_reverse)
       end
       
+      # Call the array_sample method:
+      #
+      #   array_op.sample(1) # array_sample(array, 1)
+      def sample(element)
+        function(:array_sample, element)
+      end
+      
+      # Call the array_shuffle method:
+      #
+      #   array_op.shuffle # array_shuffle
+      def shuffle
+        function(:array_shuffle)
+      end
+      
       # Call the array_sort method. Options:
       #
       # :desc :: Sort in descending order instead of ascending order.
@@ -273,6 +321,13 @@ module Sequel
       end
       alias join to_string
       
+      # Call the trim_array method:
+      #
+      #   array_op.trim(1) # array_trim(array, 1)
+      def trim(number)
+        function(:trim_array, number)
+      end
+      
       # Call the unnest method:
       #
       #   array_op.unnest # unnest(array)
@@ -280,7 +335,7 @@ module Sequel
         function(:unnest, *args.map{|a| wrap_array(a)})
       end
       
-      # Use the concatentation (||) operator, reversing the order:
+      # Use the concatenation (||) operator, reversing the order:
       #
       #   array_op.unshift(:a) # (a || array)
       def unshift(other)
@@ -326,9 +381,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(PGArray)
-    # :nocov:
+    # simplecov:enable
       class PGArray
         # Wrap the PGArray instance in an ArrayOp, allowing you to easily use
         # the PostgreSQL array functions and operators with literal arrays.
@@ -360,7 +415,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::ArrayOpMethods
@@ -374,4 +429,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_auto_parameterize.rb

@@ -56,7 +56,7 @@
 #      DB[:t].select{foo('a').as(:f)}.group{foo('a')}
 #      # SELECT foo('a') AS "f" FROM "t" GROUP BY foo('a')
 #
-#    Will get auto paramterized as:
+#    Will get auto parameterized as:
 #
 #      # SELECT foo($1) AS "f" FROM "t" GROUP BY foo($2)
 #
@@ -180,7 +180,7 @@ module Sequel
         end
       end
 
-      # PlacholderLiteralizer subclass with support for stored auto parameters.
+      # PlaceholderLiteralizer subclass with support for stored auto parameters.
       class PlaceholderLiteralizer < ::Sequel::Dataset::PlaceholderLiteralizer
         def initialize(dataset, fragments, final_sql, arity)
           s = dataset.sql.dup

data/lib/sequel/extensions/pg_auto_parameterize_in_array.rb

@@ -49,7 +49,7 @@ module Sequel
     # Enable automatically parameterizing queries.
     module AutoParameterizeInArray
       module TreatStringListAsUntypedArray
-        # Sentinal value to use as an auto param type to use auto parameterization
+        # Sentinel value to use as an auto param type to use auto parameterization
         # of a string array without an explicit type cast.
         NO_EXPLICIT_CAST = Object.new.freeze
 
@@ -64,7 +64,7 @@ module Sequel
 
         private
 
-        # Recognize NO_EXPLICIT_CAST sentinal value and use wrapped
+        # Recognize NO_EXPLICIT_CAST sentinel value and use wrapped
         # PGArray that will be parameterized into the query.
         def _convert_array_to_pg_array_with_type(r, type)
           if NO_EXPLICIT_CAST.equal?(type)
@@ -158,7 +158,7 @@ module Sequel
         nil
       end
 
-      # The minimium size of array to auto parameterize.
+      # The minimum size of array to auto parameterize.
       def pg_auto_parameterize_min_array_size
         2
       end

data/lib/sequel/extensions/pg_enum.rb

@@ -180,9 +180,9 @@ module Sequel
   end
 
   # support reversible create_enum statements if the migration extension is loaded
-  # :nocov:
+  # simplecov:disable
   if defined?(MigrationReverser)
-  # :nocov:
+  # simplecov:enable
     class MigrationReverser
       private
       def create_enum(name, _)

data/lib/sequel/extensions/pg_extended_date_support.rb

@@ -31,7 +31,7 @@ module Sequel
       RATIONAL_60 = Rational(60)
       TIME_CAN_PARSE_BC = RUBY_VERSION >= '2.5'
 
-      # Add dataset methods and update the conversion proces for dates and timestamps.
+      # Add dataset methods and update the conversion process for dates and timestamps.
       def self.extended(db)
         db.extend_datasets(DatasetMethods)
         procs = db.conversion_procs
@@ -114,10 +114,10 @@ module Sequel
               DateTime.parse(value)
             elsif TIME_CAN_PARSE_BC
               Time.parse(value)
-            # :nocov:
+            # simplecov:disable
             else
               DateTime.parse(value).to_time
-            # :nocov:
+            # simplecov:enable
             end
 
             Sequel.convert_output_timestamp(dt, Sequel.application_timezone)
@@ -219,7 +219,7 @@ module Sequel
         end
 
         if RUBY_ENGINE == 'jruby'
-          # :nocov:
+          # simplecov:disable
 
           ExtendedDateSupport::CONVERT_TYPES = [Java::JavaSQL::Types::DATE, Java::JavaSQL::Types::TIMESTAMP]
 
@@ -241,7 +241,7 @@ module Sequel
               super
             end
           end
-          # :nocov:
+          # simplecov:enable
         else
           # Handle BC Time objects.
           def literal_time(time)

data/lib/sequel/extensions/pg_extended_integer_support.rb

@@ -53,7 +53,7 @@
 #  # => "numeric"
 #
 # The +:raw+ behavior was Sequel's historical behavior, but unless
-# you fully understand the reprecussions of PostgreSQL using a
+# you fully understand the repercussions of PostgreSQL using a
 # numeric type for integer values, you should not use it.
 #
 # To get the current default behavior of raising an exception for

data/lib/sequel/extensions/pg_hstore.rb

@@ -326,7 +326,7 @@ module Sequel
   Database.register_extension(:pg_hstore, Postgres::HStore::DatabaseMethods)
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Hash
     # Create a new HStore using the receiver as the input
@@ -350,4 +350,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_hstore_ops.rb

@@ -63,7 +63,7 @@
 #   DB[:tab].update(h: Sequel.hstore_op(:h).delete('k1'))
 #  
 # On PostgreSQL 14+, The hstore <tt>[]</tt> method will use subscripts instead of being
-# the same as +get+, if the value being wrapped is an identifer:
+# the same as +get+, if the value being wrapped is an identifier:
 #
 #   Sequel.hstore_op(:hstore_column)['a']    # hstore_column['a']
 #   Sequel.hstore_op(Sequel[:h][:s])['a']      # h.s['a']
@@ -367,9 +367,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(HStore)
-    # :nocov:
+    # simplecov:enable
       class HStore
         # Wrap the receiver in an HStoreOp so you can easily use the PostgreSQL
         # hstore functions and operators with it.
@@ -401,7 +401,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::HStoreOpMethods
@@ -415,4 +415,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_inet.rb

@@ -41,9 +41,9 @@ module Sequel
         db.instance_exec do
           extend_datasets(InetDatasetMethods)
 
-          # :nocov:
+          # simplecov:disable
           if !defined?(SEQUEL_PG_VERSION_INTEGER) || SEQUEL_PG_VERSION_INTEGER >= 11300
-          # :nocov:
+          # simplecov:enable
             # sequel_pg 1.13.0+ will use inet/cidr conversion procs, but doing so is
             # slower, so don't add the conversion procs if using sequel_pg 1.13.0+.
             meth = IPAddr.method(:new)

data/lib/sequel/extensions/pg_inet_ops.rb

@@ -187,7 +187,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::InetOpMethods
@@ -201,4 +201,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_interval.rb

@@ -35,12 +35,12 @@
 require 'active_support'
 require 'active_support/duration'
 
-# :nocov:
+# simplecov:disable
 begin
   require 'active_support/version'
 rescue LoadError
 end
-# :nocov:
+# simplecov:enable
 
 module Sequel
   module Postgres
@@ -75,11 +75,11 @@ module Sequel
         if defined?(ActiveSupport::Duration::SECONDS_PER_MONTH)
           SECONDS_PER_MONTH = ActiveSupport::Duration::SECONDS_PER_MONTH
           SECONDS_PER_YEAR = ActiveSupport::Duration::SECONDS_PER_YEAR
-        # :nocov:
+        # simplecov:disable
         else
           SECONDS_PER_MONTH = 2592000
           SECONDS_PER_YEAR = 31557600
-        # :nocov:
+        # simplecov:enable
         end
 
         # Parse the interval input string into an ActiveSupport::Duration instance.
@@ -125,11 +125,11 @@ module Sequel
             parts[:seconds] = seconds
           end
 
-          # :nocov:
+          # simplecov:disable
           if USE_PARTS_ARRAY
             parts = parts.to_a
           end
-          # :nocov:
+          # simplecov:enable
 
           ActiveSupport::Duration.new(value, parts)
         end

data/lib/sequel/extensions/pg_json.rb

@@ -206,12 +206,12 @@ module Sequel
     }
 
     if RUBY_VERSION < '2.4'
-      # :nocov:
+      # simplecov:disable
       JSON_PRIMITIVE_WRAPPER_MAPPING[Fixnum] = JSONInteger
       JSON_PRIMITIVE_WRAPPER_MAPPING[Bignum] = JSONInteger
       JSONB_PRIMITIVE_WRAPPER_MAPPING[Fixnum] = JSONBInteger
       JSONB_PRIMITIVE_WRAPPER_MAPPING[Bignum] = JSONBInteger
-      # :nocov:
+      # simplecov:enable
     end
 
     JSON_PRIMITIVE_WRAPPER_MAPPING.freeze
@@ -583,7 +583,7 @@ module Sequel
   Database.register_extension(:pg_json, Postgres::JSONDatabaseMethods)
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Array
     # Return a Sequel::Postgres::JSONArray proxy to the receiver.
@@ -641,4 +641,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_json_ops.rb

@@ -103,7 +103,7 @@
 #   j.path_query_first_tz('$.foo') # jsonb_path_query_first_tz(jsonb_column, '$.foo')
 #
 # On PostgreSQL 14+, The JSONB <tt>[]</tt> method will use subscripts instead of being
-# the same as +get+, if the value being wrapped is an identifer:
+# the same as +get+, if the value being wrapped is an identifier:
 #
 #   Sequel.pg_jsonb_op(:jsonb_column)[1]       # jsonb_column[1]
 #   Sequel.pg_jsonb_op(:jsonb_column)[1][2]    # jsonb_column[1][2]
@@ -173,7 +173,7 @@
 #
 # If you are also using the pg_json extension, you should load it before
 # loading this extension.  Doing so will allow you to use the #op method on
-# JSONHash, JSONHarray, JSONBHash, and JSONBArray, allowing you to perform json/jsonb operations
+# JSONHash, JSONArray, JSONBHash, and JSONBArray, allowing you to perform json/jsonb operations
 # on json/jsonb literals.
 #
 # In order to get the automatic conversion from a ruby array to a PostgreSQL array
@@ -843,9 +843,9 @@ module Sequel
 
       # Wrap argument in a PGArray if it is an array or a set
       def wrap_input_array(obj)
-        # :nocov:
+        # simplecov:disable
         if Sequel.respond_to?(:pg_array)
-        # :nocov:
+        # simplecov:enable
           case obj
           when Array
             return Sequel.pg_array(obj)
@@ -1074,7 +1074,7 @@ module Sequel
         end
       end
 
-      # Do not auto paramterize default value, as PostgreSQL doesn't allow it.
+      # Do not auto parameterize default value, as PostgreSQL doesn't allow it.
       def default_literal_append(ds, sql, v)
         if sql.respond_to?(:skip_auto_param)
           sql.skip_auto_param do
@@ -1341,7 +1341,7 @@ module Sequel
         end
       end
 
-      # Append path caluse to the SQL
+      # Append path clause to the SQL
       def to_s_append_path(ds, sql, path)
         if path
           sql << ' PATH '
@@ -1349,7 +1349,7 @@ module Sequel
         end
       end
 
-      # Do not auto paramterize default value or path value, as PostgreSQL doesn't allow it.
+      # Do not auto parameterize default value or path value, as PostgreSQL doesn't allow it.
       def default_literal_append(ds, sql, v)
         if sql.respond_to?(:skip_auto_param)
           sql.skip_auto_param do
@@ -1375,9 +1375,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(JSONArray)
-    # :nocov:
+    # simplecov:enable
       class JSONArray
         # Wrap the JSONArray instance in an JSONOp, allowing you to easily use
         # the PostgreSQL json functions and operators with literal jsons.
@@ -1443,7 +1443,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::JSONOpMethods
@@ -1457,4 +1457,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_range.rb

@@ -2,11 +2,11 @@
 #
 # The pg_range extension adds support for the PostgreSQL 9.2+ range
 # types to Sequel.  PostgreSQL range types are similar to ruby's
-# Range class, representating an array of values.  However, they
+# Range class, representing an array of values.  However, they
 # are more flexible than ruby's ranges, allowing exclusive beginnings
 # and endings (ruby's range only allows exclusive endings).
 #
-# When PostgreSQL range values are retreived, they are parsed and returned
+# When PostgreSQL range values are retrieved, they are parsed and returned
 # as instances of Sequel::Postgres::PGRange.  PGRange mostly acts
 # like a Range, but it's not a Range as not all PostgreSQL range
 # type values would be valid ruby ranges.  If the range type value
@@ -459,10 +459,10 @@ module Sequel
         return @range if @range
         raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
         raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
-        # :nocov:
+        # simplecov:disable
         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") if STARTLESS_RANGE_NOT_SUPPORTED && !self.begin
         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") if ENDLESS_RANGE_NOT_SUPPORTED && !self.end
-        # :nocov:
+        # simplecov:enable
         @range = Range.new(self.begin, self.end, exclude_end?)
       end
 
@@ -549,7 +549,7 @@ module Sequel
   Database.register_extension(:pg_range, Postgres::PGRange::DatabaseMethods)
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Range 
     # Create a new PGRange using the receiver as the input range,
@@ -569,4 +569,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_range_ops.rb

@@ -113,7 +113,7 @@ module Sequel
 
       private
 
-      # Create a boolen expression for the given type and argument.
+      # Create a boolean expression for the given type and argument.
       def operator(type, other)
         Sequel::SQL::BooleanExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(OPERATORS[type], [value, other]))
       end
@@ -132,9 +132,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(PGRange)
-    # :nocov:
+    # simplecov:enable
       class PGRange
         # Wrap the PGRange instance in an RangeOp, allowing you to easily use
         # the PostgreSQL range functions and operators with literal ranges.
@@ -144,9 +144,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(PGMultiRange)
-    # :nocov:
+    # simplecov:enable
       class PGMultiRange
         # Wrap the PGRange instance in an RangeOp, allowing you to easily use
         # the PostgreSQL range functions and operators with literal ranges.
@@ -178,7 +178,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::RangeOpMethods
@@ -192,4 +192,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_row.rb

@@ -247,9 +247,9 @@ module Sequel
           if skip(/\)/)
             values << nil
           else
-            # :nocov:
+            # simplecov:disable
             until eos?
-            # :nocov:
+            # simplecov:enable
               if skip(/"/)
                 values << scan(/(\\.|""|[^"])*/).gsub(/\\(.)|"(")/, '\1\2')
                 skip(/"[,)]/)
@@ -563,7 +563,7 @@ module Sequel
   Database.register_extension(:pg_row, Postgres::PGRow::DatabaseMethods)
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Array
     # Wraps the receiver in an anonymous Sequel::Postgres::PGRow::ArrayRow instance.
@@ -582,4 +582,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/pg_row_ops.rb

@@ -159,9 +159,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(PGRow::ArrayRow)
-    # :nocov:
+    # simplecov:enable
       class PGRow::ArrayRow
         # Wrap the PGRow::ArrayRow instance in an PGRowOp, allowing you to easily use
         # the PostgreSQL row functions and operators with literal rows.
@@ -171,9 +171,9 @@ module Sequel
       end
     end
 
-    # :nocov:
+    # simplecov:disable
     if defined?(PGRow::HashRow)
-    # :nocov:
+    # simplecov:enable
       class PGRow::HashRow
         # Wrap the PGRow::ArrayRow instance in an PGRowOp, allowing you to easily use
         # the PostgreSQL row functions and operators with literal rows.
@@ -200,7 +200,7 @@ module Sequel
   end
 end
 
-# :nocov:
+# simplecov:disable
 if Sequel.core_extensions?
   class Symbol
     include Sequel::Postgres::PGRowOp::ExpressionMethods
@@ -214,4 +214,4 @@ if defined?(Sequel::CoreRefinements)
     end
   end
 end
-# :nocov:
+# simplecov:enable

data/lib/sequel/extensions/provenance.rb

@@ -46,11 +46,11 @@ module Sequel
           super(provenance_opts(opts))
         end
       else
-        # :nocov:
+        # simplecov:disable
         def clone(opts = OPTS) # :nodoc:
           super(provenance_opts(opts))
         end
-        # :nocov:
+        # simplecov:enable
       end
 
       %w'select insert update delete'.each do |type|