basis/math/bitfields/bitfields-docs.factor

   1 USING: help.markup help.syntax math ;
   2 IN: math.bitfields
   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 } ;