/core/arrays/arrays-docs.factor

 1USING: help.markup help.syntax
 2kernel kernel.private prettyprint sequences.private sequences ;
 3IN: arrays
 4
 5ARTICLE: "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
12ARTICLE: "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
43ABOUT: "arrays"
44
45HELP: array
46{ $description "The class of fixed-length arrays. See " { $link "syntax-arrays" } " for syntax and " { $link "arrays" } " for general information." } ;
47
48HELP: <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
52HELP: >array
53{ $values { "seq" "a sequence" } { "array" array } }
54{ $description "Outputs a freshly-allocated array with the same elements as a given sequence." } ;
55
56HELP: 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
62HELP: 2array
63{ $values { "x" object } { "y" object } { "array" array } }
64{ $description "Create a new array with two elements, with " { $snippet "x" } " appearing first." } ;
65
66HELP: 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
70HELP: 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
74HELP: 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
79HELP: pair
80{ $class-description "The class of two-element arrays, known as pairs." } ;