extra/bit-arrays/bit-arrays-docs.factor

   1 USING: arrays help.markup help.syntax kernel
   2 kernel.private math prettyprint strings vectors sbufs ;
   3 IN: bit-arrays
   4
   5 ARTICLE: "bit-arrays" "Bit arrays"
   6 "Bit array are a fixed-size mutable sequences (" { $link "sequence-protocol" } ") whose elements are either " { $link t } " or " { $link f } ". Each element only uses one bit of storage, hence the name."
   7 $nl
   8 "Bit array words are in the " { $vocab-link "bit-arrays" } " vocabulary."
   9 $nl
  10 "Bit 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" } "."
  11 $nl
  12 "Bit arrays form a class of objects:"
  13 { $subsection bit-array }
  14 { $subsection bit-array? }
  15 "Creating new bit arrays:"
  16 { $subsection >bit-array }
  17 { $subsection <bit-array> }
  18 "Efficiently setting and clearing all bits in a bit array:"
  19 { $subsection set-bits }
  20 { $subsection clear-bits }
  21 "Converting between unsigned integers and their binary representation:"
  22 { $subsection integer>bit-array }
  23 { $subsection bit-array>integer }
  24 "Bit array literal syntax:"
  25 { $subsection POSTPONE: ?{ } ;
  26
  27 ABOUT: "bit-arrays"
  28
  29 HELP: ?{
  30 { $syntax "?{ elements... }" }
  31 { $values { "elements" "a list of booleans" } }
  32 { $description "Marks the beginning of a literal bit array. Literal bit arrays are terminated by " { $link POSTPONE: } } "." }
  33 { $examples { $code "?{ t f t }" } } ;
  34
  35 HELP: bit-array
  36 { $description "The class of fixed-length bit arrays." } ;
  37
  38 HELP: <bit-array> ( n -- bit-array )
  39 { $values { "n" "a non-negative integer" } { "bit-array" "a new " { $link bit-array } } }
  40 { $description "Creates a new bit array with the given length and all elements initially set to " { $link f } "." } ;
  41
  42 HELP: >bit-array
  43 { $values { "seq" "a sequence" } { "bit-array" bit-array } }
  44 { $description "Outputs a freshly-allocated bit array whose elements have the same boolean values as a given sequence." } ;
  45
  46 HELP: clear-bits
  47 { $values { "bit-array" bit-array } }
  48 { $description "Sets all elements of the bit array to " { $link f } "." }
  49 { $notes "Calling this word is more efficient than the following:"
  50     { $code "[ drop f ] change-each" }
  51 }
  52 { $side-effects "bit-array" } ;
  53
  54 HELP: set-bits
  55 { $values { "bit-array" bit-array } }
  56 { $description "Sets all elements of the bit array to " { $link t } "." }
  57 { $notes "Calling this word is more efficient than the following:"
  58     { $code "[ drop t ] change-each" }
  59 }
  60 { $side-effects "bit-array" } ;
  61
  62 HELP: integer>bit-array
  63 { $values { "integer" integer } { "bit-array" bit-array } }
  64 { $description "Outputs a freshly-allocated bit array whose elements correspond to the bits in the binary representation of the given unsigned integer value." }
  65 { $notes "The bits of the integer are stored in the resulting bit array in order of ascending significance, least significant bit first. This word will fail if passed a negative integer. If you want the two's-complement binary representation of a negative number, use " { $link bitnot } " to get the complement of the number first. This word works with fixnums or bignums of any size; it is not limited by fixnum size or machine word size." } ;
  66
  67 HELP: bit-array>integer
  68 { $values { "bit-array" bit-array } { "integer" integer } }
  69 { $description "Outputs the unsigned integer whose binary representation corresponds to the contents of the given bit array." }
  70 { $notes "The bits of the integer are taken from the bit array in order of ascending significance, least significant bit first. This word is able to return fixnums or bignums of any size; it is not limited by fixnum size or machine word size." } ;