GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HASH::FIELDHASH (3)

.ds Aq ’

NAME

Hash::FieldHash - Lightweight field hash for inside-out objects

CONTENTS

VERSION

This document describes Hash::FieldHash version 0.14.

SYNOPSIS



        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.

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

This is a better alternative to H::U::F with following features:
Simpler interface Hash::FieldHash provides a few functions: fieldhash() and fieldhashes(). That’s enough.
Higher performance Hash::FieldHash is faster than Hash::Util::FieldHash, because its internals use simpler structures.
Relic support Although 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.

INTERFACE

    Exportable functions

fieldhash(%hash, ?$name, ?$package) Creates a field hash. The first argument must be a hash.

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

As Hash::Util::FieldHash does, Hash::FieldHash fully supports threading using the CLONE method.

    Memory leaks

Hash::FieldHash itself does not leak memory, but it may leak memory when you uses hash references as field hash keys because of an issue of perl 5.10.0.

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.

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 <B>chainableB> accessors. That is, it returns the $object (i.e. $self) with a parameter, where as it returns the $value without it.

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.

BUGS

No bugs have been reported.

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 HASH::FIELDHASH (3) 2016-03-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.