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" } " 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 "This word behaves as follows, depending on the relation between " { $snippet "n" } " and the length of the sequence:"
  32 { $list
  33   { "If " { $snippet "n" } " is less than the length of the sequence, does nothing." }
  34   { "If " { $snippet "n" } " exceeds the capacity of the underlying storage, the underlying storage is grown." }
  35   { "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." }
  36 }
  37 "In the case that new elements are added to the sequence (last two cases), the new elements are undefined." }
  38 { $notes "This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")."
  39 } ;