refinements 11.0.1 → 11.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdcd2042bcfde5031fad3d0049e01fc4e1ad23a9d4841ee601fdcb02a96d3af
-  data.tar.gz: 55fac5447439c53705870a9409268e96aaf633e7a420f9d4678257f9b68f078d
+  metadata.gz: 91fae4e74017d86d0ca24e153dc7210fd9503276ccdf79da032e0f8f8ee2d181
+  data.tar.gz: eeea2c49941fe6508e9e4aab89aa42f38c2e23efd48b4f5381d4487a08061e3b
 SHA512:
-  metadata.gz: 81949b0fb95b4aca53d6fd88f51d8cb4f0c8738bbb3eac83816880ff6b479ac86228847dd6660d8a99a861c5e3aee6e6985a0628764af037b328db55422cc7fb
-  data.tar.gz: 6b40c6be0c5cc6304366fe60c8df54bca9e3ab366338f45308b2267f9a81f6adb123002740feb933af3313a0349a9a5035c39525c0b90d48f875842fefd0c3cf
+  metadata.gz: '08e77b3c0837d2158593f431a6cdd427cdc7cf9a1605178c0762444549b08807e3f3890cd7c578a8bc429d453b8961d38649a412b4616ea92889f745a721bc1f'
+  data.tar.gz: 20525ddb58f09cb45d4fc39fe652d0790b156f387bea40fe0f6574be0d396d8607cc6e9f692a6e6feee78f8608b102aaab5d9219ef6f4d43dcdd5e73e8ad4957

data/README.adoc

@@ -14,6 +14,7 @@ Enhances the following objects:
 
 * Array
 * BigDecimal
+* Data
 * DateTime
 * Hash
 * IO
@@ -78,6 +79,7 @@ gem "refinements", require: false
 ----
 require "refinements/arrays"
 require "refinements/big_decimals"
+require "refinements/data"
 require "refinements/date_times"
 require "refinements/hashes"
 require "refinements/ios"
@@ -100,6 +102,7 @@ refinement(s):
 class Example
   using Refinements::Arrays
   using Refinements::BigDecimals
+  using Refinements::Data
   using Refinements::DateTimes
   using Refinements::Hashes
   using Refinements::IOs
@@ -184,9 +187,9 @@ Answers the first element which evaluates to true from a filtered collection.
 [source,ruby]
 ----
 handlers = [
-  ->(object) { object if object == :b },
+  -> object { object if object == :b },
   proc { false },
-  ->(object) { object if object == :a }
+  -> object { object if object == :a }
 ]
 
 handlers.filter_find                                # Enumerator::Lazy
@@ -206,7 +209,7 @@ Adds given array or elements without mutating itself.
 
 ===== #intersperse
 
-Inserts additional elements or an array between all members of given array.
+Inserts additional elements, or an array, between all members of given array.
 
 [source,ruby]
 ----
@@ -234,11 +237,13 @@ Answers the maximum extracted value from a collection of objects.
 
 [source,ruby]
 ----
-Point = Struct.new :x, :y
+Point = Data.define :x, :y
 points = [Point[x: 1, y: 2], Point[x: 0, y: 1], Point[x: 2, y: 3]]
 
-points.maximum(:x)  # 2
-points.maximum(:y)  # 3
+points.maximum :x  # 2
+points.maximum :y  # 3
+points.maximum :z  # undefined method `z' for #<data Point x=1, y=2> (NoMethodError)
+[].maximum :x      # nil
 ----
 
 ===== #mean
@@ -259,11 +264,13 @@ Answers the minimum extracted value from a collection of objects.
 
 [source,ruby]
 ----
-Point = Struct.new :x, :y
+Point = Data.define :x, :y
 points = [Point[x: 1, y: 2], Point[x: 0, y: 1], Point[x: 2, y: 3]]
 
-points.minimum(:x)  # 0
-points.minimum(:y)  # 1
+points.minimum :x  # 0
+points.minimum :y  # 1
+points.minimum :z  # undefined method `z' for #<data Point x=1, y=2> (NoMethodError)
+[].minimum :x      # nil
 ----
 
 ===== #pad
@@ -289,7 +296,7 @@ array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C
 array.pick :name          # "a"
 array.pick :name, :label  # ["a", "A"]
 array.pick                # nil
