README
1Heap::Simple version 0.13
2=========================
3
4DESCRIPTION
5
6A heap is a partially sorted structure where it's always easy to extract the
7smallest element. If the collection of elements is changing dynamically, a
8heap has less overhead than keeping the collection fully sorted.
9
10The order in which equal elements get extracted is unspecified.
11
12The main order relations supported by this module are "<" (numeric compare)
13and "lt" (string compare).
14
15The module allows you to manage data where the elements are of several
16allowed types, in particular array references, hash references, objects
17or just the keys themselves.
18
19The internals of the module do nothing with the elements inserted except
20inspecting the key. This means that if you for example store a blessed
21object, that's what you will get back on extract. It's also ok to keep
22references to the elements around and make changes to them while they are
23in the heap as long as you don't change the key.
24
25SYNOPSIS
26
27 use Heap::Simple;
28
29 # Create a heap
30 my $heap = Heap::Simple->new;
31 my $heap = Heap::Simple->new(%options);
32
33 # Put data in the heap
34 $heap->insert($element);
35 # Put data in a "Object" or "Any" heap with a given key
36 $heap->key_insert($key, $element);
37
38 # Extract the top value
39 $element = $heap->extract_top; # croaks on an empty heap
40 $element = $heap->extract_first; # returns undef on an empty heap
41
42 # Get the top value but leave it in the heap
43 $element = $heap->top; # croaks on an empty heap
44 $element = $heap->first; # returns undef on an empty heap
45
46 # Find the top key in the heap
47 $top_key = $heap->top_key; # return infinity on an empty heap
48 # croaks if there's no infinity
49 $top_key = $heap->first_key; # returns undef on an empty heap
50
51 # Extract all data whose key is not above a given value
52 @elements = $heap->extract_upto($max_key);
53
54 # Find the number of elements
55 $count = $heap->count;
56
57 # Empty the heap
58 $heap->clear;
59
60 # Get all keys (not sorted)
61 @keys = $heap->keys;
62 # Get all values (not sorted)
63 @values = $heap->values;
64
65 # Find the key corresponding to a value
66 $key = $heap->key($value);
67
68 # Get/Set user_data
69 $user_data = $heap->user_data;
70 $old_data = $heap->user_data($new_data);
71
72 # Get/Set infinity
73 $infinity = $heap->infinity;
74 $old_infinity = $heap->infinity($new_data);
75
76 # Get the position of a key in an element
77 $key_index = $heap->key_index;
78 $key_name = $heap->key_name;
79 $key_method = $heap->key_method;
80 $key_function = $heap->key_function;
81
82 # Return the value of several things that were set in new:
83 $wrapped = $heap->wrapped;
84 $max_count = $heap->max_count;
85 $can_die = $heap->can_die;
86 $dirty = $heap->dirty;
87 $order = $heap->order;
88 @elements = $heap->elements;
89 $elements = $heap->elements;
90
91 # Move all elements from $heap2 to $heap1
92 $heap1->absorb($heap2); # As if doing a repeated $heap1->insert
93 $heap1->key_absorb($heap2); # As if doing a repeated $heap1->key_insert
94
95 # Which class does the actual work ?
96 $implementation = Heap::Simple->implementation;
97
98INSTALLATION
99
100To install this module type the following:
101
102 perl Makefile.PL
103 make
104 make test
105 make install
106
107To install this module into a specific directory, do:
108 perl Makefile.PL PREFIX=/name/of/the/directory
109 ...the rest is the same...
110
111Please also read the perlmodinstall man page, if available.
112
113DEPENDENCIES
114
115This module doesn't do anything on itself. It needs a plugin actually
116implementing the interfaced described above. You can use:
117
118 Heap::Simple::Perl A pure perl implementation, quite fast actually
119 Heap::Simple::XS An even faster XS implementation, but it needs your
120 setup to be able to compile perl modules or you must
121 be able to get a binary package for your system
122
123AUTHOR
124
125Ton Hospel, <Heap-Simple@ton.iguana.be>
126
127COPYRIGHT AND LICENCE
128
129Copyright (C) 2004 Ton Hospel
130
131This library is free software; you can redistribute it and/or modify
132it under the same terms as Perl itself.
133