basis/specialized-arrays/specialized-arrays-docs.factor

   1 USING: help.markup help.syntax byte-arrays ;
   2 IN: specialized-arrays
   3
   4 ARTICLE: "specialized-arrays" "Specialized arrays"
   5 "The " { $vocab-link "specialized-arrays" } " vocabulary implements fixed-length sequence types for storing machine values in a space-efficient manner without boxing."
   6 $nl
   7 "For each primitive C type " { $snippet "T" } ", a set of words are defined in the vocabulary named " { $snippet "specialized-arrays.T" } ":"
   8 { $table
   9     { { $snippet "T-array" } { "The class of arrays with elements of type " { $snippet "T" } } }
  10     { { $snippet "<T-array>" } { "Constructor for arrays with elements of type " { $snippet "T" } "; stack effect " { $snippet "( len -- array )" } } }
  11     { { $snippet "<direct-T-array>" } { "Constructor for arrays with elements of type " { $snippet "T" } "; stack effect " { $snippet "( alien len -- array )" } } }
  12     { { $snippet "byte-array>T-array" } { "Converts a byte array into a specialized array by interpreting the bytes in as machine-specific values. Code which uses this word is unportable" } }
  13     { { $snippet ">T-array" } { "Converts a sequence into a specialized array of type " { $snippet "T" } "; stack effect " { $snippet "( seq -- array )" } } }
  14     { { $snippet "T-array{" } { "Literal syntax, consists of a series of values terminated by " { $snippet "}" } } }
  15 }
  16 "Each specialized array has a " { $slot "underlying" } " slot holding a " { $link byte-array } " with the raw data. This data can be passed to C functions."
  17 $nl
  18 "The primitive C types for which specialized arrays exist:"
  19 { $list
  20     { $snippet "char" }
  21     { $snippet "uchar" }
  22     { $snippet "short" }
  23     { $snippet "ushort" }
  24     { $snippet "int" }
  25     { $snippet "uint" }
  26     { $snippet "long" }
  27     { $snippet "ulong" }
  28     { $snippet "longlong" }
  29     { $snippet "ulonglong" }
  30     { $snippet "float" }
  31     { $snippet "double" }
  32     { $snippet "complex-float" }
  33     { $snippet "complex-double" }
  34     { $snippet "void*" }
  35     { $snippet "bool" }
  36 }
  37 "Note that " { $vocab-link "specialized-arrays.bool" } " behaves like a C " { $snippet "bool[]" } " array, and each element takes up 8 bits of space. For a more space-efficient boolean array, see " { $link "bit-arrays" } "."
  38 $nl
  39 "Specialized arrays are generated with a functor in the " { $vocab-link "specialized-arrays.functor" } " vocabulary."
  40 $nl
  41 "The " { $vocab-link "specialized-vectors" } " vocabulary provides resizable versions of the above." ;
  42
  43 ABOUT: "specialized-arrays"