! Copyright (C) 2008 Doug Coleman.
! See http://factorcode.org/license.txt for BSD license.
-USING: assocs help.markup help.syntax math sequences ;
+USING: assocs help.markup help.syntax math sequences kernel ;
IN: math.bitwise
HELP: bitfield
}
} ;
-HELP: bits
+HELP: bits
{ $values { "m" integer } { "n" integer } { "m'" integer } }
{ $description "Keep only n bits from the integer m." }
-{ $example "USING: math.bitwise prettyprint ;" "HEX: 123abcdef 16 bits .h" "cdef" } ;
+{ $example "USING: math.bitwise prettyprint ;" "0x123abcdef 16 bits .h" "cdef" } ;
HELP: bitroll
{ $values { "x" integer } { "s" "a shift integer" } { "w" "a wrap integer" } { "y" integer }
{ $description "Roll n by s bits to the left, wrapping around after w bits." }
{ $examples
{ $example "USING: math.bitwise prettyprint ;" "1 -1 32 bitroll .b" "10000000000000000000000000000000" }
- { $example "USING: math.bitwise prettyprint ;" "HEX: ffff0000 8 32 bitroll .h" "ff0000ff" }
+ { $example "USING: math.bitwise prettyprint ;" "0xffff0000 8 32 bitroll .h" "ff0000ff" }
} ;
HELP: bit-clear?
{ "?" "a boolean" }
}
{ $description "Returns " { $link t } " if the nth bit is set to zero." }
-{ $examples
+{ $examples
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: ff 8 bit-clear? ."
+ "0xff 8 bit-clear? ."
"t"
}
- { $example "" "USING: math.bitwise prettyprint ;"
- "HEX: ff 7 bit-clear? ."
+ { $example "USING: math.bitwise prettyprint ;"
+ "0xff 7 bit-clear? ."
"f"
}
} ;
HELP: bit-count
{ $values
- { "x" integer }
+ { "obj" object }
{ "n" integer }
}
-{ $description "Returns the number of set bits as an integer." }
-{ $examples
+{ $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." }
+{ $examples
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: f0 bit-count ."
+ "0xf0 bit-count ."
"4"
}
{ $example "USING: math.bitwise prettyprint ;"
- "-7 bit-count ."
+ "-1 32 bits bit-count ."
+ "32"
+ }
+ { $example "USING: math.bitwise prettyprint ;"
+ "B{ 1 0 1 } bit-count ."
"2"
}
} ;
HELP: bitroll-32
{ $values
- { "n" integer } { "s" integer }
- { "n'" integer }
-}
-{ $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
-{ $examples
+ { "m" integer } { "s" integer }
+ { "n" integer }
+}
+{ $description "Rolls the number " { $snippet "m" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
+{ $examples
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: 1 10 bitroll-32 .h"
+ "0x1 10 bitroll-32 .h"
"400"
}
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: 1 -10 bitroll-32 .h"
+ "0x1 -10 bitroll-32 .h"
"400000"
}
} ;
HELP: bitroll-64
{ $values
- { "n" integer } { "s" "a shift integer" }
- { "n'" integer }
+ { "m" integer } { "s" "a shift integer" }
+ { "n" integer }
}
-{ $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
-{ $examples
+{ $description "Rolls the number " { $snippet "m" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
+{ $examples
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: 1 10 bitroll-64 .h"
+ "0x1 10 bitroll-64 .h"
"400"
}
{ $example "USING: math.bitwise prettyprint ;"
- "HEX: 1 -10 bitroll-64 .h"
+ "0x1 -10 bitroll-64 .h"
"40000000000000"
}
} ;
{ $description "Sets the nth bit of " { $snippet "x" } " to zero." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ff 7 clear-bit .h"
+ "0xff 7 clear-bit .h"
"7f"
}
} ;
-HELP: flags
-{ $values
- { "values" sequence }
-}
-{ $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." }
-{ $examples
- { $example "USING: math.bitwise kernel prettyprint ;"
- "IN: scratchpad"
- "CONSTANT: x HEX: 1"
- "{ HEX: 20 x BIN: 100 } flags .h"
- "25"
- }
-} ;
-
HELP: symbols>flags
{ $values { "symbols" sequence } { "assoc" assoc } { "flag-bits" integer } }
{ $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." }
}
} ;
+HELP: >even
+{ $values
+ { "m" integer }
+ { "n" integer }
+}
+{ $examples
+ { $example "USING: math.bitwise prettyprint ;"
+ "7 >even ."
+ "6"
+ }
+}
+{ $description "Sets the lowest bit in the integer to 0, which either does nothing or outputs 1 less than the input integer." } ;
+
+HELP: >odd
+{ $values
+ { "m" integer }
+ { "n" integer }
+}
+{ $examples
+ { $example "USING: math.bitwise prettyprint ;"
+ "4 >odd ."
+ "5"
+ }
+}
+{ $description "Sets the lowest bit in the integer to 1, which either does nothing or outputs 1 more than the input integer." } ;
+
+HELP: >signed
+{ $values
+ { "x" integer } { "n" integer }
+ { "y" integer }
+}
+{ $examples
+ { $example "USING: math.bitwise prettyprint ;"
+ "0xff 8 >signed ."
+ "-1"
+ }
+}
+{ $description "Interprets a number " { $snippet "x" } " as an " { $snippet "n" } "-bit number and converts it to a negative number " { $snippet "n" } "-bit number if the topmost bit is set." } ;
+
HELP: mask
{ $values
{ "x" integer } { "n" integer }
{ $description "After the operation, only the bits that were set in both the mask and the original number are set." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "BIN: 11111111 BIN: 101 mask .b"
+ "0b11111111 0b101 mask .b"
"101"
}
} ;
{ $description "Turns off all bits besides the nth bit." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ff 2 mask-bit .b"
+ "0xff 2 mask-bit .b"
"100"
}
} ;
{ $description "Returns true if all of the bits in the mask " { $snippet "n" } " are set in the integer input " { $snippet "x" } "." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ff HEX: f mask? ."
+ "0xff 0xf mask? ."
"t"
}
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: f0 HEX: 1 mask? ."
+ "0xf0 0x1 mask? ."
"f"
}
} ;
+HELP: even-parity?
+{ $values
+ { "obj" object }
+ { "?" boolean }
+}
+{ $description "Returns true if the number of set bits in an object is even." } ;
+
+HELP: odd-parity?
+{ $values
+ { "obj" object }
+ { "?" boolean }
+}
+{ $description "Returns true if the number of set bits in an object is odd." } ;
+
HELP: on-bits
{ $values
- { "n" integer }
{ "m" integer }
+ { "n" integer }
}
-{ $description "Returns an integer with " { $snippet "n" } " bits set." }
+{ $description "Returns an integer with " { $snippet "m" } " bits set." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
"6 on-bits .h"
"1000"
}
{ $example "USING: math.bitwise kernel prettyprint ;"
- "BIN: 1000 3 toggle-bit .b"
+ "0b1000 3 toggle-bit .b"
"0"
}
} ;
HELP: shift-mod
{ $values
- { "n" integer } { "s" integer } { "w" integer }
+ { "m" integer } { "s" integer } { "w" integer }
{ "n" integer }
}
{ $description "Calls " { $link shift } " on " { $snippet "n" } " and " { $snippet "s" } ", wrapping the result to " { $snippet "w" } " bits." } ;
{ $description "Clears the bits in " { $snippet "x" } " if they are set in the mask " { $snippet "n" } "." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ff HEX: 0f unmask .h"
+ "0xff 0x0f unmask .h"
"f0"
}
} ;
{ $description "Tests whether unmasking the bits in " { $snippet "x" } " would return an integer greater than zero." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ff HEX: 0f unmask? ."
+ "0xff 0x0f unmask? ."
"t"
}
} ;
HELP: w*
{ $values
- { "int" integer } { "int" integer }
- { "int" integer }
+ { "x" integer } { "y" integer }
+ { "z" integer }
}
-{ $description "Multiplies two integers and wraps the result to 32 bits." }
+{ $description "Multiplies two integers and wraps the result to a 32-bit unsigned integer." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ffffffff HEX: 2 w* ."
+ "0xffffffff 0x2 w* ."
"4294967294"
}
} ;
HELP: w+
{ $values
- { "int" integer } { "int" integer }
- { "int" integer }
+ { "x" integer } { "y" integer }
+ { "z" integer }
}
-{ $description "Adds two integers and wraps the result to 32 bits." }
+{ $description "Adds two integers and wraps the result to a 32-bit unsigned integer." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: ffffffff HEX: 2 w+ ."
+ "0xffffffff 0x2 w+ ."
"1"
}
} ;
HELP: w-
{ $values
- { "int" integer } { "int" integer }
- { "int" integer }
+ { "x" integer } { "y" integer }
+ { "z" integer }
}
-{ $description "Subtracts two integers and wraps the result to 32 bits." }
+{ $description "Subtracts two integers and wraps the result to a 32-bit unsigned integer." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
- "HEX: 0 HEX: ff w- ."
+ "0x0 0xff w- ."
"4294967041"
}
} ;
+HELP: W*
+{ $values
+ { "x" integer } { "y" integer }
+ { "z" integer }
+}
+{ $description "Multiplies two integers and wraps the result to a 64-bit unsigned integer." }
+{ $examples
+ { $example "USING: math.bitwise kernel prettyprint ;"
+ "0xffffffffffffffff 0x2 W* ."
+ "18446744073709551614"
+ }
+} ;
+
+HELP: W+
+{ $values
+ { "x" integer } { "y" integer }
+ { "z" integer }
+}
+{ $description "Adds two integers and wraps the result to 64-bit unsigned integer." }
+{ $examples
+ { $example "USING: math.bitwise kernel prettyprint ;"
+ "0xffffffffffffffff 0x2 W+ ."
+ "1"
+ }
+} ;
+
+HELP: W-
+{ $values
+ { "x" integer } { "y" integer }
+ { "z" integer }
+}
+{ $description "Subtracts two integers and wraps the result to a 64-bit unsigned integer." }
+{ $examples
+ { $example "USING: math.bitwise kernel prettyprint ;"
+ "0x0 0xff W- ."
+ "18446744073709551361"
+ }
+} ;
+
HELP: wrap
{ $values
{ "m" integer } { "n" integer }
}
{ $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." }
{ $examples "Equivalent to modding by 8:"
- { $example
+ { $example
"USING: math.bitwise prettyprint ;"
- "HEX: ffff 8 wrap .h"
+ "0xffff 8 wrap .h"
"7"
}
} ;
ARTICLE: "math-bitfields" "Constructing bit fields"
"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:"
-{ $subsection bitfield } ;
+{ $subsections bitfield } ;
ARTICLE: "math.bitwise" "Additional bitwise arithmetic"
"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."
$nl
"Setting and clearing bits:"
-{ $subsection set-bit }
-{ $subsection clear-bit }
+{ $subsections
+ set-bit
+ clear-bit
+}
"Testing if bits are set or clear:"
-{ $subsection bit? }
-{ $subsection bit-clear? }
+{ $subsections
+ bit?
+ bit-clear?
+}
+"Toggling a bit:"
+{ $subsections
+ toggle-bit
+}
"Operations with bitmasks:"
-{ $subsection mask }
-{ $subsection unmask }
-{ $subsection mask? }
-{ $subsection unmask? }
+{ $subsections
+ mask
+ unmask
+ mask?
+ unmask?
+}
"Generating an integer with n set bits:"
-{ $subsection on-bits }
+{ $subsections on-bits }
"Counting the number of set bits:"
-{ $subsection bit-count }
+{ $subsections bit-count }
+"Testing the parity of an object:"
+{ $subsections even-parity? odd-parity? }
"More efficient modding by powers of two:"
-{ $subsection wrap }
+{ $subsections wrap }
"Bit-rolling:"
-{ $subsection bitroll }
-{ $subsection bitroll-32 }
-{ $subsection bitroll-64 }
+{ $subsections
+ bitroll
+ bitroll-32
+ bitroll-64
+}
"32-bit arithmetic:"
-{ $subsection w+ }
-{ $subsection w- }
-{ $subsection w* }
+{ $subsections
+ w+
+ w-
+ w*
+}
+"64-bit arithmetic:"
+{ $subsections
+ W+
+ W-
+ W*
+}
+"Converting a number to the nearest even/odd:"
+{ $subsections
+ >even
+ >odd
+}
"Bitfields:"
-{ $subsection flags }
-{ $subsection "math-bitfields" } ;
+{ $subsections
+ "math-bitfields"
+} ;
ABOUT: "math.bitwise"
projects / factor.git / blobdiff