292 lines
8.1 KiB
HTML
292 lines
8.1 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Tie::IxHash</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Tie::IxHash</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2015-06-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Tie::IxHash - ordered associative arrays for Perl
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# simple usage
|
|
use Tie::IxHash;
|
|
tie HASHVARIABLE, 'Tie::IxHash' [, LIST];
|
|
|
|
# OO interface with more powerful features
|
|
use Tie::IxHash;
|
|
TIEOBJECT = Tie::IxHash->new( [LIST] );
|
|
TIEOBJECT->Splice( OFFSET [, LENGTH [, LIST]] );
|
|
TIEOBJECT->Push( LIST );
|
|
TIEOBJECT->Pop;
|
|
TIEOBJECT->Shift;
|
|
TIEOBJECT->Unshift( LIST );
|
|
TIEOBJECT->Keys( [LIST] );
|
|
TIEOBJECT->Values( [LIST] );
|
|
TIEOBJECT->Indices( LIST );
|
|
TIEOBJECT->Delete( [LIST] );
|
|
TIEOBJECT->Replace( OFFSET, VALUE, [KEY] );
|
|
TIEOBJECT->Reorder( LIST );
|
|
TIEOBJECT->SortByKey;
|
|
TIEOBJECT->SortByValue;
|
|
TIEOBJECT->Length;
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This Perl module implements Perl hashes that preserve the order in which the
|
|
hash elements were added. The order is not affected when values
|
|
corresponding to existing keys in the IxHash are changed. The elements can
|
|
also be set to any arbitrary supplied order. The familiar perl array
|
|
operations can also be performed on the IxHash.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Standard TIEHASH Interface</H3>
|
|
|
|
|
|
|
|
|
|
|
|
The standard <TT>"TIEHASH"</TT> mechanism is available. This interface is
|
|
recommended for simple uses, since the usage is exactly the same as
|
|
regular Perl hashes after the <TT>"tie"</TT> is declared.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Object Interface</H3>
|
|
|
|
|
|
|
|
This module also provides an extended object-oriented interface that can be
|
|
used for more powerful operations with the IxHash. The following methods
|
|
are available:
|
|
<DL COMPACT>
|
|
<DT id="1"><FONT SIZE="-1">FETCH, STORE, DELETE, EXISTS</FONT><DD>
|
|
|
|
|
|
These standard <TT>"TIEHASH"</TT> methods mandated by Perl can be used directly.
|
|
See the <TT>"tie"</TT> entry in <I><A HREF="/cgi-bin/man/man2html?1+perlfunc">perlfunc</A></I>(1) for details.
|
|
<DT id="2">Push, Pop, Shift, Unshift, Splice<DD>
|
|
|
|
|
|
These additional methods resembling Perl functions are available for
|
|
operating on key-value pairs in the IxHash. The behavior is the same as the
|
|
corresponding perl functions, except when a supplied hash key already exists
|
|
in the hash. In that case, the existing value is updated but its order is
|
|
not affected. To unconditionally alter the order of a supplied key-value
|
|
pair, first <TT>"DELETE"</TT> the IxHash element.
|
|
<DT id="3">Keys<DD>
|
|
|
|
|
|
Returns an array of IxHash element keys corresponding to the list of supplied
|
|
indices. Returns an array of all the keys if called without arguments.
|
|
Note the return value is mostly only useful when used in a list context
|
|
(since perl will convert it to the number of elements in the array when
|
|
used in a scalar context, and that may not be very useful).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a single argument is given, returns the single key corresponding to
|
|
the index. This is usable in either scalar or list context.
|
|
<DT id="4">Values<DD>
|
|
|
|
|
|
Returns an array of IxHash element values corresponding to the list of supplied
|
|
indices. Returns an array of all the values if called without arguments.
|
|
Note the return value is mostly only useful when used in a list context
|
|
(since perl will convert it to the number of elements in the array when
|
|
used in a scalar context, and that may not be very useful).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a single argument is given, returns the single value corresponding to
|
|
the index. This is usable in either scalar or list context.
|
|
<DT id="5">Indices<DD>
|
|
|
|
|
|
Returns an array of indices corresponding to the supplied list of keys.
|
|
Note the return value is mostly only useful when used in a list context
|
|
(since perl will convert it to the number of elements in the array when
|
|
used in a scalar context, and that may not be very useful).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a single argument is given, returns the single index corresponding to
|
|
the key. This is usable in either scalar or list context.
|
|
<DT id="6">Delete<DD>
|
|
|
|
|
|
Removes elements with the supplied keys from the IxHash.
|
|
<DT id="7">Replace<DD>
|
|
|
|
|
|
Substitutes the IxHash element at the specified index with the supplied
|
|
value-key pair. If a key is not supplied, simply substitutes the value at
|
|
index with the supplied value. If an element with the supplied key already
|
|
exists, it will be removed from the IxHash first.
|
|
<DT id="8">Reorder<DD>
|
|
|
|
|
|
This method can be used to manipulate the internal order of the IxHash
|
|
elements by supplying a list of keys in the desired order. Note however,
|
|
that any IxHash elements whose keys are not in the list will be removed from
|
|
the IxHash.
|
|
<DT id="9">Length<DD>
|
|
|
|
|
|
Returns the number of IxHash elements.
|
|
<DT id="10">SortByKey<DD>
|
|
|
|
|
|
Reorders the IxHash elements by textual comparison of the keys.
|
|
<DT id="11">SortByValue<DD>
|
|
|
|
|
|
Reorders the IxHash elements by textual comparison of the values.
|
|
<DT id="12">Clear<DD>
|
|
|
|
|
|
Resets the IxHash to its pristine state: with no elements at all.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use Tie::IxHash;
|
|
|
|
# simple interface
|
|
$t = tie(%myhash, 'Tie::IxHash', 'a' => 1, 'b' => 2);
|
|
%myhash = (first => 1, second => 2, third => 3);
|
|
$myhash{fourth} = 4;
|
|
@keys = keys %myhash;
|
|
@values = values %myhash;
|
|
print("y") if exists $myhash{third};
|
|
|
|
# OO interface
|
|
$t = Tie::IxHash->new(first => 1, second => 2, third => 3);
|
|
$t->Push(fourth => 4); # same as $myhash{'fourth'} = 4;
|
|
($k, $v) = $t->Pop; # $k is 'fourth', $v is 4
|
|
$t->Unshift(neg => -1, zeroth => 0);
|
|
($k, $v) = $t->Shift; # $k is 'neg', $v is -1
|
|
@oneandtwo = $t->Splice(1, 2, foo => 100, bar => 101);
|
|
|
|
@keys = $t->Keys;
|
|
@values = $t->Values;
|
|
@indices = $t->Indices('foo', 'zeroth');
|
|
@itemkeys = $t->Keys(@indices);
|
|
@itemvals = $t->Values(@indices);
|
|
$t->Replace(2, 0.3, 'other');
|
|
$t->Delete('second', 'zeroth');
|
|
$len = $t->Length; # number of key-value pairs
|
|
|
|
$t->Reorder(reverse @keys);
|
|
$t->SortByKey;
|
|
$t->SortByValue;
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
You cannot specify a negative length to <TT>"Splice"</TT>. Negative indexes are <FONT SIZE="-1">OK,</FONT>
|
|
though.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTE</H2>
|
|
|
|
|
|
|
|
Indexing always begins at 0 (despite the current <TT>$[</TT> setting) for
|
|
all the functions.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>TODO</H2>
|
|
|
|
|
|
|
|
Addition of elements with keys that already exist to the end of the IxHash
|
|
must be controlled by a switch.
|
|
<P>
|
|
|
|
Provide <TT>"TIEARRAY"</TT> interface when it stabilizes in Perl.
|
|
<P>
|
|
|
|
Rewrite using XSUBs for efficiency.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gurusamy Sarathy <A HREF="mailto:gsar@umich.edu">gsar@umich.edu</A>
|
|
<P>
|
|
|
|
Copyright (c) 1995 Gurusamy Sarathy. All rights reserved.
|
|
This program is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
Version 1.23
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?1+perl">perl</A></I>(1)
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="13"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="14"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="15"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="16"><A HREF="#lbAE">Standard TIEHASH Interface</A><DD>
|
|
<DT id="17"><A HREF="#lbAF">Object Interface</A><DD>
|
|
</DL>
|
|
<DT id="18"><A HREF="#lbAG">EXAMPLE</A><DD>
|
|
<DT id="19"><A HREF="#lbAH">BUGS</A><DD>
|
|
<DT id="20"><A HREF="#lbAI">NOTE</A><DD>
|
|
<DT id="21"><A HREF="#lbAJ">TODO</A><DD>
|
|
<DT id="22"><A HREF="#lbAK">AUTHOR</A><DD>
|
|
<DT id="23"><A HREF="#lbAL">VERSION</A><DD>
|
|
<DT id="24"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:58 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|