Name
     Binary::Heap::Array - Extensible array each of whose component arrays is an
     integral power of two wide.

Synopsis
      my $a = Binary::Heap::Array::new();

      $a->push(1)->push(2);
      ok $a->size   == 2;
      ok $a->at( 0) == 1;
      ok $a->at( 1) == 2;
      ok $a->at(-1) == 2;
      ok $a->at(-2) == 1;

      $a->at(0) = 2;
      ok $a->at(-2) == 2;
      ok $a->pop    == 2;
      ok $a->size   == 1;

Methods
  new()()
    Create a new binary heap Array

  at :lvalue($array, $index)
    Address the element at a specified index so that it can get set or got

         Parameter  Description
      1  $array     Array
      2  $index     index of element

  pop($array)
    Pop the topmost element from the leading full array and spread the
    remainder of its contents as sub arrays of the correct size for each
    preceding empty slot

         Parameter  Description
      1  $array     Array from which an element is to be popped

  push($array, $element)
    Push a new element on to the top of the array by accumulating the
    leading full sub arrays in the first empty slot

         Parameter  Description
      1  $array     Array
      2  $element   element to push

  size($array, $element)
    Find the number of elements in the binary heap array

         Parameter  Description
      1  $array     Array
      2  $element

Index
    Alphabetic list of methods:

    "at :lvalue($array, $index)" "new()()" "pop($array)" "push($array,
    $element)" "size($array, $element)"

Installation
    This module is written in 100% Pure Perl in a single file and is thus
    easy to read, modify and install.

    Standard Module::Build process for building and installing modules:

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

See also
    The arrays used to construct the binary heap array are all an integral
    power of two wide and thus make good use of the memory allocated by
    Data::Layout::BuddySystem or similar.

Author
    philiprbrenan@gmail.com

    http://www.appaapps.com

Copyright
    Copyright (c) 2017 Philip R Brenan.

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.

