core/byte-vectors/byte-vectors-docs.factor

   1 USING: help.markup help.syntax sequences ;
   2 IN: byte-vectors
   3
   4 ARTICLE: "byte-vectors" "Byte vectors"
   5 "The " { $vocab-link "byte-vectors" } " vocabulary implements resizable mutable sequence of unsigned bytes. Byte vectors implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them."
   6 $nl
   7 "Byte vectors form a class:"
   8 { $subsections
   9     byte-vector
  10     byte-vector?
  11 }
  12 "Creating byte vectors:"
  13 { $subsections
  14     >byte-vector
  15     <byte-vector>
  16 }
  17 "Literal syntax:"
  18 { $subsections POSTPONE: BV{ }
  19 "If you don't care about initial capacity, a more elegant way to create a new byte vector is to write:"
  20 { $code "BV{ } clone" } ;
  21
  22 ABOUT: "byte-vectors"
  23
  24 HELP: byte-vector
  25 { $class-description "The class of resizable byte vectors. See " { $link "byte-vectors" } " for information." } ;
  26
  27 HELP: <byte-vector>
  28 { $values { "n" "a positive integer specifying initial capacity" } { "byte-vector" byte-vector } }
  29 { $description "Creates a new byte vector that can hold " { $snippet "n" } " bytes before resizing." } ;
  30
  31 HELP: >byte-vector
  32 { $values { "seq" sequence } { "byte-vector" byte-vector } }
  33 { $description "Outputs a freshly-allocated byte vector with the same elements as a given sequence." }
  34 { $errors "Throws an error if the sequence contains elements other than integers." } ;
  35
  36 HELP: BV{
  37 { $syntax "BV{ elements... }" }
  38 { $values { "elements" "a list of bytes" } }
  39 { $description "Marks the beginning of a literal byte vector. Literal byte vectors are terminated by " { $link POSTPONE: } } "." }
  40 { $examples { $code "BV{ 1 2 3 12 }" } } ;