txt: ## clone.md
  clone
  
  Combined from primary sources listed below.
  
  # [In Match](#___top "go to top of document")[§](#(Match)_method_clone "direct link")
  
  See primary documentation
  [in context](/type/Match#method_clone)
  for **method clone**.
  
  ```raku
  method clone()
  ```
  
  Clones the `Match` object.
  
  # [In Array](#___top "go to top of document")[§](#(Array)_method_clone "direct link")
  
  See primary documentation
  [in context](/type/Array#method_clone)
  for **method clone**.
  
  ```raku
  method clone(Array:D: --> Array:D)
  ```
  
  Clones the original `Array`. Modifications of elements in the clone are not propagated to the original and vice-versa:
  
  ```raku
  my @a = <a b c>; my @b = @a.clone;
  @b[1] = 42; @a.push: 72;
  say @b; # OUTPUT: «[a 42 c]␤»
  say @a; # OUTPUT: «[a b c 72]␤»
  ```
  
  However, note that the reifier *is* shared between the two Arrays, so both Arrays will have the same elements even when each is randomly-generated on reification and each element will be reified just once, regardless of whether the reification was done by the clone or the original Array. **Note:** just as reifying an Array from multiple threads is not safe, so is, for example, reifying the clone from one thread while reifying the original from another thread is not safe.
  
  ```raku
  my @a = 1, {rand} … ∞; my @b = @a.clone;
  say @b[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»
  say @a[^3]; # OUTPUT: «(1 0.0216426755282736 0.567660896142156)␤»
  ```
  
  # [In Mu](#___top "go to top of document")[§](#(Mu)_method_clone "direct link")
  
  See primary documentation
  [in context](/type/Mu#method_clone)
  for **method clone**.
  
  ```raku
  multi method clone(Mu:U: *%twiddles)
  multi method clone(Mu:D: *%twiddles)
  ```
  
  This method will clone type objects, or die if it's invoked with any argument.
  
  ```raku
  say Num.clone( :yes )
  # OUTPUT: «(exit code 1) Cannot set attribute values when cloning a type object␤  in block <unit>␤␤»
  
  ```
  
  If invoked with value objects, it creates a shallow clone of the invocant, including shallow cloning of private attributes. Alternative values for *public* attributes can be provided via named arguments with names matching the attributes' names.
  
  ```raku
  class Point2D {
      has ($.x, $.y);
      multi method gist(Point2D:D:) {
          "Point($.x, $.y)";
      }
  }
  
  my $p = Point2D.new(x => 2, y => 3);
  
  say $p;                     # OUTPUT: «Point(2, 3)␤»
  say $p.clone(y => -5);      # OUTPUT: «Point(2, -5)␤»
  
  ```
  
  Note that `.clone` does not go the extra mile to shallow-copy `@.` and `%.` sigiled attributes and, if modified, the modifications will still be available in the original object:
  
  ```raku
  class Foo {
      has $.foo is rw = 42;
      has &.boo is rw = { say "Hi" };
      has @.bar       = <a b>;
      has %.baz       = <a b c d>;
  }
  
  my $o1 = Foo.new;
  with my $o2 = $o1.clone {
      .foo = 70;
      .bar = <Z Y>;
      .baz = <Z Y X W>;
      .boo = { say "Bye" };
  }
  
  # Hash and Array attribute modifications in clone appear in original as well:
  say $o1;
  # OUTPUT: «Foo.new(foo => 42, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
  say $o2;
  # OUTPUT: «Foo.new(foo => 70, bar => ["Z", "Y"], baz => {:X("W"), :Z("Y")}, …␤»
  $o1.boo.(); # OUTPUT: «Hi␤»
  $o2.boo.(); # OUTPUT: «Bye␤»
  
  ```
  
  To clone those, you could implement your own `.clone` that clones the appropriate attributes and passes the new values to `Mu.clone`, for example, via [`nextwith`](/language/functions#sub_nextwith).
  
  ```raku
  class Bar {
      has $.quux;
      has @.foo = <a b>;
      has %.bar = <a b c d>;
      method clone { nextwith :foo(@!foo.clone), :bar(%!bar.clone), |%_  }
  }
  
  my $o1 = Bar.new( :42quux );
  with my $o2 = $o1.clone {
      .foo = <Z Y>;
      .bar = <Z Y X W>;
  }
  
  # Hash and Array attribute modifications in clone do not affect original:
  say $o1;
  # OUTPUT: «Bar.new(quux => 42, foo => ["a", "b"], bar => {:a("b"), :c("d")})␤»
  say $o2;
  # OUTPUT: «Bar.new(quux => 42, foo => ["Z", "Y"], bar => {:X("W"), :Z("Y")})␤»
  
  ```
  
  The `|%_` is needed to slurp the rest of the attributes that would have been copied via shallow copy.
  
  # [In DateTime](#___top "go to top of document")[§](#(DateTime)_method_clone "direct link")
  
  See primary documentation
  [in context](/type/DateTime#method_clone)
  for **method clone**.
  
  ```raku
  method clone(DateTime:D: :$year, :$month, :$day, :$hour, :$minute, :$second, :$timezone, :&formatter)
  ```
  
  Creates a new `DateTime` object based on the invocant, but with the given arguments overriding the values from the invocant.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
  # OUTPUT: «2015-12-24T00:23:00Z␤»
  ```
  
  Note that this can lead to invalid dates in some circumstances:
  
  ```raku
  say DateTime.new("2012-02-29T12:34:56Z").clone(year => 2015);
  CATCH { default { put .^name, ': ', .Str } };
  # OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28␤»
  ```
  
  # [In Date](#___top "go to top of document")[§](#(Date)_method_clone "direct link")
  
  See primary documentation
  [in context](/type/Date#method_clone)
  for **method clone**.
  
  ```raku
  method clone(Date:D: :$year, :$month, :$day, :&formatter)
  ```
  
  Creates a new `Date` object based on the invocant, but with the given arguments overriding the values from the invocant.
  
  ```raku
  say Date.new('2015-11-24').clone(month => 12);    # OUTPUT: «2015-12-24␤»
  ```
  