basis/math/bitwise/bitwise-docs.factor

   1 USING: help.markup help.syntax math ;
   2 IN: math.bitwise
   3
   4 ARTICLE: "math-bitfields" "Constructing bit fields"
   5 "Some applications, such as binary communication protocols and assemblers, need to construct integers from elaborate bit field specifications. Hand-coding this using " { $link shift } " and " { $link bitor } " results in repetitive code. A higher-level facility exists to factor out this repetition:"
   6 { $subsection bitfield } ;
   7
   8 ABOUT: "math-bitfields"
   9
  10 HELP: bitfield
  11 { $values { "values..." "a series of objects" } { "bitspec" "an array" } { "n" integer } }
  12 { $description "Constructs an integer from a series of values on the stack together with a bit field specifier, which is an array whose elements have one of the following shapes:"
  13     { $list
  14         { { $snippet "{ constant shift }" } " - the resulting bit field is bitwise or'd with " { $snippet "constant" } " shifted to the right by " { $snippet "shift" } " bits" }
  15         { { $snippet "{ word shift }" } " - the resulting bit field is bitwise or'd with " { $snippet "word" } " applied to the top of the stack; the result is shifted to the right by " { $snippet "shift" } " bits" }
  16         { { $snippet "shift" } " - the resulting bit field is bitwise or'd with the top of the stack; the result is shifted to the right by " { $snippet "shift" } " bits" }
  17     }
  18 "The bit field specifier is processed left to right, so stack values should be supplied in reverse order." }
  19 { $examples
  20     "Consider the following specification:"
  21     { $list
  22         { "bits 0-10 are set to the value of " { $snippet "x" } }
  23         { "bits 11-14 are set to the value of " { $snippet "y" } }
  24         { "bit 15 is always on" }
  25         { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
  26     }
  27     "Such a bit field construction can be specified with a word like the following:"
  28     { $code
  29         ": baz-bitfield ( x y z -- n )"
  30         "    {"
  31         "        { fooify 16 }"
  32         "        { 1 15 }"
  33         "        11"
  34         "        0"
  35         "    } ;"
  36     }
  37 } ;
  38
  39 HELP: bits
  40 { $values { "m" integer } { "n" integer } { "m'" integer } }
  41 { $description "Keep only n bits from the integer m." }
  42 { $example "USING: math.bitwise prettyprint ;" "HEX: 123abcdef 16 bits .h" "cdef" } ;
  43
  44 HELP: bitroll
  45 { $values { "x" "an integer (input)" } { "s" "an integer (shift)" } { "w" "an integer (wrap)" } { "y" integer } }
  46 { $description "Roll n by s bits to the left, wrapping around after w bits." }
  47 { $examples
  48     { $example "USING: math.bitwise prettyprint ;" "1 -1 32 bitroll .b" "10000000000000000000000000000000" }
  49     { $example "USING: math.bitwise prettyprint ;" "HEX: ffff0000 8 32 bitroll .h" "ff0000ff" }
  50 } ;