google-cloud-spanner 2.26.0 → 2.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cafab317421fcff06f127fb2d156c722f67b8e5d1914ae68d3e0ec8b56db4f76
-  data.tar.gz: 26820cba11c9d0a94d5dbaaff4c28ea0581c25ef3d7a9876d39ef5ca42fe5edc
+  metadata.gz: 2950745d1ef3cf6be982e2bc64a29ce467e8a15710293265181d41dd138a80ad
+  data.tar.gz: 6e96c531e76300e6d77d5d261ec0d09da96157f82aa3f4c32c502b52ce6b6f74
 SHA512:
-  metadata.gz: 58624fe569f909d5923f897fc02c6865c4861dd289ec5b1f58aead9ae01b87968ebd7b5e23d0305e4661011fd4bc2e3479cc08c08ef0c19b320daa2e68300fca
-  data.tar.gz: c011acec4ad559505de0b89e77dae6d2046f7e00768a421f4bd347ff25a3b8ee35673f1714037528e1d13572e054486ded0fd666d253df9b322a2c90ef19a1bf
+  metadata.gz: 55291fac48fb628c64d4df17266cf1a07babbd918b8411e7116e8ba23b0430c20dbf0f210098f27052bbcd9d97c9e3ed0ec2937a4c342cb5994946df2dcf2ac6
+  data.tar.gz: b2e91d7c79a316a69b3657eace1232936a13013236117170b974a9487e0d9fdd5c9de34bba851ffbe310a26c6864954fd94de68df91fdb1a9d64bd06773d5aff

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 2.27.0 (2025-05-28)
+
+#### Features
+
+* Spanner Interval type ([#162](https://github.com/googleapis/ruby-spanner/issues/162)) 
+* Updated required Ruby version to 3.1 ([#160](https://github.com/googleapis/ruby-spanner/issues/160)) 
+
 ### 2.26.0 (2025-03-24)
 
 #### Features

data/lib/google/cloud/spanner/batch_write_results.rb

@@ -92,9 +92,9 @@ module Google
         #
         # @yield [::Google::Cloud::Spanner::BatchWriteResults::BatchResult]
         #
-        def each &block
+        def each(&)
           if defined? @results
-            @results.each(&block)
+            @results.each(&)
           else
             results = []
             @enumerable.each do |grpc|

data/lib/google/cloud/spanner/convert.rb

@@ -19,6 +19,7 @@ require "stringio"
 require "base64"
 require "bigdecimal"
 require "google/cloud/spanner/data"
+require "google/cloud/spanner/interval"
 
 module Google
   module Cloud
@@ -108,6 +109,8 @@ module Google
               else
                 Google::Protobuf::Value.new string_value: obj.to_json
               end
+            when Interval
+              obj.to_s
             when Google::Protobuf::MessageExts
               proto_class = obj.class
               content = proto_class.encode obj
@@ -252,6 +255,8 @@ module Google
               BigDecimal value.string_value
             when :JSON
               JSON.parse value.string_value
+            when :INTERVAL
+              Interval.parse value.string_value
             when :PROTO
               descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(type.proto_type_fqn).msgclass
               content = Base64.decode64 value.string_value

data/lib/google/cloud/spanner/interval.rb

@@ -0,0 +1,309 @@
+# Copyright 2017 Google LLC
+#
+# 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
+#
+#     https://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.
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Interval
+      #
+      # Represents an interval of time by storing the time components
+      # in months, days and nanoseconds.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   iso_8601_string = "P1Y2M3DT4H5M6S"
+      #   interval = Google::Cloud::Spanner::Interval::parse iso_8601_string
+      #
+      #   puts interval # "P1Y2M3DT4H5M6S"
+      class Interval
+        NANOSECONDS_IN_A_SECOND = 1_000_000_000
+        NANOSECONDS_IN_A_MINUTE = NANOSECONDS_IN_A_SECOND * 60
+        NANOSECONDS_IN_AN_HOUR = NANOSECONDS_IN_A_MINUTE * 60
+        NANOSECONDS_IN_A_MILLISECOND = 1_000_000
+        NANOSECONDS_IN_A_MICROSECOND = 1_000
+        MAX_MONTHS = 120_000
+        MIN_MONTHS = -MAX_MONTHS
+        MAX_DAYS = 3_660_000
+        MIN_DAYS = -MAX_DAYS
+        MAX_NANOSECONDS = 316_224_000_000_000_000_000
+        MIN_NANOSECONDS = -316_224_000_000_000_000_000
+
+        private_constant :NANOSECONDS_IN_A_SECOND, :NANOSECONDS_IN_A_MINUTE, :NANOSECONDS_IN_AN_HOUR,
+                         :NANOSECONDS_IN_A_MILLISECOND, :NANOSECONDS_IN_A_MICROSECOND, :MAX_MONTHS,
+                         :MIN_MONTHS, :MAX_DAYS, :MIN_DAYS, :MAX_NANOSECONDS, :MIN_NANOSECONDS
+
+        class << self
+          # rubocop:disable Metrics/AbcSize
+          # rubocop:disable Metrics/MethodLength
+
+          # Parses an ISO8601 string and returns an Interval instance.
+          #
+          # The accepted format for the ISO8601 standard is:
+          # `P[n]Y[n]M[n]DT[n]H[n]M[n[.fraction]]S`
+          # where `n` represents an integer number.
+          #
+          # @param interval_string [String] An ISO8601 formatted string.
+          # @return [Google::Cloud::Spanner::Interval]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   iso_8601_string = "P1Y2M3DT4H5M6S"
+          #   interval = Google::Cloud::Spanner::Interval::parse iso_8601_string
+          #
+          #   puts interval # "P1Y2M3DT4H5M6S"
+          #
+          def parse interval_string
+            pattern = /^
+              P(?!$)
+              (?:(?<years>-?\d+)Y)?
+              (?:(?<months>-?\d+)M)?
+              (?:(?<days>-?\d+)D)?
+              (?:T(?!$)
+              (?:(?<hours>-?\d+)H)?
+              (?:(?<minutes>-?\d+)M)?
+              (?:(?<seconds>-?(?!S)\d*(?:[\.,]\d{1,9})?)S)?)?
+              $
+            /x
+            interval_months = 0
+            interval_days = 0
+            interval_nanoseconds = 0
+
+            matches = interval_string.match pattern
+
+            raise ArgumentError, "The provided string does not follow ISO8601 standard." if matches.nil?
+
+            raise ArgumentError, "The provided string does not follow ISO8601 standard." if matches.captures.empty?
+
+            interval_months += matches[:years].to_i * 12 if matches[:years]
+
+            interval_months += matches[:months].to_i if matches[:months]
+
+            interval_days = matches[:days].to_i if matches[:days]
+
+            interval_nanoseconds += matches[:hours].to_i * NANOSECONDS_IN_AN_HOUR if matches[:hours]
+
+            interval_nanoseconds += matches[:minutes].to_i * NANOSECONDS_IN_A_MINUTE if matches[:minutes]
+
+            # Only seconds can be fractional. Both period and comma are valid inputs.
+            if matches[:seconds]
+              interval_nanoseconds += (matches[:seconds].gsub(",", ".").to_f * NANOSECONDS_IN_A_SECOND).to_i
+            end
+
+            Interval.new interval_months, interval_days, interval_nanoseconds
+          end
+
+          # rubocop:enable Metrics/AbcSize
+          # rubocop:enable Metrics/MethodLength
+
+          # Returns an Interval instance with the given months.
+          #
+          # @param months [Integer]
+          # @return [Interval]
+          def from_months months
+            Interval.new months, 0, 0
+          end
+
+          # Returns an Interval instance with the given days.
+          #
+          # @param days [Integer]
+          # @return [Interval]
+          def from_days days
+            Interval.new 0, days, 0
+          end
+
+          # Returns an Interval instance with the given seconds.
+          #
+          # @param seconds [Integer]
+          # @return [Interval]
+          def from_seconds seconds
+            nanoseconds = seconds * NANOSECONDS_IN_A_SECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given milliseconds.
+          #
+          # @param milliseconds [Integer]
+          # @return [Interval]
+          def from_milliseconds milliseconds
+            nanoseconds = milliseconds * NANOSECONDS_IN_A_MILLISECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given microseconds.
+          #
+          # @param microseconds [Integer]
+          # @return [Interval]
+          def from_microseconds microseconds
+            nanoseconds = microseconds * NANOSECONDS_IN_A_MICROSECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given nanoseconds.
+          #
+          # @param nanoseconds [Integer]
+          # @return [Interval]
+          def from_nanoseconds nanoseconds
+            Interval.new 0, 0, nanoseconds
+          end
+        end
+
+
+        # Converts the [Interval] to an ISO8601 Standard string.
+        # @return [String] The interval's ISO8601 string representation.
+        def to_s
+          # Memoizing it as the logic can be a bit heavy.
+          @to_s ||= to_string
+        end
+
+        ##
+        # @private Creates a new Google::Cloud::Spanner instance.
+        def initialize months, days, nanoseconds
+          if months > MAX_MONTHS || months < MIN_MONTHS
+            raise ArgumentError, "The Interval class supports months from #{MIN_MONTHS} to #{MAX_MONTHS}."
+          end
+          @months = months
+
+          if days > MAX_DAYS || days < MIN_DAYS
+            raise ArgumentError, "The Interval class supports days from #{MIN_DAYS} to #{MAX_DAYS}."
+          end
+          @days = days
+
+          if nanoseconds > MAX_NANOSECONDS || nanoseconds < MIN_NANOSECONDS
+            raise ArgumentError, "The Interval class supports nanoseconds from #{MIN_NANOSECONDS} to #{MAX_NANOSECONDS}"
+          end
+          @nanoseconds = nanoseconds
+        end
+
+
+        # @return [Integer] The numbers of months in the time interval.
+        attr_reader :months
+
+        # @return [Integer] The numbers of days in the time interval.
+        attr_reader :days
+
+        # @return [Integer] The numbers of nanoseconds in the time interval.
+        attr_reader :nanoseconds
+
+
+        ##
+        # Standard value equality check for this object.
+        #
+        # @param [Object] other An object to compare with.
+        # @return [Boolean]
+        def eql? other
+          other.is_a?(Interval) &&
+            months == other.months &&
+            days == other.days &&
+            nanoseconds == other.nanoseconds
+        end
+        alias == eql?
+
+        ##
+        # Generate standard hash code for this object.
+        #
+        # @return [Integer]
+        #
+        def hash
+          @hash ||= [@months, @days, @nanoseconds].hash
+        end
+
+        private
+
+        def match_sign value
+          value.negative? ? -1 : 1
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable Metrics/PerceivedComplexity
+
+        # Converts [Interval] to an ISO8601 Standard string.
+        # @return [String] The interval's ISO8601 string representation.
+        def to_string
+          # Months should be converted to years and months.
+          years = @months.fdiv(12).truncate
+          months = @months % (match_sign(@months) * 12)
+
+          days = @days
+
+          # Nanoseconds should be converted to hours, minutes and seconds components.
+          remaining_nanoseconds = @nanoseconds
+
+          hours = (remaining_nanoseconds.abs / NANOSECONDS_IN_AN_HOUR) * match_sign(remaining_nanoseconds)
+          remaining_nanoseconds %= (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_AN_HOUR)
+          minutes = (remaining_nanoseconds.abs / NANOSECONDS_IN_A_MINUTE) * match_sign(remaining_nanoseconds)
+          remaining_nanoseconds %= (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_A_MINUTE)
+
+          # Only seconds can be fractional, and can have a maximum of 9 characters after decimal. Therefore,
+          # we convert the remaining nanoseconds to an integer for formatting.
+          seconds = (remaining_nanoseconds.abs / NANOSECONDS_IN_A_SECOND) * match_sign(remaining_nanoseconds)
+          nanoseconds = remaining_nanoseconds % (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_A_SECOND)
+
+          interval_string = ["P"]
+
+          interval_string.append "#{years}Y" if years.nonzero?
+
+          interval_string.append "#{months}M" if months.nonzero?
+
+          interval_string.append "#{days}D" if days.nonzero?
+
+          if hours.nonzero? || minutes.nonzero? || seconds.nonzero? || nanoseconds.nonzero?
+            interval_string.append "T"
+
+            interval_string.append "#{hours}H" if hours.nonzero?
+
+            interval_string.append "#{minutes}M" if minutes.nonzero?
+
+            if seconds.nonzero? || nanoseconds.nonzero?
+              interval_string.append "#{format_seconds seconds, nanoseconds}S"
+            end
+          end
+
+          return "P0Y" if interval_string == ["P"]
+
+          interval_string.join
+        end
+
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+
+        # Formats decimal values to be in multiples of 3 length.
+        # @return [String]
+        def format_seconds seconds, nanoseconds
+          return seconds if nanoseconds.zero?
+          add_sign = seconds.zero? && nanoseconds.negative?
+
+          nanoseconds_str = nanoseconds.abs.to_s.rjust 9, "0"
+          nanoseconds_str = nanoseconds_str.gsub(/0+$/, "")
+
+          target_length =
+            if nanoseconds_str.length <= 3
+              3
+            elsif nanoseconds_str.length <= 6
+              6
+            else
+              9
+            end
+
+          nanoseconds_str = (nanoseconds_str + ("0" * target_length))[0...target_length]
+          "#{add_sign ? '-' : ''}#{seconds}.#{nanoseconds_str}"
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/spanner/pool.rb

@@ -221,8 +221,8 @@ module Google
           @keepalive_task.execute
         end
 
-        def future &block
-          Concurrent::Future.new(executor: @thread_pool, &block).execute
+        def future(&)
+          Concurrent::Future.new(executor: @thread_pool, &).execute
         end
       end
     end

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.26.0".freeze
+      VERSION = "2.27.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.26.0
+  version: 2.27.0
 platform: ruby
 authors:
 - Mike Moore
 - Chris Smith
 bindir: bin
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -150,6 +150,7 @@ files:
 - lib/google/cloud/spanner/instance/config/list.rb
 - lib/google/cloud/spanner/instance/job.rb
 - lib/google/cloud/spanner/instance/list.rb
+- lib/google/cloud/spanner/interval.rb
 - lib/google/cloud/spanner/lar_headers.rb
 - lib/google/cloud/spanner/mutation_group.rb
 - lib/google/cloud/spanner/partition.rb
@@ -175,14 +176,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.9
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API
 test_files: []