Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Hash::FieldHash(3)    User Contributed Perl Documentation   Hash::FieldHash(3)

[![Build
Status](https://travis-ci.org/gfx/p5-Hash-FieldHash.svg?branch=master)](https://travis-ci.org/gfx/p5-Hash-FieldHash)

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

VERSION
       This document describes Hash::FieldHash version 0.15.

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 chainable 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.

perl v5.32.1			  2021-02-28		    Hash::FieldHash(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | ROBUSTNESS | NOTES | DEPENDENCIES | BUGS | SEE ALSO | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Hash::FieldHash&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help