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
    ## => - : 6

DESCRIPTION

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]
     v

CLASS 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>