Hash::FieldHash(3pm)

🦋 NAME 🦋

Hash::FieldHash — lightweight field hash for inside-out objects ✨

That (3pm) up there means this is a Perl module page living in the User Contributed Perl Documentation section, and bestie, we are reading it together right now.

Also — full disclosure, the very top of the original page has a Travis CI build status badge, and we do not lose details around here, so here's the URL it points at, verbatim: https://travis-ci.org/gfx/p5-Hash-FieldHash.svg?branch=master. cute. iconic. 🎀

---

🌸 VERSION 🌸

This document describes Hash::FieldHash version 0.15.

💅 SYNOPSIS 💅

okay so here's the whole vibe in one block:

use Hash::FieldHash qw(:all);

fieldhash my %foo;

fieldhashes \my(%bar, %baz);

{
        my $o = Something->new();

        $foo{$o} = 42;

        print $foo{$o}; # => 42
}
# when $o is released, $foo{$o} is also deleted,
# so %foo is empty in here.

# in a class
{
        package Foo;
        use Hash::FieldHash qw(:all);

        fieldhash my %bar, 'bar'; # make an accessor
}

my $obj = bless {}, 'Foo';
$obj->bar(10); # does $bar{$obj} = 10

✨ DESCRIPTION ✨

Hash::FieldHash provides the field hash mechanism which supports the inside-out technique. that's the whole serve 💅

You may already know Hash::Util::FieldHash. It's a very useful module, but it's too complex to understand the functionality and it's only available in 5.10. H::U::F::Compat is available for pre-5.10, but it is too slow to use.

So this module is the better alternative to H::U::F, with these features:

• Simpler interface — Hash::FieldHash hands you a few functions, that's it: fieldhash() and fieldhashes(). That's enough. periodt.
• Higher performance — Hash::FieldHash is faster than Hash::Util::FieldHash, because its internals use simpler structures. speed. 🏎️
• Relic support — even though Hash::FieldHash uses a new feature introduced in Perl 5.10 (the uvar magic for hashes described in "GUTS" in Hash::Util::Fieldhash), it supports Perl 5.8 using the traditional tie-hash layer. respecting the elders fr fr 🫶

🎀 INTERFACE 🎀

🍓 Exportable functions

• fieldhash(%hash, ?$name, ?$package) — creates a field hash. The first argument must be a hash, no negotiating. The optional $name and $package indicate the name of the field, which will create rw-accessors, using the same name as $name. Returns nothing.
• fieldhashes(@hash_refs) — creates a number of field hashes. All the arguments must be hash references. Returns nothing.
• from_hash($object, \%fields) — fills the named fields associated with $object with %fields. The keys of %fields can be simple or fully qualified. Returns $object.
• to_hash($object, ?-fully_qualify) — serializes $object into a hash reference.

If the -fully_qualify option is supplied, field keys are fully qualified.

For example:

package MyClass;
use FieldHash qw(:all);

fieldhash my %foo => 'foo';

sub new{
        my $class = shift;
        my $self  = bless {}, $class;
        return from_hash($self, @_);
}

package MyDerivedClass;
use parent -norequire => 'MyClass';
use FieldHash qw(:all);

fieldhash my %bar => 'bar';

package main;

my $o = MyDerivedClass->new(foo => 10, bar => 20);
my $p = MyDerivedClass->new('MyClass::foo' => 10, 'MyDerivedClass::bar' => 20);

use Data::Dumper;
print Dumper($o->to_hash());
# $VAR1 = { foo => 10, bar => 20 }

print Dumper($o->to_hash(-fully_qualify));
# $VAR1 = { 'MyClass::foo' => 10, 'MyDerived::bar' => 20 }

---

🔥 ROBUSTNESS 🔥

🧵 Thread support

Just as Hash::Util::FieldHash does, Hash::FieldHash fully supports threading using the CLONE method. threads said yes to slay 🧵✨

Memory leaks

Hash::FieldHash itself does not leak memory, but it may leak memory when you use hash references as field hash keys, because of an issue of perl 5.10.0. so like… be aware bestie 🙈

💜 NOTES 💜

The type of field hash keys

Hash::FieldHash accepts only references and registered addresses as its keys, whereas Hash::Util::FieldHash accepts any type of scalars. picky? no, curated.

According to "The Generic Object" in Hash::Util::FieldHash, non-reference keys in H::U::F are used for class fields. That is, all the fields defined by H::U::F act as both object fields and class fields by default. It seems confusing; if you do not want them to be class fields, you must check the type of $self explicitly. In addition, these class fields are never inherited. This behavior seems problematic, so Hash::FieldHash restricts the type of keys.

The ID of field hash keys

While Hash::Util::FieldHash uses refaddr as the IDs of field hash keys, Hash::FieldHash allocates arbitrary integers as the IDs.

What accessors return

The accessors fieldhash() creates are chainable accessors. That is, it returns the $object (i.e. $self) with a parameter, whereas it returns the $value without it. chainable accessors are the moment, no cap.

For example:

my $o = YourClass->new();
$o->foo(42);           # returns $o itself
my $value = $o->foo(); # retuns 42

🌈 DEPENDENCIES 🌈

Perl 5.8.5 or later, and a C compiler. yes bestie we are compiling C, hydrate first 💧

💀 BUGS 💀

No bugs have been reported. (iconic. unmatched. 💅)

Please report any bugs or feature requests to the author.

🫶 SEE ALSO 🫶

• Hash::Util::FieldHash.
• Hash::Util::FieldHash::Compat.
• "Magic Virtual Tables" in perlguts.
• Class::Std describes the inside-out technique.

👑 AUTHOR 👑

Fuji, Goro (gfx) <gfuji(at)cpan.org>.

⭐ LICENSE AND COPYRIGHT ⭐

Copyright (c) 2009-2010, Fuji, Goro. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🫶 this was perl v5.42.3, dated 2026-08-20, so if you're reading this from the future… hi, you look amazing 💖