Clone(3)

📦
version 0.48 · 15 versions
, in fedora 44

✨ Clone(3) ✨

okay bestie, so this is a page from the User Contributed Perl Documentation and it's literally about copying your Perl data 💖 no cap, it's giving main character energy for recursion.

💅 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'

see how the clone got its own lil 1 while the original stayed at 42?? that's the whole vibe 💖 separate. independent. iconic.

You can also add it to your class, like a lil glow-up:

package Foo;
use parent 'Clone';
sub new { bless {}, shift }

package main;

my $obj = Foo->new;
my $copy = $obj->clone;

🎀 DESCRIPTION

This module hands you a clone() method that makes recursive copies of nested hash, array, scalar and reference types — and yes, that includes tied variables and objects. so many vibes, all duplicated 🫶

clone() takes a scalar argument and duplicates it. wanna duplicate lists, arrays or hashes? pass them in by reference, bestie:

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

not the clone being completely unbothered by Bob 💀 she's her own person fr fr

🔥 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

no infinite loop, no crash, just a lil circular situation handled with grace ✨

💜 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

strong stays strong, weak stays weak, the way that it just works 😭👑

🌸 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

the tie travels with the clone. obsessed. 🎀

⭐ LIMITATIONS

okay this is the part where we get real, bestie. read it. it matters.
  • Maximum Recursion Depth — Clone supports structures up to 32,000 levels deep. Deeper structures will cause the clone operation to fail with an error. This limit prevents stack overflow and ensures safe operation.
  • 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.
  • Code References — Code references (subroutines) are cloned by reference, not by value. The cloned coderef points to the same subroutine as the original.
  • 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. it's giving speed 💅

  • When to use Clone

Clone is optimized for speed and works best with:

  • Shallow to medium-depth structures (3 levels or fewer)
  • Data structures that need fast cloning in hot code paths
  • Structures containing blessed objects and tied variables
  • When to use Storable::dclone

Storable's dclone() may be faster for:

  • Very deep structures (4+ levels)
  • When you need serialization features

Benchmarking your specific use case is recommended for performance-critical applications. like, actually test it, don't just vibe-guess 🫶

💀 CAVEATS

  • Cloned objects are deep copies — Changes to the clone do not affect the original, and vice versa. This includes nested references and objects.
  • 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.
  • Memory usage — Cloning large data structures creates a complete copy in memory. Ensure you have sufficient memory available. no cap, big data = big memory, plan accordingly 😭

🦋 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 — Pure Perl implementation of Clone
  • Scalar::Util — For weaken() and other scalar utilities
  • Data::Dumper — For debugging and inspecting data structures

💖 SUPPORT

  • Bug Reports and Feature Requests

Please report bugs on GitHub: <https://github.com/garu/Clone/issues>

  • Source Code

The source code is available on GitHub: <https://github.com/garu/Clone>

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.

and that's the whole page, bestie ✨ this one shipped with perl v5.42.0, dated 2026-03-03, and it's an official User Contributed Perl Documentation page — go forth and clone responsibly 💅💖

📦 where this page comes from