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

   1 USING: kernel help.markup help.syntax sequences ;
   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-pointers" } "."
  10 $nl
  11 "Byte arrays form a class of objects."
  12 { $subsections
  13     byte-array
  14     byte-array?
  15 }
  16 "There are several ways to construct byte arrays."
  17 { $subsections
  18     >byte-array
  19     <byte-array>
  20     1byte-array
  21     2byte-array
  22     3byte-array
  23     4byte-array
  24 }
  25 "Resizing byte arrays:"
  26 { $subsections resize-byte-array } ;
  27
  28 ABOUT: "byte-arrays"
  29
  30 HELP: byte-array
  31 { $class-description "The class of byte arrays. See " { $link "syntax-byte-arrays" } " for syntax and " { $link "byte-arrays" } " for general information." } ;
  32
  33 HELP: <byte-array>
  34 { $values { "n" "a non-negative integer" } { "byte-array" byte-array } }
  35 { $examples { $example "USING: byte-arrays prettyprint ;" "3 <byte-array> ." "B{ 0 0 0 }" } }
  36 { $description "Creates a new " { $link byte-array } " of length " { $snippet "n" } " bytes, with the elements all initialized to zero." } ;
  37
  38 HELP: (byte-array)
  39 { $values { "n" "a non-negative integer" } { "byte-array" byte-array } }
  40 { $examples { $unchecked-example "USING: byte-arrays prettyprint ;" "3 (byte-array) ." "B{ 103 189 48 }" } }
  41 { $description "Creates a new " { $link byte-array } " of length " { $snippet "n" } " bytes, with the elements containing unspecified values." } ;
  42
  43 { <byte-array> (byte-array) } related-words
  44
  45 HELP: >byte-array
  46 { $values { "seq" sequence } { "byte-array" byte-array } }
  47 { $description "Outputs a freshly-allocated byte array whose elements have the same signed byte values as a given sequence." }
  48 { $errors "Throws an error if the sequence contains elements other than integers." } ;
  49
  50 HELP: 1byte-array
  51 { $values
  52      { "x" object }
  53      { "byte-array" byte-array } }
  54 { $description "Creates a new byte-array with one element." } ;
  55
  56 HELP: 2byte-array
  57 { $values
  58      { "x" object } { "y" object }
  59      { "byte-array" byte-array } }
  60 { $description "Creates a new byte-array with two elements." } ;
  61
  62 HELP: 3byte-array
  63 { $values
  64      { "x" object } { "y" object } { "z" object }
  65      { "byte-array" byte-array } }
  66 { $description "Creates a new byte-array with three element." } ;
  67
  68 HELP: 4byte-array
  69 { $values
  70      { "w" object } { "x" object } { "y" object } { "z" object }
  71      { "byte-array" byte-array } }
  72 { $description "Creates a new byte-array with four elements." } ;
  73
  74 { 1byte-array 2byte-array 3byte-array 4byte-array } related-words
  75
  76 HELP: resize-byte-array
  77 { $values { "n" "a non-negative integer" } { "byte-array" byte-array } { "new-byte-array" byte-array } }
  78 { $description "Resizes the byte array to have a length of " { $snippet "n" } " elements. When making the byte array shorter, this word may either create a new byte array or modify the existing byte array in place. When making the byte array longer, this word always allocates a new byte array, filling remaining space with zeroes." }
  79 { $side-effects "byte-array" } ;