math.bitwise: Add bit-range

basis/math/bitwise/bitwise-docs.factor

@@ -37,6 +37,11 @@ HELP: bits
 { $description "Keep only n bits from the integer m." }
 { $example "USING: math.bitwise prettyprint ;" "0x123abcdef 16 bits .h" "cdef" } ;
 
+HELP: bit-range
+{ $values { "x" integer } { "high" integer } { "low" integer } { "y" integer } }
+{ $description "Extract a range of bits from an integer, inclusive of each boundary." }
+{ $example "USING: math.bitwise prettyprint ;" "0b1100 3 2 bit-range .b" "11" } ;
+
 HELP: bitroll
 { $values { "x" integer } { "s" "a shift integer" } { "w" "a wrap integer" } { "y" integer }
 }
@@ -441,6 +446,11 @@ $nl
     bit?
     bit-clear?
 }
+"Extracting bits from an integer:"
+{ $subsections
+    bit-range
+    bits
+}
 "Toggling a bit:"
 { $subsections
     toggle-bit

basis/math/bitwise/bitwise-tests.factor

@@ -77,3 +77,5 @@ SPECIALIZED-ARRAY: uint-4
 [ t ] [ 0x0 1 bit-clear? ] unit-test
 
 [ -1 bit-count ] [ invalid-bit-count-target? ] must-fail-with
+
+{ 0b11 } [ 0b110000 5 4 bit-range ] unit-test

basis/math/bitwise/bitwise.factor

@@ -28,6 +28,8 @@ IN: math.bitwise
 : next-even ( m -- n ) >even 2 + ; foldable
 : next-odd ( m -- n ) dup even? [ 1 + ] [ 2 + ] if ; foldable
 : shift-mod ( m s w -- n ) [ shift ] dip 2^ wrap ; inline
+: bit-range ( x high low -- y )
+    [ nip neg shift ] [ - 1 + ] 2bi bits ;
 
 : bitroll ( x s w -- y )
     [ wrap ] keep