basis/tuple-arrays/tuple-arrays-docs.factor

   1 IN: tuple-arrays
   2 USING: help.markup help.syntax sequences ;
   3
   4 HELP: TUPLE-ARRAY:
   5 { $syntax "TUPLE-ARRAY: class" }
   6 { $values { "class" "a final tuple class" } }
   7 { $description "Generates a new data type in the current vocabulary named " { $snippet { $emphasis "class" } "-array" } " for holding instances of " { $snippet "class" } ", which must be a tuple class word. Together with the class itself, this also generates words named " { $snippet "<" { $emphasis "class" } "-array>" } " and " { $snippet ">" { $emphasis "class" } "-array" } ", for creating new instances of this tuple array type." } ;
   8
   9 ARTICLE: "tuple-arrays" "Tuple arrays"
  10 "The " { $vocab-link "tuple-arrays" } " vocabulary implements space-efficient unboxed tuple arrays. Whereas an ordinary array of tuples would consist of references to heap-allocated objects, a tuple array stores its elements as values."
  11 $nl
  12 "Calling " { $link nth } " copies an element into a new tuple, and calling " { $link set-nth } " copies an existing tuple's slots into an array."
  13 $nl
  14 "Since value semantics are incompatible with inheritance, the base type of a tuple array must be declared " { $link POSTPONE: final } ". A best practice that is not enforced is to have all slots in the tuple declared " { $link read-only } "."
  15 $nl
  16 "Tuple arrays do not get updated if tuples are redefined to add or remove slots, so caution should be exercised when doing interactive development on code that uses tuple arrays."
  17 $nl
  18 { $subsections POSTPONE: TUPLE-ARRAY: }
  19 "An example:"
  20 { $example
  21   "USE: tuple-arrays"
  22   "IN: scratchpad"
  23   "TUPLE: point x y ; final"
  24   "TUPLE-ARRAY: point"
  25   "{ T{ point f 1 2 } T{ point f 1 3 } T{ point f 2 3 } } >point-array first short."
  26   "T{ point f 1 2 }"
  27 } ;
  28
  29 ABOUT: "tuple-arrays"