refinements 11.0.1 → 11.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdcd2042bcfde5031fad3d0049e01fc4e1ad23a9d4841ee601fdcb02a96d3af
-  data.tar.gz: 55fac5447439c53705870a9409268e96aaf633e7a420f9d4678257f9b68f078d
+  metadata.gz: 0ec4e17de3e050923d08c34123d8e8f2cf7096e66b3cf035c5fec870470de049
+  data.tar.gz: 8d5d5449055c76a8cb4675acc8ccbd2f9e46b4eb9986e29b04e548847f6d69b3
 SHA512:
-  metadata.gz: 81949b0fb95b4aca53d6fd88f51d8cb4f0c8738bbb3eac83816880ff6b479ac86228847dd6660d8a99a861c5e3aee6e6985a0628764af037b328db55422cc7fb
-  data.tar.gz: 6b40c6be0c5cc6304366fe60c8df54bca9e3ab366338f45308b2267f9a81f6adb123002740feb933af3313a0349a9a5035c39525c0b90d48f875842fefd0c3cf
+  metadata.gz: fe21be9b51f2616eeb94664a85006332dc1b00395cee44540a2adf9b5a08397636e22d35ca4d786887f2d6bfb287bcbca6aee54e89383b71f4976f1433980001
+  data.tar.gz: 5bc27d6026ce8ce38fe522929b54328c67445a7ed89f44ba57759a216b2f098c5fd18696bea14c0ab4719d953b59c6173ebff1e218d2d35b9bcfb9ebfdee43e8

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
@@ -397,6 +400,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 +557,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
@@ -1355,6 +1400,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`.

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,6 +45,12 @@ module Refinements
 
       def deep_symbolize_keys! = replace(deep_symbolize_keys)
 
+      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_value, &) = fetch(key, *default_value, &) || default_value.first
 
       def flatten_keys prefix: nil, delimiter: "_"
@@ -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.0"
   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.0
 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-08-15 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.18
 signing_key:
 specification_version: 4
 summary: A collection of core Ruby object refinements.