basis/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-pointers" } "."
  11 $nl
  12 "Bit arrays form a class of objects:"
  13 { $subsections
  14     bit-array
  15     bit-array?
  16 }
  17 "Creating new bit arrays:"
  18 { $subsections
  19     >bit-array
  20     <bit-array>
  21 }
  22 "Efficiently setting and clearing all bits in a bit array:"
  23 { $subsections
  24     set-bits
  25     clear-bits
  26 }
  27 "Converting between unsigned integers and their binary representation:"
  28 { $subsections
  29     integer>bit-array
  30     bit-array>integer
  31 }
  32 "Bit array literal syntax:"
  33 { $subsections POSTPONE: ?{ } ;
  34
  35 ABOUT: "bit-arrays"
  36
  37 HELP: ?{
  38 { $syntax "?{ elements... }" }
  39 { $values { "elements" "a list of booleans" } }
  40 { $description "Marks the beginning of a literal bit array. Literal bit arrays are terminated by " { $link POSTPONE: } } "." }
  41 { $examples { $code "?{ t f t }" } } ;
  42
  43 HELP: bit-array
  44 { $description "The class of fixed-length bit arrays." } ;
  45
  46 HELP: <bit-array>
  47 { $values { "n" "a non-negative integer" } { "bit-array" "a new " { $link bit-array } } }
  48 { $description "Creates a new bit array with the given length and all elements initially set to " { $link f } "." } ;
  49
  50 HELP: >bit-array
  51 { $values { "seq" "a sequence" } { "bit-array" bit-array } }
  52 { $description "Outputs a freshly-allocated bit array whose elements have the same boolean values as a given sequence." } ;
  53
  54 HELP: clear-bits
  55 { $values { "bit-array" bit-array } }
  56 { $description "Sets all elements of the bit array to " { $link f } "." }
  57 { $notes "Calling this word is more efficient than the following:"
  58     { $code "[ drop f ] map! drop" }
  59 }
  60 { $side-effects "bit-array" } ;
  61
  62 HELP: set-bits
  63 { $values { "bit-array" bit-array } }
  64 { $description "Sets all elements of the bit array to " { $link t } "." }
  65 { $notes "Calling this word is more efficient than the following:"
  66     { $code "[ drop t ] map! drop" }
  67 }
  68 { $side-effects "bit-array" } ;
  69
  70 HELP: integer>bit-array
  71 { $values { "n" integer } { "bit-array" bit-array } }
  72 { $description "Outputs a freshly-allocated bit array whose elements correspond to the bits in the binary representation of the given unsigned integer value." }
  73 { $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." } ;
  74
  75 HELP: bit-array>integer
  76 { $values { "bit-array" bit-array } { "n" integer } }
  77 { $description "Outputs the unsigned integer whose binary representation corresponds to the contents of the given bit array." }
  78 { $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." } ;