From a1ef01c3f71a92c845391198fb9eeb26ade66d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Tue, 8 Dec 2020 01:58:24 +0100 Subject: [PATCH 1/2] Improve docs for `Object#dup` --- src/object.cr | 49 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/src/object.cr b/src/object.cr index 5abc1388eb40..6d87e018ad05 100644 --- a/src/object.cr +++ b/src/object.cr @@ -234,15 +234,54 @@ class Object self end - # Returns a shallow copy of this object. + # Returns a shallow copy (“duplicate”) of this object. # - # As a convention, `clone` is the method used to create a deep copy of - # an object, but this logic isn't defined generically for every type - # because cycles could be involved, and the clone logic might not need - # to clone everything. + # In order to create a new object with the same value as an existing on, there + # are two possible routes: + # + # * create a *shallow copy* (`#dup`): Constructs a new object with all its + # properties' values identical to the original object's properties. They + # are shared references. That means for mutable values that changes to + # either object's values will be present in both's. + # * create a *deep copy* (`#clone`): Constructs a new object with all its + # properties' values being recursive deep copies of the original object's + # properties. + # There is no shared state and the new object is a completely independent + # copy, including everything inside it. This may not be available for every + # type. + # + # A shallow copy is only one level deep whereas a deep copy copies everything + # below. + # + # This distinction is only relevant for compound values. Primitive types + # do not have any properties that could be shared or cloned. + # In that case, `dup` and `clone` are exactly the same. + # + # The `#clone` method can't be defined on `Object`. It's not + # generically available for every type because cycles could be involved, and + # the clone logic might not need to clone everything. # # Many types in the standard library, like `Array`, `Hash`, `Set` and # `Deque`, and all primitive types, define `dup` and `clone`. + # + # Example: + # + # ``` + # original = {"foo" => [1, 2, 3]} + # shallow_copy = original.dup + # deep_copy = original.clone + # + # # "foo" references the same array object for both original and shallow copy, + # # but not for a deep copy: + # original["foo"] << 4 + # shallow_copy["foo"] # => [1, 2, 3, 4] + # deep_copy["foo"] # => [1, 2, 3] + # + # # Assigning new value does not share it to either copy: + # original["foo"] = [1] + # shallow_copy["foo"] # => [1, 2, 3, 4] + # deep_copy["foo"] # => [1, 2, 3] + # ``` abstract def dup # Unsafely reinterprets the bytes of an object as being of another `type`. From cac677e9447d239be3be73a4623df66d65dad090 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Tue, 12 Jan 2021 22:01:14 +0100 Subject: [PATCH 2/2] Update src/object.cr Co-authored-by: Ary Borenszweig --- src/object.cr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/object.cr b/src/object.cr index 6d87e018ad05..d342b3516b0b 100644 --- a/src/object.cr +++ b/src/object.cr @@ -236,7 +236,7 @@ class Object # Returns a shallow copy (“duplicate”) of this object. # - # In order to create a new object with the same value as an existing on, there + # In order to create a new object with the same value as an existing one, there # are two possible routes: # # * create a *shallow copy* (`#dup`): Constructs a new object with all its