core/growable/growable-docs.factor

   1 USING: help.markup help.syntax sequences sequences.private ;
   2 IN: growable
   3
   4 ARTICLE: "growable" "Resizable sequence implementation"
   5 "Resizable sequences are implemented 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."
   6 $nl
   7 "There is a resizable sequence mixin:"
   8 { $subsections growable }
   9 "This mixin implements the sequence protocol by assuming the object has two specific slots:"
  10 { $list
  11     { { $snippet "length" } " - the fill pointer (number of occupied elements in the underlying storage)" }
  12     { { $snippet "underlying" } " - the underlying storage" }
  13 }
  14 "The underlying sequence must implement a generic word:"
  15 { $subsections resize }
  16 { $link "vectors" } " and " { $link "sbufs" } " are implemented using the resizable sequence facility." ;
  17
  18 ABOUT: "growable"
  19
  20 HELP: capacity
  21 { $values { "seq" "a vector or string buffer" } { "n" "the capacity of the sequence" } }
  22 { $description "Outputs the number of elements the sequence can hold without growing." } ;
  23
  24 HELP: new-size
  25 { $values { "old" "a positive integer" } { "new" "a positive integer" } }
  26 { $description "Computes the new size of a resizable sequence." } ;
  27
  28 HELP: ensure
  29 { $values { "n" "a non-negative integer" } { "seq" growable } }
  30 { $description "Ensures that " { $snippet "seq" } " has sufficient capacity to store an " { $snippet "n" } "th element." $nl "This word behaves as follows, depending on the relation between " { $snippet "n" } ", the capacity of the underlying storage, and the length of the sequence:"
  31 { $list
  32   { "If " { $snippet "n" } " is less than the length of the sequence, does nothing." }
  33   { "If " { $snippet "n" } " is greater than or equal to the capacity of the underlying storage, the underlying storage is grown." }
  34   { "If " { $snippet "n" } " is greater than or equal to the length, the length is increased." }
  35 }
  36 "In the case that new elements are added to the sequence (last two cases), the new elements are undefined." }
  37 { $notes "This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")."
  38 } ;