Why not adopt me?
NAME
Data::Couplet - Yet another (But Hopefully Better) Key-Value Storage mechanism
VERSION
version 0.02004314
SYNOPSIS
use
Data::Couplet;
# Retain order.
my
$couplet
= Data::Couplet->new(
a
=>
$b
,
c
=>
$d
);
my
$output
=
$couplet
->value(
'a'
);
# returns $b;
my
$hash
= {
'this is a'
=>
'key'
};
$couplet
->set(
$hash
,
"hello"
);
$couplet
->value(
$hash
);
# hello
ALPHA CODE
Lots of stuff is probably still broken, unimplemented, untested.
User beware
DIFFERENT
Why is this module different?
- 1. No Tied Hashes.
-
Tied hashes are IMO Ugly. Objects are far more handy for many things. Especially in moose world. You want tied hashes, do it yourself.
- 2. Trying Hard to preserve non-scalar keys.
-
I want it to be possible, to retain arbitrary references used as keys.
- 3. Permutation.
-
Its not here yet, but there Will eventually be reordering functions.
I seriously looked all over CPAN for something that suited my needs and didn't find any.
I then tried with Tie::IxHash::ButMoreFun, and then discovered that how I was using Tie::IxHash wasn't even sustainable on different versions of Perl, and based on the 1997 release date, I gave up on seeing that fixed.
METHODS
CONSTRUCTOR
->new( %orderd_pairs )
Create a new Data::Couplet entity using a series of ordered pairs.
$c
= Data::Couplet->new(
'a'
=>
'b'
,
'c'
=>
'd'
);
ENTRY CREATION
->set( Any $object, Any $value ) : $self : Modifier
Record the association of a key ( any object that can be coerced into a string ) to a value.
New entries are pushed on the logical right hand end of it in array context.
# { 'a' => 'b', 'c' => 'd' }
set(
'a'
,
'e'
);
# { 'a' => 'e', 'c' => 'd' }
set(
'e'
,
'a'
);
# { 'a' => 'e', 'c' => 'd', 'e' => 'a' }
ENTRY REMOVAL
->unset( Array[Any] @objects ) : $self : Modifier
Entries are ripped out of the structure, and all items moved around to fill the void.
# { 'a' => 'b', 'c' => 'd','e'=>'f' }
->unset(
'c'
);
# { 'a' => 'b', 'e'=>'f' }
->unset(
'a'
);
# { 'e' => 'f' }
->unset_at( Array[Int] @indices ) : $self : Modifier
Like ->unset, except you know where ( logically ) in the order off things the entry you wish to delete is.
->unset_at( 1 );
->unset_at( 0 );
Should be identical to the above code.
->unset_key( Array[Str] @keys ) : $self : Modifier
This is what ->unset ultimately calls, except ->unset does implicit object_to_key conversion first. At present, that's not anything huge, its just $object
to convert it to a string. But this may change at some future time. So use that method instead.
VALUE MANIPULATION
->value( Any $object ) : Any $value
Returns a value associated with a key object. See "unset" for the semantics of what object keys are.
->value_at( Int $index ) : Any $value
Like value, but you need to know where in the data set the item is.
->values() : Any @list
returns an array of all stored values in order.
->values_ref() : ArrayRef[Any] $list
Just some nice syntax for [$o->values]
->key_values() : Any @list
Returns an ordered sequence of key,value pairs, just like that passed to the constructor.
my
@d
=
$o
->key_values()
while
(
@d
){
my
$key
=
shift
@d
;
my
$value
=
shift
@d
;
"$key => $value\n"
}
->key_values_paired() : Any[ArrayRef] @list
Returns like ->key_values does but key/value is grouped for your convenience
for
(
$o
->key_values_paired() ){
my
(
$key
,
$value
) = @{
$_
};
}
KEY MANIPULATION
->keys() : @list
returns all known keys in order
->key_at( Int $index ) : String
Given an index, return the key that holds that place.
->key_object( String $key ) : Any $object
Given a string key, returns the object stored there.
This is probably very unhelpful to you unless you explicitly asked us for our internal key name.
->key_object_at( Int $index ) : Any $object
As with key_object, except partially useful, because you can fetch by ID.
METHODS FROM PLUGINS
By default, this package imports a few methods from various plug-ins.
AUTHOR
Kent Fredric <kentnl at cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Kent Fredric.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.