core/byte-arrays/byte-arrays-docs.factor

   1 USING: kernel help.markup help.syntax ;
   2 IN: byte-arrays
   3
   4 ARTICLE: "byte-arrays" "Byte arrays"
   5 "Byte arrays are fixed-size mutable sequences (" { $link "sequence-protocol" } ") whose elements are integers in the range 0-255, inclusive. Each element only uses one byte of storage, hence the name. The literal syntax is covered in " { $link "syntax-byte-arrays" } "."
   6 $nl
   7 "Byte array words are in the " { $vocab-link "byte-arrays" } " vocabulary."
   8 $nl
   9 "Byte arrays play a special role in the C library interface; they can be used to pass binary data back and forth between Factor and C. See " { $link "c-byte-arrays" } "."
  10 $nl
  11 "Byte arrays form a class of objects."
  12 { $subsection byte-array }
  13 { $subsection byte-array? }
  14 "There are several ways to construct byte arrays."
  15 { $subsection >byte-array }
  16 { $subsection <byte-array> }
  17 { $subsection 1byte-array }
  18 { $subsection 2byte-array }
  19 { $subsection 3byte-array }
  20 { $subsection 4byte-array }
  21 "Resizing byte-arrays:"
  22 { $subsection resize-byte-array } ;
  23
  24 ABOUT: "byte-arrays"
  25
  26 HELP: byte-array
  27 { $description "The class of byte arrays. See " { $link "syntax-byte-arrays" } " for syntax and " { $link "byte-arrays" } " for general information." } ;
  28
  29 HELP: <byte-array> ( n -- byte-array )
  30 { $values { "n" "a non-negative integer" } { "byte-array" "a new byte array" } }
  31 { $description "Creates a new byte array holding " { $snippet "n" } " bytes." } ;
  32
  33 HELP: >byte-array
  34 { $values { "seq" "a sequence" } { "byte-array" byte-array } }
  35 { $description
  36   "Outputs a freshly-allocated byte array whose elements have the same signed byte values as a given sequence." }
  37 { $errors "Throws an error if the sequence contains elements other than integers." } ;
  38
  39 HELP: 1byte-array
  40 { $values
  41      { "x" object }
  42      { "byte-array" byte-array } }
  43 { $description "Creates a new byte-array with one element." } ;
  44
  45 HELP: 2byte-array
  46 { $values
  47      { "x" object } { "y" object }
  48      { "byte-array" byte-array } }
  49 { $description "Creates a new byte-array with two elements." } ;
  50
  51 HELP: 3byte-array
  52 { $values
  53      { "x" object } { "y" object } { "z" object }
  54      { "byte-array" byte-array } }
  55 { $description "Creates a new byte-array with three element." } ;
  56
  57 HELP: 4byte-array
  58 { $values
  59      { "w" object } { "x" object } { "y" object } { "z" object }
  60      { "byte-array" byte-array } }
  61 { $description "Creates a new byte-array with four elements." } ;
  62
  63 { 1byte-array 2byte-array 3byte-array 4byte-array } related-words
  64
  65 HELP: resize-byte-array ( n byte-array -- newbyte-array )
  66 { $values { "n" "a non-negative integer" } { "byte-array" byte-array }
  67         { "newbyte-array" byte-array } }
  68 { $description "Creates a new byte-array of n elements.  The contents of the existing byte-array are copied into the new byte-array; if the new byte-array is shorter, only an initial segment is copied, and if the new byte-array is longer the remaining space is filled in with 0." } ;