core/vectors/vectors-docs.factor

   1 USING: help.markup help.syntax kernel sequences ;
   2 IN: vectors
   3
   4 ARTICLE: "vectors" "Vectors"
   5 "The " { $vocab-link "vectors" } " vocabulary implements resizable mutable sequence which support the " { $link "sequence-protocol" } "."
   6 $nl
   7 "The " { $vocab-link "vectors" } " vocabulary only includes words for creating new vectors. To access and modify vector elements, use " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary."
   8 $nl
   9 "Vector literal syntax is documented in " { $link "syntax-vectors" } "."
  10 $nl
  11 "Vectors are intended to be used with " { $link "sequences-destructive" } ". Code that does not modify sequences in-place can use fixed-size arrays without loss of generality; see " { $link "arrays" } "."
  12 $nl
  13 "Vectors form a class of objects:"
  14 { $subsections
  15     vector
  16     vector?
  17 }
  18 "Creating new vectors:"
  19 { $subsections
  20     >vector
  21     <vector>
  22 }
  23 "Creating a vector from a single element:"
  24 { $subsections 1vector }
  25 "If you don't care about initial capacity, an elegant way to create a new vector is to write:"
  26 { $code "V{ } clone" } ;
  27
  28 ABOUT: "vectors"
  29
  30 HELP: vector
  31 { $class-description "The class of resizable vectors. See " { $link "syntax-vectors" } " for syntax and " { $link "vectors" } " for general information." } ;
  32
  33 HELP: <vector>
  34 { $values { "n" "a positive integer specifying initial capacity" } { "vector" vector } }
  35 { $description "Creates a new vector that can hold " { $snippet "n" } " elements before resizing." } ;
  36
  37 HELP: >vector
  38 { $values { "seq" sequence } { "vector" vector } }
  39 { $description "Outputs a freshly-allocated vector with the same elements as a given sequence." } ;
  40
  41 HELP: 1vector
  42 { $values { "x" object } { "vector" vector } }
  43 { $description "Create a new vector with one element." } ;
  44
  45 HELP: ?push
  46 { $values { "elt" object } { "seq/f" { $maybe "a resizable mutable sequence" } } { "seq" "a resizable mutable sequence" } }
  47 { $description "If the given sequence is " { $link f } ", creates and outputs a new one-element vector holding " { $snippet "elt" } ". Otherwise, pushes " { $snippet "elt" } " onto the given sequence." }
  48 { $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
  49 { $side-effects "seq" } ;