/core/arrays/arrays-docs.factor

http://github.com/abeaumont/factor · Factor · 80 lines · 67 code · 13 blank · 0 comment · 0 complexity · 9b12490125c89d4bd17a811039eca115 MD5 · raw file

  1. USING: help.markup help.syntax
  2. kernel kernel.private prettyprint sequences.private sequences ;
  3. IN: arrays
  4. ARTICLE: "arrays-unsafe" "Unsafe array operations"
  5. "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 } "."
  6. { $subsections
  7. array-nth
  8. set-array-nth
  9. } ;
  10. ARTICLE: "arrays" "Arrays"
  11. "The " { $vocab-link "arrays" } " vocabulary implements fixed-size mutable sequences which support the " { $link "sequence-protocol" } "."
  12. $nl
  13. "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."
  14. $nl
  15. "Array literal syntax is documented in " { $link "syntax-arrays" } ". Resizable arrays also exist and are known as " { $link "vectors" } "."
  16. $nl
  17. "Arrays form a class of objects:"
  18. { $subsections
  19. array
  20. array?
  21. }
  22. "Creating new arrays:"
  23. { $subsections
  24. >array
  25. <array>
  26. }
  27. "Creating an array from several elements on the stack:"
  28. { $subsections
  29. 1array
  30. 2array
  31. 3array
  32. 4array
  33. }
  34. "Resizing arrays:"
  35. { $subsections resize-array }
  36. "The class of two-element arrays:"
  37. { $subsections pair }
  38. "Arrays can be accessed without bounds checks in a pointer unsafe way."
  39. { $subsections "arrays-unsafe" } ;
  40. ABOUT: "arrays"
  41. HELP: array
  42. { $description "The class of fixed-length arrays. See " { $link "syntax-arrays" } " for syntax and " { $link "arrays" } " for general information." } ;
  43. HELP: <array>
  44. { $values { "n" "a non-negative integer" } { "elt" "an initial element" } { "array" "a new array" } }
  45. { $description "Creates a new array with the given length and all elements initially set to " { $snippet "elt" } "." } ;
  46. HELP: >array
  47. { $values { "seq" "a sequence" } { "array" array } }
  48. { $description "Outputs a freshly-allocated array with the same elements as a given sequence." } ;
  49. HELP: 1array
  50. { $values { "x" object } { "array" array } }
  51. { $description "Create a new array with one element." } ;
  52. { 1array 2array 3array 4array } related-words
  53. HELP: 2array
  54. { $values { "x" object } { "y" object } { "array" array } }
  55. { $description "Create a new array with two elements, with " { $snippet "x" } " appearing first." } ;
  56. HELP: 3array
  57. { $values { "x" object } { "y" object } { "z" object } { "array" array } }
  58. { $description "Create a new array with three elements, with " { $snippet "x" } " appearing first." } ;
  59. HELP: 4array
  60. { $values { "w" object } { "x" object } { "y" object } { "z" object } { "array" array } }
  61. { $description "Create a new array with four elements, with " { $snippet "w" } " appearing first." } ;
  62. HELP: resize-array
  63. { $values { "n" "a non-negative integer" } { "array" array } { "new-array" array } }
  64. { $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 } "." }
  65. { $side-effects "array" } ;
  66. HELP: pair
  67. { $class-description "The class of two-element arrays, known as pairs." } ;