Hash::FieldHash(3pm)

1Hash::FieldHash(3)    User Contributed Perl Documentation   Hash::FieldHash(3)
2
3
4

NAME

6       Hash::FieldHash - A lightweight field hash implementation
7

VERSION

9       This document describes Hash::FieldHash version 0.10.
10

SYNOPSIS

12               use Hash::FieldHash qw(:all);
13
14               fieldhash my %foo;
15
16               fieldhashes \my(%bar, %baz);
17
18               {
19                       my $o = Something->new();
20
21                       $foo{$o} = 42;
22
23                       print $foo{$o}; # => 42
24               }
25               # when $o is released, $foo{$o} is also deleted,
26               # so %foo is empty in here.
27
28               # in a class
29               {
30                       package Foo;
31                       use Hash::FieldHash qw(:all);
32
33                       fieldhash my %bar, 'bar'; # make an accessor
34               }
35
36               my $obj = bless {}, 'Foo';
37               $obj->bar(10); # does $bar{$obj} = 10
38

DESCRIPTION

40       "Hash::FieldHash" provides the field hash mechanism which supports the
41       inside-out technique.
42
43       You may know "Hash::Util::FieldHash". It's a very useful module, but
44       too complex to understand all the functions and only available in 5.10.
45       "H::U::F::Compat" is available for pre-5.10, but it seems too slow to
46       use.
47
48       This is an alternative to "H::U::F" with following features:
49
50       Simpler interface
51           "Hash::FieldHash" provides a few functions:  "fieldhash()" and
52           "fieldhashes()".  That's enough.
53
54       Higher performance
55           "Hash::FieldHash" is faster than "Hash::Util::FieldHash", because
56           its internals use simpler structures.
57
58       Relic support
59           Although "Hash::FieldHash" uses a new feature introduced in Perl
60           5.10, the uvar magic for hashes described in "GUTS" in
61           Hash::Util::Fieldhash, it supports Perl 5.8 using the traditional
62           tie-hash layer.
63

INTERFACE

65   Exportable functions
66       "fieldhash(%hash, ?$name, ?$package)"
67           Creates a field hash. The first argument must be a hash.
68
69           Optional $name and $package indicate the name of the field, which
70           will create rw-accessors, using the same name as $name.
71
72           Returns nothing.
73
74       "fieldhashes(@hash_refs)"
75           Creates a number of field hashes. All the arguments must be hash
76           references.
77
78           Returns nothing.
79
80       "from_hash($object, \%fields)"
81           Fills the named fields associated with $object with %fields.  The
82           keys of %fields can be simple or fully qualified.
83
84           Returns $object.
85
86       "to_hash($object, ?-fully_qualify)"
87           Serializes $object into a hash reference.
88
89           If the "-fully_qualify" option is supplied , field keys are fully
90           qualified.
91
92           For example:
93
94                   package MyClass;
95                   use FieldHash qw(:all);
96
97                   fieldhash my %foo => 'foo';
98
99                   sub new{
100                           my $class = shift;
101                           my $self  = bless {}, $class;
102                           return from_hash($self, @_);
103                   }
104
105                   package MyDerivedClass;
106                   use parent -norequire => 'MyClass';
107                   use FieldHash qw(:all);
108
109                   fieldhash my %bar => 'bar';
110
111                   package main;
112
113                   my $o = MyDerivedClass->new(foo => 10, bar => 20);
114                   my $p = MyDerivedClass->new('MyClass::foo' => 10, 'MyDerivedClass::bar' => 20);
115
116                   use Data::Dumper;
117                   print Dumper($o->to_hash());
118                   # $VAR1 = { foo => 10, bar => 20 }
119
120                   print Dumper($o->to_hash(-fully_qualify));
121                   # $VAR1 = { 'MyClass::foo' => 10, 'MyDerived::bar' => 20 }
122

ROBUSTNESS

124   Thread support
125       As "Hash::Util::FieldHash" does, "Hash::FieldHash" fully supports
126       threading using the "CLONE" method.
127
128   Memory leaks
129       "Hash::FieldHash" itself does not leak memory, but it may leak memory
130       when you uses hash references as field hash keys because of an issue of
131       perl 5.10.0.
132

NOTES

134   The type of field hash keys
135       "Hash::FieldHash" accepts only references and registered addresses as
136       its keys, whereas "Hash::Util::FieldHash" accepts any type of scalars.
137
138       According to "The Generic Object" in Hash::Util::FieldHash, Non-
139       reference keys in "H::U::F" are used for class fields. That is, all the
140       fields defined by "H::U::F" act as both object fields and class fields
141       by default. It seems confusing; if you do not want them to be class
142       fields, you must check the type of $self explicitly. In addition, these
143       class fields are never inherited.  This behavior seems problematic, so
144       "Hash::FieldHash" restricts the type of keys.
145
146   The ID of field hash keys
147       While "Hash::Util::FieldHash" uses "refaddr" as the IDs of field hash
148       keys, "Hash::FieldHash" allocates arbitrary integers as the IDs.
149

DEPENDENCIES

151       Perl 5.8.1 or later, and a C compiler.
152

BUGS

154       No bugs have been reported.
155
156       Please report any bugs or feature requests to the author.
157

AUTHOR

168       Goro Fuji <gfuji(at)cpan.org>.
169

LICENSE AND COPYRIGHT

171       Copyright (c) 2009-2010, Goro Fuji. Some rights reserved.
172
173       This library is free software; you can redistribute it and/or modify it
174       under the same terms as Perl itself.
175
176
177
178perl v5.12.3                      2010-01-10                Hash::FieldHash(3)