bit-twiddle 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e99fcc28158a3f2bd16c5e37e6cf4ad41761b1c
-  data.tar.gz: 5456fbb26c9f7ef7ac8bfd825ad06212ee99d757
+  metadata.gz: 6c88090274260692eb69445316299a13b3b63b89
+  data.tar.gz: d5b7938cfeb8c8de999b052f4c08b59038f97bcf
 SHA512:
-  metadata.gz: 26e0e2e18939a02a45e728360fa49befe19a42569e7669de1fa422f22c0c9611832bc069c7a91bf8782dda942814a319c6093981de8e9ea53aa1d68daae74a5e
-  data.tar.gz: a220ae44f99ea25432b8df8a3ff5ce7ec48781c9416775bff9088ff6243ebd6656c95273cc0cf2ead096e9e640bae7a48529077cb32304f9e0757d23f2630fc0
+  metadata.gz: 4b13792ba786af66d85c982aab50165cdeabd8569f3927e9508732190f8cf3e9f2598d7ebbce2bfb68eb8f6de4c0af3f11cb627d9882802acbf2d03aa58ee73a
+  data.tar.gz: f4e55b16fe4753d66ddf7e87b3d25692c6e8d5ed0331e6f2eee36122c3f35baba50194638532ac4cf0c5bbfa89452886fc522afdba3ed2421e55d16d61b2e7f3

data/README.md

@@ -1,18 +1,116 @@
 #Fast bitwise operations for Ruby
 
-Ruby has built-in implementations of the "workhorses" of bit manipulation: bitwise AND, OR, NOT, and XOR operations and bit shifts. This library adds more bitwise operations, which may be useful in implementing some algorithms. All the added operations are implemented in optimized C code. All operations on integers are implemented on both `Fixnum` and `Bignum`. Install this goodness with:
+Ruby has built-in implementations of the "workhorses" of bit manipulation: bitwise AND, OR, NOT, and XOR operations and bit shifts. This library adds more bitwise operations, which may be useful in implementing some algorithms. All the added operations are implemented in optimized C code (so this is MRI-only). All operations on integers are implemented for both `Fixnum`s and `Bignum`s.
+
+Install this goodness with:
 
 ```ruby
 gem install bit-twiddle
 ```
 
-Here is what it offers:
+If you want all operations to be namespaced under the `BitTwiddle` module, load it with:
 
-### Population count
+```ruby
+require "bit-twiddle"
+```
 
-"Popcount" or "population count" refers to the number of 1 bits in a binary number. For example, the popcount of 11 (binary 1011) is 3. Typically, Ruby programmers use goofy tricks like `num.to_s(2).count("1")` to compute this quantity. Don't bother with that nonsense. Just use the fastest native code which GCC can generate for your CPU architecture. (On x86 CPUs with SSE4, that is a single POPCNT instruction.) Like so:
+Or for all operations to be defined as instance methods on `Fixnum` and `Bignum`:
 
+```ruby
+require "bit-twiddle/core_ext"
 ```
+
+In many cases, `bit-twiddle` operations explicitly work on the low 8, 16, 32, or 64 bits of an integer. (For example, it defines `#bitreverse8`, `#bitreverse16`, `#bitreverse32`, and `#bitreverse64` methods.) If an integer's bit width is larger than the number of bits operated on, the higher-end bits are passed through unchanged.
+
+All methods automatically convert between `Fixnum` and `Bignum` as is most appropriate to represent their result.
+
+## Examples
+
+### Population count
+
+"Popcount" or "population count" refers to the number of 1 bits in a binary number. For example, the popcount of decimal 11 (binary 1011) is 3.
+
+Typically, Ruby programmers use goofy tricks like `num.to_s(2).count("1")` to compute this quantity. This is much faster, and doesn't needlessly allocate memory:
+
+```ruby
 7.popcount   # => 3
 255.popcount # => 255
 ```
