Clone(3) User Contributed Perl Documentation Clone(3)
NAME
Clone - recursively copy Perl datatypes
SYNOPSIS
use Clone 'clone';
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}; # '1'
print $data->{foo}{answer}; # '42'
You can also add it to your class:
package Foo;
use parent 'Clone';
sub new { bless {}, shift }
package main;
my $obj = Foo->new;
my $copy = $obj->clone;
DESCRIPTION
This module provides a clone() method which makes recursive copies of
nested hash, array, scalar and reference types, including tied
variables and objects.
clone() takes a scalar argument and duplicates it. To duplicate lists,
arrays or hashes, pass them in by reference, e.g.
my $copy = clone (\@array);
# or
my %copy = %{ clone (\%hash) };
EXAMPLES
Cloning Blessed Objects
package Person;
sub new {
my ($class, $name) = @_;
bless { name => $name, friends => [] }, $class;
}
package main;
use Clone 'clone';
my $person = Person->new('Alice');
my $clone = clone($person);
# $clone is a separate object with the same data
push @{$person->{friends}}, 'Bob';
print scalar @{$clone->{friends}}; # 0
Handling Circular References
Clone properly handles circular references, preventing infinite loops:
my $a = { name => 'A' };
my $b = { name => 'B', ref => $a };
$a->{ref} = $b; # circular reference
my $clone = clone($a);
# Circular structure is preserved in the clone
Cloning Weakened References
use Scalar::Util 'weaken';
my $obj = { data => 'important' };
my $container = { strong => $obj, weak => $obj };
weaken($container->{weak});
my $clone = clone($container);
# Both strong and weak references are preserved correctly
Cloning Tied Variables
use Tie::Hash;
tie my %hash, 'Tie::StdHash';
%hash = (a => 1, b => 2);
my $clone = clone(\%hash);
# The tied behavior is preserved in the clone
LIMITATIONS
o Maximum Recursion Depth
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.
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.
You can override the depth limit by passing it as the second
argument to clone():
my $copy = clone($data, 8000); # allow deeper recursion
o Filehandles and IO Objects
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.
o Code References
Code references (subroutines) are cloned by reference, not by
value. The cloned coderef points to the same subroutine as the
original.
o Thread Safety
Clone is not explicitly thread-safe. Use appropriate
synchronization when cloning data structures across threads.
PERFORMANCE
Clone is implemented in C using Perl's XS interface, making it very
fast for most use cases.
o When to use Clone
Clone is optimized for speed and works best with:
o Shallow to medium-depth structures (3 levels or fewer)
o Data structures that need fast cloning in hot code paths
o Structures containing blessed objects and tied variables
o When to use Storable::dclone
Storable's dclone() may be faster for:
o Very deep structures (4+ levels)
o When you need serialization features
Benchmarking your specific use case is recommended for
performance-critical applications.
CAVEATS
o Cloned objects are deep copies
Changes to the clone do not affect the original, and vice versa.
This includes nested references and objects.
o Object internals
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.
o Memory usage
Cloning large data structures creates a complete copy in memory.
Ensure you have sufficient memory available.
SEE ALSO
Storable's dclone() 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 dclone() can be faster for structures 4 or more
levels deep.
Other modules that may be of interest:
Clone::PP(3) - Pure Perl implementation of Clone
Scalar::Util(3) - For "weaken()" and other scalar utilities
Data::Dumper(3) - For debugging and inspecting data structures
SUPPORT
o Bug Reports and Feature Requests
Please report bugs on GitHub:
<https://github.com/garu/Clone/issues>
o Source Code
The source code is available on GitHub:
<https://github.com/garu/Clone>
COPYRIGHT
Copyright 2001-2026 Ray Finch. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHOR
Ray Finch "<rdf@cpan.org>"
Breno G. de Oliveira "<garu@cpan.org>", Nicolas Rochelemagne
"<atoomic@cpan.org>" and Florian Ragwitz "<rafl@debian.org>" perform
routine maintenance releases since 2012.
perl v5.34.3 2026-03-28 Clone(3)
clone 0.500.0 - Generated Fri Apr 3 07:51:27 CDT 2026