-[].pick(:other)           # nil
+[].pick :other            # nil
 ----
 
 ===== #pluck
@@ -312,10 +319,10 @@ Answers mutated array where an element -- at a specific index -- is replaced by
 
 [source,ruby]
 ----
-%i[a b c].replace_at(0, :x)      # [:x, :b, :c]
-%i[a b c].replace_at(1, :x)      # [:a, :x, :c]
-%i[a b c].replace_at(1, :x, :y)  # [:a, :x, :y, :c]
-%i[a b c].replace_at(-1, :x)     # [:a, :b, :x]
+%i[a b c].replace_at 0, :x      # [:x, :b, :c]
+%i[a b c].replace_at 1, :x      # [:a, :x, :c]
+%i[a b c].replace_at 1, :x, :y  # [:a, :x, :y, :c]
+%i[a b c].replace_at -1, :x     # [:a, :b, :x]
 ----
 
 ===== #ring
@@ -397,6 +404,28 @@ Allows one to inspect a big decimal with numeric representation.
 BigDecimal.new("5.0E-10").inspect  # "#<BigDecimal:3fd3d458fe84 0.0000000005>"
 ----
 
+==== Data
+
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+implementation = Data.define :a, :b, :c
+
+one = implementation.new a: 1, b: 2, c: 3
+two = implementation.new a: 3, b: 2, c: 1
+three = Data.define(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples.
+
 ==== DateTime
 
 ===== .utc
@@ -532,6 +561,26 @@ example.deep_symbolize_keys!  # {a: {b: 1}}
 example                       # {a: {b: 1}}
 ----
 
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+one = {a: 1, b: 2, c: 3}
+two = {a: 3, b: 2, c: 1}
+three = {c: 3, b: 2, a: 1}
+four = Data.define(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {}
+one.diff four        # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples. Two hashes with the same keys but defined in different order behave as if they had the same key order.
+
 ===== #fetch_value
 
 Fetches value for exiting or missing key. Behavior is identical to `#fetch` except when the value of
@@ -751,12 +800,12 @@ Answers full stream by rewinding to beginning of stream and reading all content.
 io = IO.new IO.sysopen(Pathname("demo.txt").to_s, "w+")
 io.write "This is a demo."
 
-io.reread                  # "This is a demo."
-io.reread 4                # "This"
+io.reread           # "This is a demo."
+io.reread 4         # "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)  # "This is a demo."
-buffer                     # "This is a demo."
+io.reread(buffer:)  # "This is a demo."
+buffer              # "This is a demo."
 ----
 
 ===== #squelch
@@ -784,17 +833,17 @@ Answers previously written content by rewinding to beginning of device.
 # With File.
 device = Logger::LogDevice.new "test.log"
 device.write "Test."
-device.reread                                # "Test."
+device.reread  # "Test."
 
 # With StringIO.
 device = Logger::LogDevice.new StringIO.new
 device.write "Test."
-device.reread                                # "Test."
+device.reread  # "Test."
 
 # With STDOUT.
 device = Logger::LogDevice.new $stdout
 device.write "Test."
-device.reread                                # ""
+device.reread  # ""
 ----
 
 ==== Logger
@@ -808,17 +857,17 @@ Answers previously written content by rewinding to beginning of log.
 # With File.
 logger = Logger.new "test.log"
 logger.write "Test."
-logger.reread                     # "Test."
+logger.reread  # "Test."
 
 # With StringIO.
 logger = Logger.new StringIO.new
 logger.write "Test."
-logger.reread                     # "Test."
+logger.reread  # "Test."
 
 # With STDOUT.
 logger = Logger.new $stdout
 logger.write "Test."
-logger.reread                     # ""
+logger.reread  # ""
 ----
 
 ===== #any
@@ -846,7 +895,7 @@ construct a valid path.
 
 [source,ruby]
 ----
-Pathname(nil)  # Pathname("")
+Pathname nil  # Pathname("")
 ----
 
 ===== .home
@@ -972,9 +1021,9 @@ Deletes a path prefix and answers new pathname.
 
 [source,ruby]
 ----
-Pathname("a/path/example-test.rb").delete_prefix("example-")  # Pathname("a/path/test.rb")
-Pathname("example-test.rb").delete_prefix("example-")         # Pathname("test.rb")
-Pathname("example-test.rb").delete_prefix("miss")             # Pathname("example-test.rb")
+Pathname("a/path/example-test.rb").delete_prefix "example-"  # Pathname("a/path/test.rb")
+Pathname("example-test.rb").delete_prefix "example-"         # Pathname("test.rb")
+Pathname("example-test.rb").delete_prefix "miss"             # Pathname("example-test.rb")
 ----
 
 ===== #delete_suffix
@@ -983,9 +1032,9 @@ Deletes a path suffix and answers new pathname.
 
 [source,ruby]
 ----
-Pathname("a/path/test-example.rb").delete_suffix("-example")  # Pathname("a/path/test.rb")
-Pathname("test-example.rb").delete_suffix("-example")         # Pathname("test.rb")
-Pathname("test-example.rb").delete_suffix("miss")             # Pathname("test-example.rb")
+Pathname("a/path/test-example.rb").delete_suffix "-example"  # Pathname("a/path/test.rb")
+Pathname("test-example.rb").delete_suffix "-example"         # Pathname("test.rb")
+Pathname("test-example.rb").delete_suffix "miss"             # Pathname("test-example.rb")
 ----
 
 ===== #directories
@@ -1039,10 +1088,10 @@ Same behavior as `String#gsub` but answers a path with patterns replaced with de
 
 [source,ruby]
 ----
-Pathname("/a/path/some/path").gsub("path", "test")
+Pathname("/a/path/some/path").gsub "path", "test"
 # Pathname("/a/test/some/test")
 
-Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test")
+Pathname("/%placeholder%/some/%placeholder%").gsub "%placeholder%", "test"
 # Pathname("/test/some/test")
 ----
 
@@ -1090,11 +1139,11 @@ Pathname("example.txt").name # Pathname("example")
 
 ===== #relative_parent
 
-Answers relative path from parent directory. This is a complement to `#relative_path_from`.
+Answers relative path from parent directory. This complements: `#relative_path_from`.
 
 [source,ruby]
 ----
-Pathname("/one/two/three").relative_parent("/one")  # Pathname "two"
+Pathname("/one/two/three").relative_parent "/one"  # Pathname "two"
 ----
 
 ===== #remove_dir
@@ -1333,8 +1382,8 @@ io.reread    # "This is a test."
 io.reread 4  # "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)  # "This is a test."
-buffer                     # "This is a test."
+io.reread(buffer:)  # "This is a test."
+buffer              # "This is a test."
 ----
 
 ==== Struct
@@ -1355,6 +1404,26 @@ Example.with_positions 1, 2, 3  # #<struct a=1, b=2, c=3>
 Example.with_positions 1        # #<struct a=1, b=nil, c=nil>
 ----
 
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+implementation = Struct.new :a, :b, :c
+
+one = implementation.new a: 1, b: 2, c: 3
+two = implementation.new a: 3, b: 2, c: 1
+three = Struct.new(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples.
+
 ===== #merge
 
 Merges multiple attributes without mutating itself and supports any object that responds to `#to_h`.
@@ -1393,8 +1462,7 @@ example                             # #<struct Struct::Example a=10, b=20, c=30>
 
 Transforms values without mutating itself. An optional hash can be supplied to target specific
 attributes. In the event that a block isn't supplied, the struct will answer itself since there is
-nothing to operate on. Behavior is the same regardless of whether the struct is constructed using
-positional or keyword arguments. Works regardless of whether the struct is constructed with
+nothing to operate on. Works regardless of whether the struct is constructed with
 positional or keyword arguments.
 
 [source,ruby]
@@ -1412,8 +1480,7 @@ example                                                           # #<struct Str
 
 Transforms values while mutating itself. An optional hash can be supplied to target specific
 attributes. In the event that a block isn't supplied, the struct will answer itself since there is
-nothing to operate on. Behavior is the same regardless of whether the struct is constructed using
-positional or keyword arguments. Works regardless of whether the struct is constructed with
+nothing to operate on. Works regardless of whether the struct is constructed with
 positional or keyword arguments.
 
 [source,ruby]

data/lib/refinements/data.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "refinements/shared/values/diff"
+
+module Refinements
+  # Provides additional enhancements to the Struct primitive.
+  module Data
+    refine ::Data do
+      import_methods Shared::Values::Diff
+    end
+  end
+end

data/lib/refinements/hashes.rb

@@ -45,7 +45,13 @@ module Refinements
 
       def deep_symbolize_keys! = replace(deep_symbolize_keys)
 
-      def fetch_value(key, *default_value, &) = fetch(key, *default_value, &) || default_value.first
+      def diff other
+        return differences_from other if other.is_a?(self.class) && keys.sort! == other.keys.sort!
+
+        each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
+      end
+
+      def fetch_value(key, *default, &) = fetch(key, *default, &) || default.first
 
       def flatten_keys prefix: nil, delimiter: "_"
         reduce({}) do |accumulator, (key, value)|
@@ -88,6 +94,13 @@ module Refinements
              .map { |(_type, key)| self[key] || self[key.to_s] }
              .then { |values| yield values }
       end
+
+      private
+
+      def differences_from other
+        result = merge(other.to_h) { |_, one, two| [one, two].uniq }
+        result.select { |_, diff| diff.size == 2 }
+      end
     end
   end
 end

data/lib/refinements/shared/values/diff.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Refinements
+  module Shared
+    module Values
+      # Provides shared whole value functionality for knowing the difference between two objects.
+      module Diff
+        def diff other
+          if other.is_a? self.class
+            to_h.merge(other.to_h) { |_, one, two| [one, two].uniq }
+                .select { |_, diff| diff.size == 2 }
+          else
+            to_h.each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/refinements/structs.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "refinements/shared/values/diff"
+
 module Refinements
   # Provides additional enhancements to the Struct primitive.
   module Structs
@@ -8,6 +10,8 @@ module Refinements
     end
 
     refine Struct do
+      import_methods Shared::Values::Diff
+
       def merge(...) = dup.merge!(...)
 
       def merge! object = nil

data/lib/refinements.rb

@@ -2,6 +2,7 @@
 
 require "refinements/arrays"
 require "refinements/big_decimals"
+require "refinements/data"
 require "refinements/date_times"
 require "refinements/hashes"
 require "refinements/ios"

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "11.0.1"
+  spec.version = "11.1.1"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/refinements"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 11.0.1
+  version: 11.1.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-06-19 00:00:00.000000000 Z
+date: 2023-11-04 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -51,6 +51,7 @@ files:
 - lib/refinements.rb
 - lib/refinements/arrays.rb
 - lib/refinements/big_decimals.rb
+- lib/refinements/data.rb
 - lib/refinements/date_times.rb
 - lib/refinements/hashes.rb
 - lib/refinements/ios.rb
@@ -59,6 +60,7 @@ files:
 - lib/refinements/pathnames.rb
 - lib/refinements/shared/enumerables/many.rb
 - lib/refinements/shared/ios/reread.rb
+- lib/refinements/shared/values/diff.rb
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb
 - lib/refinements/structs.rb
@@ -90,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.21
 signing_key:
 specification_version: 4
 summary: A collection of core Ruby object refinements.

metadata.gz.sig

@@ -1,2 +1,3 @@
-#�],�Gi�ָ7G��ͣDw�>�'���1D4z���+Ph(Y��&i�?���[�N)��3��bGc�a0��OW��g+gV܈9e⍋dD��u�G��y��"ʥ��O�Bkl�a2mz���˗���Qx�
-�_8�����&�e�������KiEYm�ꏪgH[��?��I�a��üw�h!P��Nx{�bo��q�k]+8��}���֎)4�>���o�̂K�*�"���e�n�T��Q�e�W!2��C�~�z�t+����	o.(o���+�en:����T�
+im����uV�?q��6�
+bM���e������T�`�!��9�u=�R
��[m���E,�j�q=7�a��EB\w8�\�����ɖv���U��(m��Z�
��ڌ#N�p�'���f���,�=��.�x}8_����D����ce�:�(�hr�0���!u�y	��z��#L[����x������^B���*K4ўS�+�S#�@��kR!9Z��[1���
+�k�_�p�}˄��i|�a��!N!��΢hB��<0؛M�ri��?��U&u���̍9����i1?���9����V���D:�=1Y�X|�A6��v�c9�z��Y���u���u�.m�1e����nW��R�+�s���B���~�`l�h