Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sysread/skewheap-pp

A fast and flexible heap structure written in pure perl
https://github.com/sysread/skewheap-pp

data-structures heap perl perl5 prioity-queue queue skew skewheap

Last synced: about 1 month ago
JSON representation

A fast and flexible heap structure written in pure perl

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



SkewHeap::PP - a fast and flexible heap structure



=head1 VERSION



version 0.02



=head1 SYNOPSIS



  use SkewHeap::PP;



  my $s = skew{ $_[0] <=> $_[1] };



  # Add items one at a time

  for (@items) {

    skew_put($s, $_);

  }



  # Or as a batch

  skew_put($s, @items);



  # Take individual items

  my @taken;

  until (skew_is_empty($s)) {

    say "Taking: " . skew_peek($s);



    push @taken, skew_take($s);



    say "Left in queue: " . skew_count($s);

  }



  # Or take a batch

  my @take_ten = skew_take($s, 10);



  # Destructively merge two heaps

  skew_merge($s, $another_skew_heap);



  # Non-destructively merge heaps

  my $new_heap = skew_merge($a, $b, $c);



=head1 DESCRIPTION



A skew heap is a memory efficient, self-adjusting heap with an amortized

performance of O(log n) or better. C is implemented in pure perl,

yet performs comparably to L.



The key feature of a skew heap is the ability to quickly and efficiently merge

two heaps together.



=head2 skew



Creates a new skew heap. Requires a single argument, a code block that knows how

to prioritize the values to be stored in the heap.



  my $heap = skew{ $_[0] <=> $_[1] };



=head2 skew_count



Returns the number of elements in the heap.



=head2 skew_is_empty



Returns true if the heap is empty.



=head2 skew_peek



Returns the top element in the heap without removing it from the heap.



=head2 skew_take



Removes and returns the top element from the heap.



  my $item = skew_take($heap);



Optionally, multiple elements may be returned from the heap by passing the

desired number of elements, in which case a list is returned, rather than a

single, scalar element. If there are fewer elements available than requested,

as many as a immediately available are returned.



  # Get 10 elements

  my @items = skew_take($heap, 10);



=head2 skew_put



Adds one or more items to the heap.



  skew_put($s, 42);

  skew_put($s, 42, 6, 8);



=head2 skew_merge



Merges any number of heaps into the first argument I. After

merging, the first heap passed in will contain all of the items in the heaps

passed in subsequent arguments. After merging, the subsequent heaps will be

empty. The comparison function used for ordering is that of the first heap

passed in. The return value is the first heap into which the other heaps were

merged.



  skew_merge($x, $y, $z); # $x contains all elements of $x, $y, and $z;

                          # $y and $z are now empty.



=head2 skew_merge_safe



Non-destructively merges any number of heaps into a new heap whose comparison

function will be that of the first heap in the list to merge. Returns a new

heap containing all of the items in each of the other heaps. The other heaps'

contents will remain intact.



=head2 skew_explain



Prints out a representation of the internal tree structure for debugging.



=head1 OBJECT INTERFACE



An object interface is provided that maps directly to the similarly named

C routines.



=over



=item new - SEE L



=item count - SEE L



=item is_empty - SEE L



=item peek - SEE L



=item take - SEE L



=item put - SEE L



=item merge - SEE L



=item merge_safe - SEE L



=item explain = SEE L



=back



=head1 SEE ALSO



=over



=item L



Written in XS and roughly 2x faster.



=item L



=back



=head1 AUTHOR



Jeff Ober 



=head1 COPYRIGHT AND LICENSE



This software is copyright (c) 2020 by Jeff Ober.



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.



=cut