NAME
    Tie::IxHash::ButMoreFun - A user-friendly wrapper to a Tie::IxHash
    object to fill some use case holes.

VERSION
    version 1.0921204

SYNOPSIS
    Tie::IxHash is a generally ok container, but I found the methods it
    provided lacking.

    I didn't want to use native Hash interface anyway, just wanted a good
    datastorage for key-value pairs that permitted arbitrary order and order
    preservation.

        use aliased 'Tie::IxHash::ButMoreFun' => 'TIxBMF';

        my $i = TIxBMF->new();
        # {}
        $i->set_key_value( 'key' , 'value' );
        # { key => 'value' }
        $i->set_key_value( 'key2' , 'value' );
        # { key => 'value', key2 => 'value' );
        $i->swap_keys( 'key', 'key2' );
        # { key2 => 'value', key => 'value' }
        for( $i->all_keys ){
            my $v = $i->get_key_value( $_ );
            print "$_ => $v ";
        }

BETA
    Code is still beta, interface is not yet deemed "stable", method names
    could change depending on things at this point.

    This release is primarily a RFC. If somebody finds me something nicer,
    which does what I want without having to insert the hoop jumps I have
    here everywhere, then this might vanish altogther.

METHODS
  has_key( $key )
    returns true if the datastructure currently has $key set.

    Semantically equivalent to:

        exists $hash{ $key }

  need_keys ( $key, ... , $key )
    Clucks + undef if all keys are not available 1 if otherwise.

  all_keys()
    returns a list of all keys in the datastructure

    Semantically equivalent to:

        keys %hash;

    except of course, keys are in a controlled order.

  get_key_value( $key )
    return the value of the key named $key

    Semanticaly equivalent to:

        my $value = $hash{ $key };

  set_key_value( $key , $value )
    set the value of the key $key in the structure.

    Equivalent to:

        $hash{ $key } = $value

    Except of course, insertion order is retained.

  length()
    return how many keys there are

  last()
    return the number of the last key.

  add_key( $key , $default = undef )
    ensure that $key is in the datastructure. if it is not there, it is set
    to undef,

    Semantically identical to:

        $hash{ $key } //=  ( $default // undef )

  copy_value( $key1, $key2 )
    copy the value of key1 to under the value of key2

    Semantically identical to

        $hash{ $key2 } = $hash{ $key1 }

    Order of keys is retained.

  swap_values( $key1 , $key2  )
    Swaps the values behind the named keys.

    Akin to:

        my $v = $hash{ $key1 };
        $hash{ $key1 } = $hash{ $key2 };
        $hash{ $key2 } = $v;

  swap_keys( $key1 , $key2 )
    This works on the *order* of the keys, not the values, Key<->value pairs
    should retain bonding, just the internal order will be changed.

  move_up( $key , $maxmove = 1 )
    attempt to shift $key one position up ( closer to 0 )

  move_down( $key , $maxmove  = 1)
    attempt to shift the $key one position down ( closer to 999... )

  _move_down_one( $index )
    PRIVATE: INTERNAL USE ONLY.

    Internal method called for shifting an entry down one place in the
    array. If used wrongly will leave 'HOLEARRAY(0XF00AD)' style droppings
    in your data.

  _move_up_one( $index )
    PRIVATE: INTERNAL USE ONLY.

    Internal method called for shifting an entry up one place in the array.
    If used wrongly will leave 'HOLEARRAY(0XF00AD)' style droppings in your
    data.

  IxHash()
    Returns a hashref to an Actually Tied hash. Note this is independant of
    our datastructure, as we don't use a tied hash internally, only the
    IxHash container.

AUTHOR
      Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2009 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.

