NAME
Gnuplot::Builder::PartiallyKeyedList - a list part of which you can randomly access
SYNOPSIS
use Gnuplot::Builder::PartiallyKeyedList;
sub print_pkl {
my $pkl = shift;
$pkl->each(sub {
my ($key, $value) = @_;
printf('%s : %s'."\n", (defined($key) ? $key : "-"), $value);
});
}
my $pkl = Gnuplot::Builder::PartiallyKeyedList->new;
$pkl->add("1");
$pkl->set(a => 2);
$pkl->add(3);
$pkl->add(4);
$pkl->set(b => 5);
print_pkl $pkl;
## => - : 1
## => a : 2
## => - : 3
## => - : 4
## => b : 5
$pkl->set(a => "two");
print_pkl $pkl;
## => - : 1
## => a : two
## => - : 3
## => - : 4
## => b : 5
my $another = Gnuplot::Builder::PartiallyKeyedList->new;
$another->add(6);
$another->set(b => "five");
$pkl->merge($another);
print_pkl $pkl;
## => - : 1
## => a : two
## => - : 3
## => - : 4
## => b : five
## => - : 6DESCRIPTION
This is an internal module for Gnuplot::Builder distribution. However it's general enough for separate distribution. If you are interested in it, just contact me.
Gnuplot::Builder::PartiallyKeyedList is similar to Tie::IxHash. It maintains an ordered associative array. The difference is that it can contain entries without keys. So essentially, it's a list in which some entries have keys.
The data model of this module is depicted below.
You can access all entries sequentially.
|
| [entry 0]
| [entry 1] key: a <--- You can access some of
| [entry 2] the entries randomly.
| [entry 3] key: hoge <---
| [entry 4] key: foobar <---
| [entry 5]
vCLASS METHODS
$pkl = Gnuplot::Builder::PartiallyKeyedList->new()
The constructor. It creates an empty list.
OBJECT METHODS
$pkl->set($key, $value)
Set the value for the $key to $value. $key must be a defined string.
If $key is already set in $pkl, the existing value is replaced. If $key doesn't exist in $pkl, a new keyed entry is added.
$value = $pkl->get($key)
Get the value for the $key.
If $key doesn't exist in $pkl, it returns undef.
$value = $pkl->get_at($index)
($key, $value) = $pkl->get_at($index)
Get an entry at $index. $index starts with 0.
This method can return both keyed and non-keyed entries. For non-keyed entries, the return value $key is undef.
In scalar context, it returns $value only. In list context, it returns $key and $value.
Complexity of get_at(0) is guaranteed to be O(1).
@keys = $pkl->get_all_keys()
Get the list of all keys.
@values = $pkl->get_all_values()
Get the list of all values.
$does_exist = $pkl->exists($key)
Return true if $key exists in $pkl. False otherwise.
$value = $pkl->delete($key)
Delete the value for the $key from the $pkl.
If $key exists, it returns the value for the $key. If $key doesn't exist, it returns undef.
$pkl->add($entry)
Add a non-keyed entry to the $pkl.
$size = $pkl->size()
Get the size of the list. This includes both keyed and non-keyed entries.
$pkl->each($code)
Iterate over all the entries in $pkl from the head, and execute the $code for each entry.
$code is a code-ref that is called for each entry.
$code->($key, $value)$code is passed two arguments, $key and $value. For non-keyed entry, $key is undef. For keyed entry, $key is the key of the entry. $value is the value of the entry in both cases.
Currently, you must not alter $pkl while iterating.
$pkl->merge($another_pkl)
Merge all entries in $another_pkl into $pkl. This is a mutator method.
Non-keyed entries in $another_pkl are just added to $pkl.
Keyed entries in $another_pkl replace existing entries in $pkl. If the key doesn't exist in $pkl, the entry is added.
AUTHOR
Toshio Ito, <toshioito at cpan.org>