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