basis/math/bitwise/bitwise-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax math sequences ;
   4 IN: math.bitwise
   5
   6 HELP: bitfield
   7 { $values { "values..." "a series of objects" } { "bitspec" "an array" } { "n" integer } }
   8 { $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:"
   9     { $list
  10         { { $snippet "{ constant shift }" } " - the resulting bit field is bitwise or'd with " { $snippet "constant" } " shifted to the right by " { $snippet "shift" } " bits" }
  11         { { $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" }
  12         { { $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" }
  13     }
  14 "The bit field specifier is processed left to right, so stack values should be supplied in reverse order." }
  15 { $examples
  16     "Consider the following specification:"
  17     { $list
  18         { "bits 0-10 are set to the value of " { $snippet "x" } }
  19         { "bits 11-14 are set to the value of " { $snippet "y" } }
  20         { "bit 15 is always on" }
  21         { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
  22     }
  23     "Such a bit field construction can be specified with a word like the following:"
  24     { $code
  25         ": baz-bitfield ( x y z -- n )"
  26         "    {"
  27         "        { fooify 16 }"
  28         "        { 1 15 }"
  29         "        11"
  30         "        0"
  31         "    } ;"
  32     }
  33 } ;
  34
  35 HELP: bits
  36 { $values { "m" integer } { "n" integer } { "m'" integer } }
  37 { $description "Keep only n bits from the integer m." }
  38 { $example "USING: math.bitwise prettyprint ;" "HEX: 123abcdef 16 bits .h" "cdef" } ;
  39
  40 HELP: bitroll
  41 { $values { "x" integer } { "s" "a shift integer" } { "w" "a wrap integer" } { "y" integer }
  42 }
  43 { $description "Roll n by s bits to the left, wrapping around after w bits." }
  44 { $examples
  45     { $example "USING: math.bitwise prettyprint ;" "1 -1 32 bitroll .b" "10000000000000000000000000000000" }
  46     { $example "USING: math.bitwise prettyprint ;" "HEX: ffff0000 8 32 bitroll .h" "ff0000ff" }
  47 } ;
  48
  49 HELP: bit-clear?
  50 { $values
  51      { "x" integer } { "n" integer }
  52      { "?" "a boolean" }
  53 }
  54 { $description "Returns " { $link t } " if the nth bit is set to zero." }
  55 { $examples
  56     { $example "USING: math.bitwise prettyprint ;"
  57                "HEX: ff 8 bit-clear? ."
  58                "t"
  59     }
  60     { $example "" "USING: math.bitwise prettyprint ;"
  61                "HEX: ff 7 bit-clear? ."
  62                "f"
  63     }
  64 } ;
  65
  66 { bit? bit-clear? set-bit clear-bit } related-words
  67
  68 HELP: bit-count
  69 { $values
  70      { "x" integer }
  71      { "n" integer }
  72 }
  73 { $description "Returns the number of set bits as an integer." }
  74 { $examples
  75     { $example "USING: math.bitwise prettyprint ;"
  76                "HEX: f0 bit-count ."
  77                "4"
  78     }
  79     { $example "USING: math.bitwise prettyprint ;"
  80                "-7 bit-count ."
  81                "2"
  82     }
  83 } ;
  84
  85 HELP: bitroll-32
  86 { $values
  87      { "n" integer } { "s" integer }
  88      { "n'" integer }
  89 }
  90 { $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
  91 { $examples
  92     { $example "USING: math.bitwise prettyprint ;"
  93                "HEX: 1 10 bitroll-32 .h"
  94                "400"
  95     }
  96     { $example "USING: math.bitwise prettyprint ;"
  97                "HEX: 1 -10 bitroll-32 .h"
  98                "400000"
  99     }
 100 } ;
 101
 102 HELP: bitroll-64
 103 { $values
 104      { "n" integer } { "s" "a shift integer" }
 105      { "n'" integer }
 106 }
 107 { $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
 108 { $examples
 109     { $example "USING: math.bitwise prettyprint ;"
 110                "HEX: 1 10 bitroll-64 .h"
 111                "400"
 112     }
 113     { $example "USING: math.bitwise prettyprint ;"
 114                "HEX: 1 -10 bitroll-64 .h"
 115                "40000000000000"
 116     }
 117 } ;
 118
 119 { bitroll bitroll-32 bitroll-64 } related-words
 120
 121 HELP: clear-bit
 122 { $values
 123      { "x" integer } { "n" integer }
 124      { "y" integer }
 125 }
 126 { $description "Sets the nth bit of " { $snippet "x" } " to zero." }
 127 { $examples
 128     { $example "USING: math.bitwise kernel prettyprint ;"
 129         "HEX: ff 7 clear-bit .h"
 130         "7f"
 131     }
 132 } ;
 133
 134 HELP: flags
 135 { $values
 136      { "values" sequence }
 137 }
 138 { $description "Constructs a constant flag value from a sequence of integers or words that output integers. The resulting constant is computed at compile-time, which makes this word as efficient as using a literal integer." }
 139 { $examples
 140     { $example "USING: math.bitwise kernel prettyprint ;"
 141         "IN: scratchpad"
 142         ": MY-CONSTANT HEX: 1 ; inline"
 143         "{ HEX: 20 MY-CONSTANT BIN: 100 } flags .h"
 144         "25"
 145     }
 146 } ;
 147
 148 HELP: mask
 149 { $values
 150      { "x" integer } { "n" integer }
 151      { "?" "a boolean" }
 152 }
 153 { $description "After the operation, only the bits that were set in both the mask and the original number are set." }
 154 { $examples
 155     { $example "USING: math.bitwise kernel prettyprint ;"
 156         "BIN: 11111111 BIN: 101 mask .b"
 157         "101"
 158     }
 159 } ;
 160
 161 HELP: mask-bit
 162 { $values
 163      { "m" integer } { "n" integer }
 164      { "m'" integer }
 165 }
 166 { $description "Turns off all bits besides the nth bit." }
 167 { $examples
 168     { $example "USING: math.bitwise kernel prettyprint ;"
 169         "HEX: ff 2 mask-bit .b"
 170         "100"
 171     }
 172 } ;
 173
 174 HELP: mask?
 175 { $values
 176      { "x" integer } { "n" integer }
 177      { "?" "a boolean" }
 178 }
 179 { $description "Returns true if all of the bits in the mask " { $snippet "n" } " are set in the integer input " { $snippet "x" } "." }
 180 { $examples
 181     { $example "USING: math.bitwise kernel prettyprint ;"
 182         "HEX: ff HEX: f mask? ."
 183         "t"
 184     }
 185
 186     { $example "USING: math.bitwise kernel prettyprint ;"
 187         "HEX: f0 HEX: 1 mask? ."
 188         "f"
 189     }
 190 } ;
 191
 192 HELP: on-bits
 193 { $values
 194      { "n" integer }
 195      { "m" integer }
 196 }
 197 { $description "Returns an integer with " { $snippet "n" } " bits set." }
 198 { $examples
 199     { $example "USING: math.bitwise kernel prettyprint ;"
 200         "6 on-bits .h"
 201         "3f"
 202     }
 203     { $example "USING: math.bitwise kernel prettyprint ;"
 204         "64 on-bits .h"
 205         "ffffffffffffffff"
 206     }
 207 } ;
 208
 209 HELP: toggle-bit
 210 { $values
 211      { "m" integer }
 212      { "n" integer }
 213      { "m'" integer }
 214 }
 215 { $description "Toggles the nth bit of an integer." }
 216 { $examples
 217     { $example "USING: math.bitwise kernel prettyprint ;"
 218         "0 3 toggle-bit .b"
 219         "1000"
 220     }
 221     { $example "USING: math.bitwise kernel prettyprint ;"
 222         "BIN: 1000 3 toggle-bit .b"
 223         "0"
 224     }
 225 } ;
 226
 227 HELP: set-bit
 228 { $values
 229      { "x" integer } { "n" integer }
 230      { "y" integer }
 231 }
 232 { $description "Sets the nth bit of " { $snippet "x" } "." }
 233 { $examples
 234     { $example "USING: math.bitwise kernel prettyprint ;"
 235         "0 5 set-bit .h"
 236         "20"
 237     }
 238 } ;
 239
 240 HELP: shift-mod
 241 { $values
 242      { "n" integer } { "s" integer } { "w" integer }
 243      { "n" integer }
 244 }
 245 { $description "Calls " { $link shift } " on " { $snippet "n" } " and " { $snippet "s" } ", wrapping the result to " { $snippet "w" } " bits." } ;
 246
 247 HELP: unmask
 248 { $values
 249      { "x" integer } { "n" integer }
 250      { "?" "a boolean" }
 251 }
 252 { $description "Clears the bits in " { $snippet "x" } " if they are set in the mask " { $snippet "n" } "." }
 253 { $examples
 254     { $example "USING: math.bitwise kernel prettyprint ;"
 255         "HEX: ff  HEX: 0f unmask .h"
 256         "f0"
 257     }
 258 } ;
 259
 260 HELP: unmask?
 261 { $values
 262      { "x" integer } { "n" integer }
 263      { "?" "a boolean" }
 264 }
 265 { $description "Tests whether unmasking the bits in " { $snippet "x" } " would return an integer greater than zero." }
 266 { $examples
 267     { $example "USING: math.bitwise kernel prettyprint ;"
 268         "HEX: ff  HEX: 0f unmask? ."
 269         "t"
 270     }
 271 } ;
 272
 273 HELP: w*
 274 { $values
 275      { "int" integer } { "int" integer }
 276      { "int" integer }
 277 }
 278 { $description "Multiplies two integers and wraps the result to 32 bits." }
 279 { $examples
 280     { $example "USING: math.bitwise kernel prettyprint ;"
 281         "HEX: ffffffff HEX: 2 w* ."
 282         "4294967294"
 283     }
 284 } ;
 285
 286 HELP: w+
 287 { $values
 288      { "int" integer } { "int" integer }
 289      { "int" integer }
 290 }
 291 { $description "Adds two integers and wraps the result to 32 bits." }
 292 { $examples
 293     { $example "USING: math.bitwise kernel prettyprint ;"
 294         "HEX: ffffffff HEX: 2 w+ ."
 295         "1"
 296     }
 297 } ;
 298
 299 HELP: w-
 300 { $values
 301      { "int" integer } { "int" integer }
 302      { "int" integer }
 303 }
 304 { $description "Subtracts two integers and wraps the result to 32 bits." }
 305 { $examples
 306     { $example "USING: math.bitwise kernel prettyprint ;"
 307         "HEX: 0 HEX: ff w- ."
 308         "4294967041"
 309     }
 310 } ;
 311
 312 HELP: wrap
 313 { $values
 314      { "m" integer } { "n" integer }
 315      { "m'" integer }
 316 }
 317 { $description "Wraps an integer " { $snippet "m" } " by modding it by " { $snippet "n" } ". This word is uses bitwise arithmetic and does not actually call the modulus word, and as such can only mod by powers of two." }
 318 { $examples "Equivalent to modding by 8:"
 319     { $example
 320         "USING: math.bitwise prettyprint ;"
 321         "HEX: ffff 8 wrap .h"
 322         "7"
 323     }
 324 } ;
 325
 326 ARTICLE: "math-bitfields" "Constructing bit fields"
 327 "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:"
 328 { $subsection bitfield } ;
 329
 330 ARTICLE: "math.bitwise" "Additional bitwise arithmetic"
 331 "The " { $vocab-link "math.bitwise" } " vocabulary provides bitwise arithmetic words extending " { $link "bitwise-arithmetic" } ". They are useful for efficiency, low-level programming, and interfacing with C libraries."
 332 $nl
 333 "Setting and clearing bits:"
 334 { $subsection set-bit }
 335 { $subsection clear-bit }
 336 "Testing if bits are set or clear:"
 337 { $subsection bit? }
 338 { $subsection bit-clear? }
 339 "Operations with bitmasks:"
 340 { $subsection mask }
 341 { $subsection unmask }
 342 { $subsection mask? }
 343 { $subsection unmask? }
 344 "Generating an integer with n set bits:"
 345 { $subsection on-bits }
 346 "Counting the number of set bits:"
 347 { $subsection bit-count }
 348 "More efficient modding by powers of two:"
 349 { $subsection wrap }
 350 "Bit-rolling:"
 351 { $subsection bitroll }
 352 { $subsection bitroll-32 }
 353 { $subsection bitroll-64 }
 354 "32-bit arithmetic:"
 355 { $subsection w+ }
 356 { $subsection w- }
 357 { $subsection w* }
 358 "Bitfields:"
 359 { $subsection flags }
 360 { $subsection "math-bitfields" } ;
 361
 362 ABOUT: "math.bitwise"