Data::Structure::Util(User Contributed Perl DocumentatData::Structure::Util(3)NAMEData::Structure::Util - Change nature of data within a structure
SYNOPSIS
use Data::Structure::Util qw(
has_utf8 utf8_off utf8_on unbless get_blessed get_refs
has_circular_ref circular_off signature
);
# get the objects in the data structure
my $objects_arrayref = get_blessed( $data );
# unbless all objects
unbless( $data );
if ( has_circular_ref( $data ) ) {
print "Removing circular ref!\n";
circular_off( $data );
}
# convert back to latin1 if needed and possible
utf8_off( $data ) if defined has_utf8( $data );
DESCRIPTION
"Data::Structure::Util" is a toolbox to manipulate the data inside a
data structure. It can process an entire tree and perform the operation
requested on each appropriate element.
For example: It can transform all strings within a data structure to
utf8 or transform any utf8 string back to the default encoding. It can
remove the blessing on any reference. It can collect all the objects or
detect if there is a circular reference.
It is written in C for decent speed.
FUNCTIONS
All Data::Structure::Util functions operate on a whole tree. If you
pass them a simple scalar then they will operate on that one scalar.
However, if you pass them a reference to a hash, array, or scalar then
they will iterate though that structure and apply the manipulation to
all elements, and in turn if they are references to hashes, arrays or
scalars to all their elements and so on, recursively.
For speed reasons all manipulations that alter the data structure do
in- place manipulation meaning that rather than returning an altered
copy of the data structure the passed data structure which has been
altered.
Manipulating Data Structures
has_circular_ref($ref)
This function detects if the passed data structure has a circular
reference, that is to say if it is possible by following references
contained in the structure to return to a part of the data
structure you have already visited. Data structures that have
circular references will not be automatically reclaimed by Perl's
garbage collector.
If a circular reference is detected the function returns a
reference to an element within circuit, otherwise the function will
return a false value.
If the version of perl that you are using supports weak references
then any weak references found within the data structure will not
be traversed, meaning that circular references that have had links
successfully weakened will not be returned by this function.
circular_off($ref)
Detects circular references in $ref (as above) and weakens a link
in each so that they can be properly garbage collected when no
external references to the data structure are left.
This means that one (or more) of the references in the data
structure will be told that the should not count towards reference
counting. You should be aware that if you later modify the data
structure and leave parts of it only 'accessible' via weakened
references that those parts of the data structure will be
immediately garbage collected as the weakened references will not
be strong enough to maintain the connection on their own.
The number of references weakened is returned.
get_refs($ref)
Examine the data structure and return a reference to flat array
that contains one copy of every reference in the data structure you
passed.
For example:
my $foo = {
first => [ "inner", "array", { inmost => "hash" } ],
second => \"refed scalar",
};
use Data::Dumper;
# tell Data::Dumper to show nodes multiple times
$Data::Dumper::Deepcopy = 1;
print Dumper get_refs( $foo );
$VAR1 = [
{ 'inmost' => 'hash' },
[ 'inner', 'array', { 'inmost' => 'hash' } ],
\'refed scalar',
{
'first' => [ 'inner', { 'inmost' => 'hash' }, 'array' ],
'second' => \'refed scalar'
}
];
As you can see, the data structure is traversed depth first, so the
top most references should be the last elements of the array. See
get_blessed($ref) below for a similar function for blessed objects.
signature($ref)
Returns a md5 of the passed data structure. Any change at all to
the data structure will cause a different md5 to be returned.
The function examines the structure, addresses, value types and
flags to generate the signature, meaning that even data structures
that would look identical when dumped with Data::Dumper produce
different signatures:
$ref1 = { key1 => [] };
$ref2 = $ref1;
$ref2->{key1} = [];
# this produces the same result, as they look the same
# even though they are different data structures
use Data::Dumper;
use Digest::MD5 qw(md5_hex);
print md5_hex( Dumper( $ref1 ) ), " ", md5_hex( Dumper( $ref2 ) ), "\n";
# cb55d41da284a5869a0401bb65ab74c1 cb55d41da284a5869a0401bb65ab74c1
# this produces differing results
use Data::Structure::Utilqw(signature);
print signature( $ref1 ), " ", signature( $ref2 ), "\n";
# 5d20c5e81a53b2be90521167aefed9db 8b4cba2cbae0fec4bab263e9866d3911
Object Blessing
unbless($ref)
Remove the blessing from any objects found within the passed data
structure. For example:
my $foo = {
'a' => bless( { 'b' => bless( {}, "c" ), }, "d" ),
'e' => [ bless( [], "f" ), bless( [], "g" ), ]
};
use Data::Dumper;
use Data::Structure::Utilqw(unbless);
print Dumper( unbless( $foo ) );
$VAR1 = {
'a' => { 'b' => {} },
'e' => [ [], [] ]
};
Note that the structure looks inside blessed objects for other
objects to unbless.
get_blessed($ref)
Examine the data structure and return a reference to flat array
that contains every object in the data structure you passed. For
example:
my $foo = {
'a' => bless( { 'b' => bless( {}, "c" ), }, "d" ),
'e' => [ bless( [], "f" ), bless( [], "g" ), ]
};
use Data::Dumper;
# tell Data::Dumper to show nodes multiple times
$Data::Dumper::Deepcopy = 1;
use Data::Structure::Utilqw(get_blessed);
print Dumper( get_blessed( $foo ) );
$VAR1 = [
bless( {}, 'c' ),
bless( { 'b' => bless( {}, 'c' ) }, 'd' ),
bless( [], 'f' ),
bless( [], 'g' )
];
This function is essentially the same as "get_refs" but only
returns blessed objects rather than all objects. As with that
function the data structure is traversed depth first, so the top
most objects should be the last elements of the array. Note also
(as shown in the above example shows) that objects within objects
are returned.
utf8 Manipulation Functions
These functions allow you to manipulate the state of the utf8 flags in
the scalars contained in the data structure. Information on the utf8
flag and it's significance can be found in Encode.
has_utf8($var)
Returns $var if the utf8 flag is enabled for $var or any scalar
that a data structure passed in $var contains.
print "this will be printed" if defined has_utf8( "\x{1234}" );
print "this won't be printed" if defined has_utf8( "foo bar" );
Note that you should not check the truth of the return value of
this function when calling it with a single scalar as it is
possible to have a string "0" or "" for which the utf8 flag set;
Since "undef" can never have the utf8 flag set the function will
never return a defined value if the data structure does not contain
a utf8 flagged scalar.
_utf8_off($var)
Recursively disables the utf8 flag on all scalars within $var.
This is the same the "_utf8_off" function of Encode but applies to
any string within $var. The data structure is converted in-place,
and as a convenience the passed variable is returned from the
function.
This function makes no attempt to do any character set conversion
to the strings stored in any of the scalars in the passed data
structure. This means that if perl was internally storing any
character as sequence of bytes in the utf8 encoding each byte in
that sequence will then be henceforth treated as a character in
it's own right.
For example:
my $emoticons = { smile => "\x{236a}" };
use Data::Structure::Utilqw(_utf8_on);
print length( $emoticons->{smile} ), "\n"; # prints 1
_utf8_off( $emoticons );
print length( $emoticons->{smile} ), "\n"; # prints 3
_utf8_on($var)
Recursively enables the utf8 flag on all scalars within $var. This
is the same the "_utf8_on" function of Encode but applies to any
string within $var. The data structure is converted in-place and as
a convenience the passed variable is returned from the function.
As above, this makes no attempt to do any character set conversion
meaning that unless your string contains the valid utf8 byte
sequences for the characters you want you are in trouble. In some
cases incorrect byte sequences can segfault perl. In particular,
the regular expression engine has significant problems with invalid
utf8 that has been incorrectly marked as utf8. You should know
what you are doing if you are using this function; Consider using
the Encode module as an alternative.
Contrary example to the above:
my $emoticons = { smile => "\342\230\272" };
use Data::Structure::Utilqw(_utf8_on);
print length( $emoticons->{smile} ), "\n"; # prints 3
_utf8_on( $emoticons );
print length( $emoticons->{smile} ), "\n"; # prints 1
utf8_on($var)
This routine performs a "sv_utf8_upgrade" on each scalar string in
the passed data structure that does not have the utf8 flag turned
on. This will cause the perl to change the method it uses
internally to store the string from the native encoding (normally
Latin-1 unless locales come into effect) into a utf8 encoding and
set the utf8 flag for that scalar. This means that single byte
letters will now be represented by multi-byte sequences. However,
as long as the "use bytes" pragma is not in effect the string will
be the same length as because as far as perl is concerned the
string still contains the same number of characters (but not
bytes).
This routine is significantly different from "_utf8_on"; That
routine assumes that your string is encoded in utf8 but was marked
(wrongly) in the native encoding. This routine assumes that your
string is encoded in the native encoding and is marked that way,
but you'd rather it be encoded and marked as utf8.
utf8_off($var)
This routine performs a "sv_utf8_downgrade" on each scalar string
in the passed data structure that has the utf8 flag turned on.
This will cause the perl to change the method it uses internally to
store the string from the utf8 encoding into a the native encoding
(normally Latin-1 unless locales are used) and disable the utf8
flag for that scalar. This means that multiple byte sequences that
represent a single character will be replaced by one byte per
character. However, as long as the "use bytes" pragma is not in
effect the string will be the same length as because as far as perl
is concerned the string still contains the same number of
characters (but not bytes).
Please note that not all strings can be converted from utf8 to the
native encoding; In the case that the utf8 character has no
corresponding character in the native encoding Perl will die with
"Wide character in subroutine entry" exception.
This routine is significantly different from "_utf8_off"; That
routine assumes that your string is encoded in utf8 and that you
want to simply mark it as being in the native encoding so that perl
will treat every byte that makes up the character sequences as a
character in it's own right in the native encoding. This routine
assumes that your string is encoded in utf8, but you want it each
character that is currently represented by multi-byte strings to be
replaced by the single byte representation of the same character.
SEE ALSO
Encode, Scalar::Util, Devel::Leak, Devel::LeakTrace
See the excellent article
http://www.perl.com/pub/a/2002/08/07/proxyobject.html from Matt
Sergeant for more info on circular references.
The development version of this module and others can be found at
http://opensource.fotango.com/svn/trunk/Data-Structure-Util/
BUGS
"signature()" is sensitive to the hash randomisation algorithm
This module only recurses through basic hashes, lists and scalar
references. It doesn't attempt anything more complicated.
THANKS TO
James Duncan and Arthur Bergman who helped me and found a name for this
module. Leon Brocard and Richard Clamp have provided invaluable help
to debug this module. Mark Fowler rewrote large chunks of the
documentation and patched a few bugs.
AUTHOR
This release by Andy Armstrong <andy@hexten.net>
Originally by Pierre Denis <pdenis@fotango.com>
http://opensource.fotango.com/
COPYRIGHT
Copyright 2003, 2004 Fotango - All Rights Reserved.
This module is released under the same license as Perl itself.
perl v5.14.1 2008-03-09 Data::Structure::Util(3)
