! Binary Min Heap
! Copyright 2007 Ryan Murphy
! See http://factorcode.org/license.txt for BSD license.

USING: help heap sequences ;

ARTICLE: { "heap" "heap" } "Binary Min Heap"
"A vector-based implementation of a binary min heap.  Elements are simply stored in a vector, so use " { $link first } " to access the root of the heap."
{ $subsection <heap> }
{ $subsection add }
{ $subsection add-many }
{ $subsection bump }
{ $subsection gbump }
{ $subsection print-heap }
;

HELP: <heap>
"Creates a new heap with nothing on it." ;

HELP: add
"Adds 1 element to the heap."
{ $examples
  { $code
    "USE: heap"
    "<heap> 3 over add 4 over add 5 over add"
    "print-heap"
  }
}
;

HELP: add-many
"For each element in the sequence, add it to the heap."
{ $examples
  { $code
    "USE: heap"
    "<heap> { 7 6 5 4 3 2 1 } over add-many"
    "print-heap"
  }
}
;

HELP: bump
"\"Bumps\" the root element off of the heap, rearranging the remaining elements so that the heap remains valid."
{ $examples
  { $code
    "USE: heap"
    "<heap> { 7 6 5 4 3 2 1 } over add-many"
    "dup print-heap"
    "dup bump \"(bump)\" print dup print-heap"
    "dup bump \"(bump)\" print dup print-heap"
    "dup bump \"(bump)\" print dup print-heap"
  }
}
;

HELP: gbump
"(\"Get-bump\") Does a " { $link bump } ", but leaves the bumped element on the stack instead of discarding it."
{ $examples
  { $code
    "USE: heap"
    "<heap> { 7 6 5 4 3 2 1 } over add-many"
    "dup gbump"
  }
}
;

HELP: print-heap
"Prints the heap in tree form."
{ $examples
  { $code
    "USE: heap"
    "<heap> { 7 6 5 4 3 2 1 } over add-many"
    "print-heap"
  }
}
;