core/growable/growable-docs.factor

   1 USING: help.markup help.syntax kernel sequences
   2 sequences.private ;
   3 IN: growable
   4
   5 ARTICLE: "growable" "Resizable sequence implementation"
   6 "Resizable sequences are implementing by having a wrapper object hold a reference to an underlying sequence, together with a fill pointer indicating how many elements of the underlying sequence are occupied. When the fill pointer exceeds the underlying sequence capacity, the underlying sequence grows."
   7 $nl
   8 "There is a resizable sequence mixin:"
   9 { $subsection growable }
  10 "This mixin implements the sequence protocol by assuming the object has two specific slots:"
  11 { $list
  12     { { $snippet "length" } " - the fill pointer (number of occupied elements in the underlying storage)" }
  13     { { $snippet "underlying" } " - the underlying storage" }
  14 }
  15 "The underlying sequence must implement a generic word:"
  16 { $subsection resize }
  17 { $link "vectors" } ", " { $link "byte-vectors" } " and " { $link "sbufs" } " are implemented using the resizable sequence facility." ;
  18
  19 ABOUT: "growable"
  20
  21 HELP: capacity
  22 { $values { "seq" "a vector or string buffer" } { "n" "the capacity of the sequence" } }
  23 { $description "Outputs the number of elements the sequence can hold without growing." } ;
  24
  25 HELP: new-size
  26 { $values { "old" "a positive integer" } { "new" "a positive integer" } }
  27 { $description "Computes the new size of a resizable sequence." } ;
  28
  29 HELP: ensure
  30 { $values { "n" "a positive integer" } { "seq" growable } }
  31 { $description "If " { $snippet "n" } " is less than the length of the sequence, does nothing. Otherwise, if " { $snippet "n" } " also exceeds the capacity of the underlying storage, the underlying storage is grown, and the fill pointer is reset. Finally, if " { $snippet "n" } " is greater than or equal to the length but less than the capacity of the underlying storage, the fill pointer is moved and nothing else is done."
  32 $nl
  33 "This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")."
  34 } ;