core/vectors/vectors-docs.factor

   1 USING: arrays byte-arrays help.markup
   2 help.syntax kernel sbufs strings quotations sequences.private
   3 vectors.private combinators ;
   4 IN: vectors
   5
   6 ARTICLE: "vectors" "Vectors"
   7 "A vector is a resizable mutable sequence of objects. The literal syntax is covered in " { $link "syntax-vectors" } ". Vector words are found in the " { $vocab-link "vectors" } " vocabulary."
   8 $nl
   9 "Vectors form a class:"
  10 { $subsection vector }
  11 { $subsection vector? }
  12 "Creating vectors:"
  13 { $subsection >vector }
  14 { $subsection <vector> }
  15 "Creating a vector from a single element:"
  16 { $subsection 1vector }
  17 "If you don't care about initial capacity, a more elegant way to create a new vector is to write:"
  18 { $code "V{ } clone" } ;
  19
  20 ABOUT: "vectors"
  21
  22 HELP: vector
  23 { $description "The class of resizable vectors. See " { $link "syntax-vectors" } " for syntax and " { $link "vectors" } " for general information." } ;
  24
  25 HELP: <vector>
  26 { $values { "n" "a positive integer specifying initial capacity" } { "vector" vector } }
  27 { $description "Creates a new vector that can hold " { $snippet "n" } " elements before resizing." } ;
  28
  29 HELP: >vector
  30 { $values { "seq" "a sequence" } { "vector" vector } }
  31 { $description "Outputs a freshly-allocated vector with the same elements as a given sequence." } ;
  32
  33 HELP: 1vector
  34 { $values { "x" object } { "vector" vector } }
  35 { $description "Create a new vector with one element." } ;
  36
  37 HELP: ?push
  38 { $values { "elt" object } { "seq/f" "a resizable mutable sequence, or " { $link f } } { "seq" "a resizable mutable sequence" } }
  39 { $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." }
  40 { $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
  41 { $side-effects "seq" } ;