+
+### Highest/lowest set bit
+
+```ruby
+8.hi_bit   # => 4
+255.hi_bit # => 8
+8.lo_bit   # => 4
+255.lo_bit # => 1
+```
+
+### Rotating bits
+
+```ruby
+0b10010011.rrot8(1).to_s(2).rjust(8,'0') # => "11001001"
+0b10010011.rrot8(2).to_s(2).rjust(8,'0') # => "11100100"
+0b10010011.rrot8(3).to_s(2).rjust(8,'0') # => "01110010"
+0b10010011.rrot8(4).to_s(2).rjust(8,'0') # => "00111001"
+0b10010011.rrot8(5).to_s(2).rjust(8,'0') # => "10011100"
+0b10010011.rrot8(6).to_s(2).rjust(8,'0') # => "01001110"
+
+0b10010011.lrot8(1).to_s(2).rjust(8,'0') # => "00100111"
+0b10010011.lrot8(2).to_s(2).rjust(8,'0') # => "01001110"
+0b10010011.lrot8(3).to_s(2).rjust(8,'0') # => "10011100"
+0b10010011.lrot8(4).to_s(2).rjust(8,'0') # => "00111001"
+0b10010011.lrot8(5).to_s(2).rjust(8,'0') # => "01110010"
+0b10010011.lrot8(6).to_s(2).rjust(8,'0') # => "11100100"
+```
+
+8/16/32/64 bit variants are available.
+
+### Reversing bytes
+
+```ruby
+0x11223344.bswap16.to_s(16) # => "11224433"
+0x11223344.bswap32.to_s(16) # => "44332211"
+0x11223344.bswap64.to_s(16) # => "4433221100000000"
+```
+
+### Reversing bits
+
+```ruby
+0b10010011.bitreverse8.to_s(2) # => "11001001"
+```
+
+8/16/32/64 bit variants are available.
+
+### "Arithmetic" right bitshift
+
+An arithmetic right shift fills the vacated bit positions with copies of the most-significant (or "sign") bit. In contrast, Ruby's `Integer#>>` is a "logical" right shift -- it fills the vacated bit positions with zeroes.
+
+```ruby
+0b10001111.arith_rshift8(3).to_s(2).rjust(8,'0') # => "11110001"
+0b00001111.arith_rshift8(3).to_s(2).rjust(8,'0') # => "00000001"
+```
+
+8/16/32/64 bit variants are available.
+
+### Logical left and right bitshifts
+
+Ruby already provides `Integer#<<` and `#>>`, which perform logical left and right bitshifts, so these are less useful than the other `BitTwiddle` methods. Probably the only reason to use them is if you want to explicitly operate on the low 8/16/32/64 bits:
+
+```ruby
+0b10001111.rshift8(3).to_s(2).rjust(8,'0') # => "01000111"
+0b10001111.lshift8(2).to_s(2).rjust(8,'0') # => "00111100"
+```
+
+8/16/32/64 bit variants are available.
+
+## Detailed documentation
+
+Clone yourself up a copy of this repo, then generate some local HTML documentation (with examples for each and every method):
+
+```
+git clone https://github.com/alexdowad/bit-twiddle.git
+cd bit-twiddle
+bundle install
+rake yard
+```

data/ext/bit_twiddle/extconf.rb

@@ -0,0 +1,31 @@
+require 'mkmf'
+
+dir = File.dirname(__FILE__)
+
+$CFLAGS << ' -Wall -Werror -O3 -march=native -mtune=native '
+
+if RUBY_VERSION < '2.2.0'
+  check_sizeof 'BDIGIT'
+  $CFLAGS << " -I#{File.join(dir, 'ruby21')} "
+else
+  $CFLAGS << " -I#{File.join(dir, 'ruby22')} "
+end
+
+check_sizeof 'short'
+check_sizeof 'int'
+check_sizeof 'long'
+check_sizeof 'long long'
+
+checking_for("whether >> on a signed long is arithmetic shift or logical shift", "%s") do
+  is_arith = try_static_assert("(-1L >> (sizeof(long)/8)) == -1L")
+  $defs.push("-DRSHIFT_IS_ARITH=#{is_arith ? '1' : '0'}")
+  is_arith ? "arithmetic" : "logical"
+end
+
+checking_for("presence of __builtin_bswap16", "%s") do
+  have_bswap16 = try_static_assert("__builtin_bswap16(0xAABB) == 0xBBAA")
+  $defs.push("-DHAVE_BSWAP16=#{have_bswap16 ? '1' : '0'}")
+  have_bswap16 ? "oh yeah" : "nope...but we can sure fix that"
+end
+
+create_makefile 'bit_twiddle'

data/lib/bit-twiddle.rb

@@ -1 +1 @@
-require 'bit_twiddling' # C extension
+require 'bit_twiddle' # C extension

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bit-twiddle
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Alex Dowad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-29 00:00:00.000000000 Z
+date: 2015-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -66,19 +66,33 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: Fast (native) bitwise operations for Ruby, in addition to the ones provided
   by the standard library
 email: alexinbeijing@gmail.com
 executables: []
 extensions:
-- ext/bit_twiddling/extconf.rb
+- ext/bit_twiddle/extconf.rb
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- ext/bit_twiddling/extconf.rb
+- ext/bit_twiddle/extconf.rb
 - lib/bit-twiddle.rb
-- lib/bit_twiddling.so
+- lib/bit_twiddle.so
 homepage: http://github.com/alexdowad/bit-twiddle
 licenses:
 - None (Public Domain)
@@ -99,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Fast bitwise operations for Ruby

data/ext/bit_twiddling/extconf.rb

@@ -1,6 +0,0 @@
-require 'mkmf'
-$CFLAGS << ' -Wall -Werror -O3 -march=native -mtune=native '
-check_sizeof 'BDIGIT'
-check_sizeof 'int'
-check_sizeof 'long'
-create_makefile 'bit_twiddling/bit_twiddling'