core/arrays/arrays-docs.factor

   1 USING: help.markup help.syntax kernel sequences
   2 sequences.private ;
   3 IN: arrays
   4
   5 ARTICLE: "arrays-unsafe" "Unsafe array operations"
   6 "These two words are used internally by the Factor implementation. User code should never need to call them; instead use " { $link nth } " and " { $link set-nth } "."
   7 { $subsections
   8     array-nth
   9     set-array-nth
  10 } ;
  11
  12 ARTICLE: "arrays" "Arrays"
  13 "The " { $vocab-link "arrays" } " vocabulary implements fixed-size mutable sequences which support the " { $link "sequence-protocol" } "."
  14 $nl
  15 "The " { $vocab-link "arrays" } " vocabulary only includes words for creating new arrays. To access and modify array elements, use " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary."
  16 $nl
  17 "Array literal syntax is documented in " { $link "syntax-arrays" } ". Resizable arrays also exist and are known as " { $link "vectors" } "."
  18 $nl
  19 "Arrays form a class of objects:"
  20 { $subsections
  21     array
  22     array?
  23 }
  24 "Creating new arrays:"
  25 { $subsections
  26     >array
  27     <array>
  28 }
  29 "Creating an array from several elements on the stack:"
  30 { $subsections
  31     1array
  32     2array
  33     3array
  34     4array
  35 }
  36 "Resizing arrays:"
  37 { $subsections resize-array }
  38 "The class of two-element arrays:"
  39 { $subsections pair }
  40 "Arrays can be accessed without bounds checks in a pointer unsafe way."
  41 { $subsections "arrays-unsafe" } ;
  42
  43 ABOUT: "arrays"
  44
  45 HELP: array
  46 { $class-description "The class of fixed-length arrays. See " { $link "syntax-arrays" } " for syntax and " { $link "arrays" } " for general information." } ;
  47
  48 HELP: <array>
  49 { $values { "n" "a non-negative integer" } { "elt" "an initial element" } { "array" "a new array" } }
  50 { $description "Creates a new array with the given length and all elements initially set to " { $snippet "elt" } "." } ;
  51
  52 HELP: >array
  53 { $values { "seq" sequence } { "array" array } }
  54 { $description "Outputs a freshly-allocated array with the same elements as a given sequence." } ;
  55
  56 HELP: 1array
  57 { $values { "x" object } { "array" array } }
  58 { $description "Create a new array with one element." } ;
  59
  60 { 1array 2array 3array 4array } related-words
  61
  62 HELP: 2array
  63 { $values { "x" object } { "y" object } { "array" array } }
  64 { $description "Create a new array with two elements, with " { $snippet "x" } " appearing first." } ;
  65
  66 HELP: 3array
  67 { $values { "x" object } { "y" object } { "z" object } { "array" array } }
  68 { $description "Create a new array with three elements, with " { $snippet "x" } " appearing first." } ;
  69
  70 HELP: 4array
  71 { $values { "w" object } { "x" object } { "y" object } { "z" object } { "array" array } }
  72 { $description "Create a new array with four elements, with " { $snippet "w" } " appearing first." } ;
  73
  74 HELP: resize-array
  75 { $values { "n" "a non-negative integer" } { "array" array } { "new-array" array } }
  76 { $description "Resizes the array to have a length of " { $snippet "n" } " elements. When making the array shorter, this word may either create a new array or modify the existing array in place. When making the array longer, this word always allocates a new array, filling remaining space with " { $link f } "." }
  77 { $side-effects "array" } ;
  78
  79 HELP: pair
  80 { $class-description "The class of two-element arrays, known as pairs." } ;