Fetching contributors…
Cannot retrieve contributors at this time
211 lines (156 sloc) 8.34 KB

Getting Started

In this section we will take a high-level look at the basic things you can do with bitmath. We'll include the following topics:

Tables of Supported Operations

The following legend describes the two operands used in the tables below.

Operand Description
bm A bitmath object is required
num An integer or decimal value is required


Math works mostly like you expect it to, except for a few edge-cases:

  • Mixing bitmath types with Number types (the result varies per-operation)
  • Operations where two bitmath types would cancel out (such as dividing two bitmath types)
  • Multiplying two bitmath instances together is supported, but the results may not make much sense.
.. seealso::

   :ref:`Appendix: Rules for Math <appendix_math>`
      For a discussion of the behavior of bitmath and number types.

Operation Parameters Result Type Example
Addition bm1 + bm2 type(bm1) KiB(1) + MiB(2) = 2049.0KiB
Addition bm + num type(num) KiB(1) + 1 = 2.0
Addition num + bm type(num) 1 + KiB(1) = 2.0
Subtraction bm1 - bm2 type(bm1) KiB(1) - Byte(2048) = -1.0KiB
Subtraction bm - num type(num) KiB(4) - 1 = 3.0
Subtraction num - bm type(num) 10 - KiB(1) = 9.0
Multiplication bm1 * bm2 type(bm1) KiB(1) * KiB(2) = 2048.0KiB
Multiplication bm * num type(bm) KiB(2) * 3 = 6.0KiB
Multiplication num * bm type(bm) 2 * KiB(3) = 6.0KiB
Division bm1 / bm2 type(num) KiB(1) / KiB(2) = 0.5
Division bm / num type(bm) KiB(1) / 3 = 0.3330078125KiB
Division num / bm type(num) 3 / KiB(2) = 1.5

Bitwise Operations

.. seealso::

   `Bitwise Calculator <>`_
      A free online calculator for checking your math

Bitwise operations are also supported. Bitwise operations work directly on the bits attribute of a bitmath instance, not the number you see in an instances printed representation (value), to maintain accuracy.

Operation Parameters Result Type Example1
Left Shift bm << num type(bm) MiB(1) << 2 = MiB(4.0)
Right Shift bm >> num type(bm) MiB(1) >> 2 = MiB(0.25)
AND bm & num type(bm) MiB(13.37) & 1337 = MiB(0.000126...)
OR bm | num type(bm) MiB(13.37) | 1337 = MiB(13.3700...)
XOR bm ^ num type(bm) MiB(13.37) ^ 1337 = MiB(13.369...)
  1. Give me a break here, it's not easy coming up with compelling examples for bitwise operations...

Basic Math

bitmath supports all arithmetic operations

Unit Conversion

Rich Comparison

Rich Comparison (as per the Python Basic Customization magic methods) <, <=, ==, !=, >, >= is fully supported:


bitmath natively supports sorting.

Let's make a list of the size (in bytes) of all the files in the present working directory (lines 4 and 5) and then print them out sorted by increasing magnitude (lines 10 and 11, and 1315):

Now print them out in descending magnitude

>>> print sorted(human_sizes, reverse=True)
[KiB(7892.0), KiB(7337.0), KiB(4190.0), KiB(4003.0), KiB(2326.0), KiB(2178.0), KiB(2126.0), KiB(1770.0), KiB(1441.0), KiB(48.0)]