.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Clone 3" .TH Clone 3 2026-03-31 "perl v5.42.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Clone \- recursively copy Perl datatypes .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Clone \*(Aqclone\*(Aq; \& \& my $data = { \& set => [ 1 .. 50 ], \& foo => { \& answer => 42, \& object => SomeObject\->new, \& }, \& }; \& \& my $cloned_data = clone($data); \& \& $cloned_data\->{foo}{answer} = 1; \& print $cloned_data\->{foo}{answer}; # \*(Aq1\*(Aq \& print $data\->{foo}{answer}; # \*(Aq42\*(Aq .Ve .PP You can also add it to your class: .PP .Vb 3 \& package Foo; \& use parent \*(AqClone\*(Aq; \& sub new { bless {}, shift } \& \& package main; \& \& my $obj = Foo\->new; \& my $copy = $obj\->clone; .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module provides a \f(CWclone()\fR method which makes recursive copies of nested hash, array, scalar and reference types, including tied variables and objects. .PP \&\f(CWclone()\fR takes a scalar argument and duplicates it. To duplicate lists, arrays or hashes, pass them in by reference, e.g. .PP .Vb 1 \& my $copy = clone (\e@array); \& \& # or \& \& my %copy = %{ clone (\e%hash) }; .Ve .SH EXAMPLES .IX Header "EXAMPLES" .SS "Cloning Blessed Objects" .IX Subsection "Cloning Blessed Objects" .Vb 5 \& package Person; \& sub new { \& my ($class, $name) = @_; \& bless { name => $name, friends => [] }, $class; \& } \& \& package main; \& use Clone \*(Aqclone\*(Aq; \& \& my $person = Person\->new(\*(AqAlice\*(Aq); \& my $clone = clone($person); \& \& # $clone is a separate object with the same data \& push @{$person\->{friends}}, \*(AqBob\*(Aq; \& print scalar @{$clone\->{friends}}; # 0 .Ve .SS "Handling Circular References" .IX Subsection "Handling Circular References" Clone properly handles circular references, preventing infinite loops: .PP .Vb 3 \& my $a = { name => \*(AqA\*(Aq }; \& my $b = { name => \*(AqB\*(Aq, ref => $a }; \& $a\->{ref} = $b; # circular reference \& \& my $clone = clone($a); \& # Circular structure is preserved in the clone .Ve .SS "Cloning Weakened References" .IX Subsection "Cloning Weakened References" .Vb 1 \& use Scalar::Util \*(Aqweaken\*(Aq; \& \& my $obj = { data => \*(Aqimportant\*(Aq }; \& my $container = { strong => $obj, weak => $obj }; \& weaken($container\->{weak}); \& \& my $clone = clone($container); \& # Both strong and weak references are preserved correctly .Ve .SS "Cloning Tied Variables" .IX Subsection "Cloning Tied Variables" .Vb 3 \& use Tie::Hash; \& tie my %hash, \*(AqTie::StdHash\*(Aq; \& %hash = (a => 1, b => 2); \& \& my $clone = clone(\e%hash); \& # The tied behavior is preserved in the clone .Ve .SH LIMITATIONS .IX Header "LIMITATIONS" .IP \(bu 4 Maximum Recursion Depth .Sp Clone uses a recursion depth counter to prevent stack overflow. The default limit is 4000 rdepth units on Linux/macOS and 2000 on Windows/Cygwin. Each nesting level consumes approximately 2 rdepth units, so the effective limits are roughly 2000 nesting levels on Linux/macOS and 1000 on Windows/Cygwin. .Sp For arrays, exceeding the limit triggers an iterative fallback that avoids stack overflow. For other reference types (hashes, scalars), exceeding the limit produces a warning and a shallow copy. .Sp You can override the depth limit by passing it as the second argument to \f(CWclone()\fR: .Sp .Vb 1 \& my $copy = clone($data, 8000); # allow deeper recursion .Ve .IP \(bu 4 Filehandles and IO Objects .Sp Filehandles and IO objects are cloned, but the underlying file descriptor is shared. Both the original and cloned filehandle will refer to the same file position. For DBI database handles and similar objects, Clone attempts to handle them safely, but behavior may vary depending on the object type. .IP \(bu 4 Code References .Sp Code references (subroutines) are cloned by reference, not by value. The cloned coderef points to the same subroutine as the original. .IP \(bu 4 Thread Safety .Sp Clone is not explicitly thread\-safe. Use appropriate synchronization when cloning data structures across threads. .SH PERFORMANCE .IX Header "PERFORMANCE" Clone is implemented in C using Perl\*(Aqs XS interface, making it very fast for most use cases. .IP \(bu 4 When to use Clone .Sp Clone is optimized for speed and works best with: .RS 4 .IP \(bu 4 Shallow to medium\-depth structures (3 levels or fewer) .IP \(bu 4 Data structures that need fast cloning in hot code paths .IP \(bu 4 Structures containing blessed objects and tied variables .RE .RS 4 .RE .IP \(bu 4 When to use Storable::dclone .Sp Storable\*(Aqs \f(CWdclone()\fR may be faster for: .RS 4 .IP \(bu 4 Very deep structures (4+ levels) .IP \(bu 4 When you need serialization features .RE .RS 4 .RE .PP Benchmarking your specific use case is recommended for performance\-critical applications. .SH CAVEATS .IX Header "CAVEATS" .IP \(bu 4 Cloned objects are deep copies .Sp Changes to the clone do not affect the original, and vice versa. This includes nested references and objects. .IP \(bu 4 Object internals .Sp While Clone handles most blessed objects correctly, objects with XS components or complex internal state may not clone as expected. Test thoroughly with your specific object types. .IP \(bu 4 Memory usage .Sp Cloning large data structures creates a complete copy in memory. Ensure you have sufficient memory available. .SH "SEE ALSO" .IX Header "SEE ALSO" Storable\*(Aqs \f(CWdclone()\fR is a flexible solution for cloning variables, albeit slower for average\-sized data structures. Simple and naive benchmarks show that Clone is faster for data structures with 3 or fewer levels, while \f(CWdclone()\fR can be faster for structures 4 or more levels deep. .PP Other modules that may be of interest: .PP Clone::PP \- Pure Perl implementation of Clone .PP Scalar::Util \- For \f(CWweaken()\fR and other scalar utilities .PP Data::Dumper \- For debugging and inspecting data structures .SH SUPPORT .IX Header "SUPPORT" .IP \(bu 4 Bug Reports and Feature Requests .Sp Please report bugs on GitHub: .IP \(bu 4 Source Code .Sp The source code is available on GitHub: .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2001\-2026 Ray Finch. All Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH AUTHOR .IX Header "AUTHOR" Ray Finch \f(CW\*(C`\*(C'\fR .PP Breno G. de Oliveira \f(CW\*(C`\*(C'\fR, Nicolas Rochelemagne \f(CW\*(C`\*(C'\fR and Florian Ragwitz \f(CW\*(C`\*(C'\fR perform routine maintenance releases since 2012.