This is version 0.98, a pre-release version of this software. No known bugs remain! Function names are changing. Currently, this module provides functions: bit(x, n), lsb(x), msb(x), bitcount(x), and extract(x, lo, hi). The old names lsbitno and msbitno remain as synonyms for lsb and msb respectively in this version only (the tests need to be updated). There is a suggestion that lsbit and msbit be be the names rather than lsb and msb, so those two names are available as well. If you care about the name, send me an e-mail quickly.
For the functions in this module, identical numbers in different formats (long, int, and float) should produce identical results. Since the results are invariably integral (int or long), and there is no integral imaginary data type, complex args are not allowed. These functions operate as if the numbers are represented as two's complement representation. -5.125 would be: ...1111111111010.111000000.... Bitcount is most likely useful mostly for counting bits when a bit is a flag, and should only be used on non-negative numbers. As you can see, negative numbers would have an infinite number of one bits. In order to provide a slightly more useful result, bitcount takes the absolute value of its argument.
b = bit(x, n) The value of bit number n in x (0 or 1). Bit zero is the low order bit of an integer (bit(1,0) ==1). Bit one is the 2's digit (bit(2,1)==1), and so on. Negative numbers are represented in two's complement. bit(0, n) is 0. All bits above the msb match the sign bit (1 for negative, 0 otherwise). All bits below the lsb are 0, and the lsb itself is 1. If lsb(x) < n, bit(x, n) == 1 - bit(-x, n). Raises ValueError if x is a floating point NaN or Inf -- the bits of such values are undefined. For types other than int, long, and float, this function raises a TypeError exception.
n = msb(x) Bit number of the most significant one bit of abs(x). Raises ValueError if x is 0, 0.0, or 0L (since there are no one bits). Also raises ValueError if x is a floating point NaN or a floating point infinity -- the bits of such values are not well defined. For types other than int, long, and float, this function raises a TypeError exception. msb(x) is the largest N such that 2**N <= abs(x); msb(1)==0. Obviously, only floating point values will yield negative results for msb.
n = lsb(x) Bit number of the least significant one bit of x. The least n where bit(x, n) == 1 is lsb(x). Raises ValueError if x is 0, 0.0, or 0L (since there are no one bits). Also raises ValueError if x is a floating point NaN or a floating point infinity -- the bits of such values are not well defined. For types other than int, long, and float, this function raises a TypeError exception. For integers, either lsb(n) or lsb(n+1) is 0. Obviously, only floating point values will yield negative results for lsb.
n = bitcount(x) Number of one bits in abs(x) (often called popcount, but popcount is different for negative numbers). Bits in the mantissa are the only bits considered for floats. Raises ValueError if x is a floating point NaN or a floating point infinity -- the bits of such values are sort of undefined. For types other than int, long, float, str, and unicode, this function raises a TypeError exception. The string types are provided since bitcount(struct.pack(...)) may be useful. Similar definitions for msb or lsb would require consensus on which bit is the "least" bit. bitcount(x) == sum([bit(abs(x), n) for n in range(lsb(x), msb(x+1))])
integer = extract(x, lo, hi) The bits from lo through hi-1 are combined in a single integer (int or long). If lo > hi, a ValueError exception is raised. If lo <= hi, the results are equivalent to: sum([bit(x, n) * 2**(n-lo) for n in range(lo, hi)])
Here are a few identities (when overflow doesn't cause problems):
Download links: