NAME
    List::SkipList - Perl implementation of skip lists

REQUIREMENTS
    Perl 5.6.1 is required.

    The following non-standard modules are required:

      enum

    Carp::Assert is no longer required.  However, the assertions can
    be uncommented for debugging.

Installation
    Installation can be done using the traditional Makefile.PL or the
    newer Build.PL methods.

    Using Makefile.PL:

      perl Makefile.PL
      make
      make test
      make install

    (On Windows platforms you should use nmake instead.)

    Using Build.PL (if you have Module::Build installed):

      perl Build.PL
      perl Build
      perl Build test
      perl Build install    

SYNOPSIS
      my $list = new List::SkipList();

      $list->insert( 'key1', 'value' );
      $list->insert( 'key2', 'another value' );

      $value = $list->find('key2');

      $list->delete('key1');

DESCRIPTION
    This is an implementation of skip lists in Perl.  What are "skip
    lists"?

      Skip lists are a probabilistic data structure that seem likely
      to supplant balanced trees as the implementation method of
      choice for many applications. Skip list algorithms have the same
      asymptotic expected time bounds as balanced trees and are
      simpler, faster and use less space.(*)

    This implementation may not be faster or use less space, but in
    superficial testing, it does appear to be a reasonably faster
    substitute for some pure-Perl tree modules.  (However, see the
    included Benchmark.txt file for comparisons with similar Perl
    modules, as well as the SEE ALSO section below.)

    Skip lists are similar to linked lists, except that they have
    random links at various levels that allow searches to skip over
    sections of the list, like so:

      4 +---------------------------> +----------------------> +
        |                             |                        |
      3 +------------> +------------> +-------> +-------> +--> +
        |              |              |         |         |    |
      2 +-------> +--> +-------> +--> +--> +--> +-------> +--> +
        |         |    |         |    |    |    |         |    |
      1 +--> +--> +--> +--> +--> +--> +--> +--> +--> +--> +--> +
             A    B    C    D    E    F    G    H    I    J   NIL

    A search would start at the top level: if the link to the right
    exceeds the target key, then it descends a level.

    More information is available in the module documentation.

    (*) Bill Pugh, inventor of skip lists.  Quoted from WikiPedia
        <http://en.wikipedia.org/wiki/Skip_list>

REVISION HISTORY
    Changes since v0.65:

    0.71 Sat Jun 12 2004
	- updated POD
	- redesigned internals of first_key, next_key and last_key
	* delete now resets last_key
	* the parameters for last_key are changed (this interface was
          meant for internal use only, however)
	- added index_by_key, key_by_index and value_by_index methods
	- updated documentation on p and k parameters
	- added support for k parameter
	- redid probability distribution calculations
	- fixed bug in benchmarks (was "existing" bogus keys)
	- added support for duplicate values
	- added find_duplicates method
	- corrected typos in POD for new method

    0.71_01 Wed Jun  9 2004
	- fixed bug in benchmarks (was deleting bogus keys)
	- added some warnings
	- improved delete method
	- added truncate method
	- _search_with_finger now builds correct update vector
	- append calls _adjust_level_threshold
	- minor optimizations of node class
	* renamed internal key {LASTNODE} to {LIST_END} so as not to
	  be confused with last_key method
	- _first_node is not autoloading since it's now used by first_key
	- updated POD to reflect issue with undefined values
	- improved copy method (undef values handled)
	- copy method can accept an argument: copy from key
	* copy method no longer resets first_key
	* _first_node no longer returns a finger (it was never used)
	- updated documentation on values for max_level and p
	- corrected typos in documentation
	- added tests for deleted greatest bug
	- fixed bug with greatest method when deleting last node
	- added _greatest_node method to find the last node as needed
	- other minor code changes

    0.70_01 Sun Jun  6 2004 
	- tests rewritten (work in progress)
	- fixed bug with next_key checking node when key was deleted
	- uses Test::More for tests
	- fixed "Too late to run INIT block" error with Test::More
	  use_ok, $NULL is now set in import() method
	- fixed bug where level sometimes exceeded user-set max level
	- P and max_level can now be set dynamically
	- added tests for max_level and p
	- checks for error when setting max_level or P
	- fixed bug with definition of List::SkipList::Null
	- $NULL is now an 'our' variable and accessible from outside
	- level method was changed to autoload, since it was redundant
	- minor optimization of _search_with_finger and _search
	* header method in Node is read-only - it returns a pointer
	  which can be used to change values anyway
	* key method in Node is read-only - it should not be
          changed once it is inside a list
	- added _adjust_level_threshold method from code that was in
	  _new_node_level to adjust SIZE_THRESHOLD/SIZE_LEVEL
	- _adjust_level_threshold is called upon inserts and deletes
	- SIZE_LEVEL does not decrease under MIN_LEVEL
	* removed null() method - it was never used
	* max_level cannot be greater than 32 (cleaner code)
	- increased coverage of "heavy" test script
	- minor updates to all test scripts

    A detailed revision history is in the Changes file included with
    this distribution.

KNOWN ISSUES
  The following issues are known:

  * If you already have a version before 0.70 installed, it may be a
    good idea to uninstall it before installing the latest version,
    since there are some changes to autoloading methods.

  * Skip lists are non-deterministic.  Because of this, bugs in programs
    that use this module may be subtle and difficult to reproduce without
    many repeated attempts.

  See http://rt.cpan.org/NoAuth/Bugs.html?Dist=List-SkipList for any
  additional issues.

AUTHOR
    Robert Rothenberg <rrwo at cpan.org>

LICENSE
    Copyright (c) 2003-2004 Robert Rothenberg. All rights reserved. This
    program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    See the article "A Skip List Cookbook" (William Pugh, 1989), or
    similar ones by the author at http://www.cs.umd.edu/~pugh/ which
    discuss skip lists.

    Because of the way Perl manages memory, you may be better off
    using a hash with sorted keys (such as Tie::Hash::Sorted) rather
    than maintaining a sorted dictionary using this or similar
    modules.
