1 ! Copyright (C) 2008 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: assocs help.markup help.syntax math sequences kernel ;
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:"
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" }
14 "The bit field specifier is processed left to right, so stack values should be supplied in reverse order." }
16 "Consider the following specification:"
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" } }
23 "Such a bit field construction can be specified with a word like the following:"
25 ": baz-bitfield ( x y z -- n )"
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" } ;
41 { $values { "x" integer } { "s" "a shift integer" } { "w" "a wrap integer" } { "y" integer }
43 { $description "Roll n by s bits to the left, wrapping around after w bits." }
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" }
51 { "x" integer } { "n" integer }
54 { $description "Returns " { $link t } " if the nth bit is set to zero." }
56 { $example "USING: math.bitwise prettyprint ;"
57 "HEX: ff 8 bit-clear? ."
60 { $example "" "USING: math.bitwise prettyprint ;"
61 "HEX: ff 7 bit-clear? ."
66 { bit? bit-clear? set-bit clear-bit } related-words
73 { $description "Returns the number of set bits as an object. This word only works on non-negative integers or objects that can be represented as a byte-array." }
75 { $example "USING: math.bitwise prettyprint ;"
79 { $example "USING: math.bitwise prettyprint ;"
80 "-1 32 bits bit-count ."
83 { $example "USING: math.bitwise prettyprint ;"
84 "B{ 1 0 1 } bit-count ."
91 { "n" integer } { "s" integer }
94 { $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
96 { $example "USING: math.bitwise prettyprint ;"
97 "HEX: 1 10 bitroll-32 .h"
100 { $example "USING: math.bitwise prettyprint ;"
101 "HEX: 1 -10 bitroll-32 .h"
108 { "n" integer } { "s" "a shift integer" }
111 { $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
113 { $example "USING: math.bitwise prettyprint ;"
114 "HEX: 1 10 bitroll-64 .h"
117 { $example "USING: math.bitwise prettyprint ;"
118 "HEX: 1 -10 bitroll-64 .h"
123 { bitroll bitroll-32 bitroll-64 } related-words
127 { "x" integer } { "n" integer }
130 { $description "Sets the nth bit of " { $snippet "x" } " to zero." }
132 { $example "USING: math.bitwise kernel prettyprint ;"
133 "HEX: ff 7 clear-bit .h"
139 { $values { "values" sequence } }
140 { $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." }
142 { $example "USING: math.bitwise kernel prettyprint ;"
145 "{ HEX: 20 x BIN: 100 } flags .h"
151 { $values { "symbols" sequence } { "assoc" assoc } { "flag-bits" integer } }
152 { $description "Constructs an integer value by mapping the values in the " { $snippet "symbols" } " sequence to integer values using " { $snippet "assoc" } " and " { $link bitor } "ing the values together." }
154 { $example "USING: math.bitwise prettyprint ui.gadgets.worlds ;"
156 "CONSTANT: window-controls>flags H{"
157 " { close-button 1 }"
158 " { minimize-button 2 }"
159 " { maximize-button 4 }"
160 " { resize-handles 8 }"
161 " { small-title-bar 16 }"
162 " { normal-title-bar 32 }"
164 "{ resize-handles close-button small-title-bar } window-controls>flags symbols>flags ."
171 { "x" integer } { "n" integer }
174 { $description "After the operation, only the bits that were set in both the mask and the original number are set." }
176 { $example "USING: math.bitwise kernel prettyprint ;"
177 "BIN: 11111111 BIN: 101 mask .b"
184 { "m" integer } { "n" integer }
187 { $description "Turns off all bits besides the nth bit." }
189 { $example "USING: math.bitwise kernel prettyprint ;"
190 "HEX: ff 2 mask-bit .b"
197 { "x" integer } { "n" integer }
200 { $description "Returns true if all of the bits in the mask " { $snippet "n" } " are set in the integer input " { $snippet "x" } "." }
202 { $example "USING: math.bitwise kernel prettyprint ;"
203 "HEX: ff HEX: f mask? ."
207 { $example "USING: math.bitwise kernel prettyprint ;"
208 "HEX: f0 HEX: 1 mask? ."
218 { $description "Returns true if the number of set bits in an object is even." } ;
225 { $description "Returns true if the number of set bits in an object is odd." } ;
232 { $description "Returns an integer with " { $snippet "n" } " bits set." }
234 { $example "USING: math.bitwise kernel prettyprint ;"
238 { $example "USING: math.bitwise kernel prettyprint ;"
250 { $description "Toggles the nth bit of an integer." }
252 { $example "USING: math.bitwise kernel prettyprint ;"
256 { $example "USING: math.bitwise kernel prettyprint ;"
257 "BIN: 1000 3 toggle-bit .b"
264 { "x" integer } { "n" integer }
267 { $description "Sets the nth bit of " { $snippet "x" } "." }
269 { $example "USING: math.bitwise kernel prettyprint ;"
277 { "n" integer } { "s" integer } { "w" integer }
280 { $description "Calls " { $link shift } " on " { $snippet "n" } " and " { $snippet "s" } ", wrapping the result to " { $snippet "w" } " bits." } ;
284 { "x" integer } { "n" integer }
287 { $description "Clears the bits in " { $snippet "x" } " if they are set in the mask " { $snippet "n" } "." }
289 { $example "USING: math.bitwise kernel prettyprint ;"
290 "HEX: ff HEX: 0f unmask .h"
297 { "x" integer } { "n" integer }
300 { $description "Tests whether unmasking the bits in " { $snippet "x" } " would return an integer greater than zero." }
302 { $example "USING: math.bitwise kernel prettyprint ;"
303 "HEX: ff HEX: 0f unmask? ."
310 { "int" integer } { "int" integer }
313 { $description "Multiplies two integers and wraps the result to 32 bits." }
315 { $example "USING: math.bitwise kernel prettyprint ;"
316 "HEX: ffffffff HEX: 2 w* ."
323 { "int" integer } { "int" integer }
326 { $description "Adds two integers and wraps the result to 32 bits." }
328 { $example "USING: math.bitwise kernel prettyprint ;"
329 "HEX: ffffffff HEX: 2 w+ ."
336 { "int" integer } { "int" integer }
339 { $description "Subtracts two integers and wraps the result to 32 bits." }
341 { $example "USING: math.bitwise kernel prettyprint ;"
342 "HEX: 0 HEX: ff w- ."
349 { "m" integer } { "n" integer }
352 { $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." }
353 { $examples "Equivalent to modding by 8:"
355 "USING: math.bitwise prettyprint ;"
356 "HEX: ffff 8 wrap .h"
361 ARTICLE: "math-bitfields" "Constructing bit fields"
362 "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:"
363 { $subsections bitfield } ;
365 ARTICLE: "math.bitwise" "Additional bitwise arithmetic"
366 "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."
368 "Setting and clearing bits:"
373 "Testing if bits are set or clear:"
378 "Operations with bitmasks:"
385 "Generating an integer with n set bits:"
386 { $subsections on-bits }
387 "Counting the number of set bits:"
388 { $subsections bit-count }
389 "Testing the parity of an object:"
390 { $subsections even-parity? odd-parity? }
391 "More efficient modding by powers of two:"
392 { $subsections wrap }
411 ABOUT: "math.bitwise"