Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
221 lines (168 sloc) 7.26 KB
.. currentmodule:: bitmath


Available Classes

There are two fundamental classes available, the :class:`Bit` and the :class:`Byte`.

There are 24 other classes available, representing all the prefix units from k through e (kilo/kibi through exa/exbi).

Classes with 'i' in their names are NIST type classes. They were defined by the National Institute of Standards and Technology (NIST) as the 'Binary Prefix Units'. They are defined by increasing powers of 2.

Classes without the 'i' character are SI type classes. Though not formally defined by any standards organization, they follow the International System of Units (SI) pattern (commonly used to abbreviate base 10 values). You may hear these referred to as the "Decimal" or "SI" prefixes.

Classes ending with lower-case 'b' characters are bit based. Classes ending with upper-case 'B' characters are byte based. Class inheritance is shown below in parentheses to make this more apparent:

Eib(Bit) Eb(Bit)
EiB(Byte) EB(Byte)
Gib(Bit) Gb(Bit)
GiB(Byte) GB(Byte)
Kib(Bit) kb(Bit)
KiB(Byte) kB(Byte)
Mib(Bit) Mb(Bit)
MiB(Byte) MB(Byte)
Pib(Bit) Pb(Bit)
PiB(Byte) PB(Byte)
Tib(Bit) Tb(Bit)
TiB(Byte) TB(Byte)


As per SI definition, the kB and kb classes begins with a lower-case k character.

The majority of the functionality of bitmath object comes from their rich implementation of standard Python operations. You can use bitmath objects in almost all of the places you would normally use an integer or a float. See the :ref:`Table of Supported Operations <simple_examples_supported_operations>` and :ref:`Appendix: Rules for Math <appendix_math>` for more details.


The value, bytes, and bits parameters are mutually exclusive. That is to say, you cannot instantiate a bitmath class using more than one of the parameters. Omitting any keyword argument defaults to behaving as if value was provided.

param int value:Default: 0. The value of the instance in prefix units. For example, if we were instantiating a bitmath.KiB object to represent 13.37 KiB, the value parameter would be 13.37. For instance, k = bitmath.KiB(13.37).
param int bytes:The value of the instance as measured in bytes.
param int bits:The value of the instance as measured in bits.
raises ValueError:if more than one parameter is provided.

The following code block demonstrates the 4 acceptable ways to instantiate a bitmath class.

Class Methods

Class Method: from_other()

bitmath class objects have one public class method, :py:meth:`BitMathClass.from_other` which provides an alternative way to initialize a bitmath class.

This method may be called on bitmath class objects directly. That is to say: you do not need to call this method on an instance of a bitmath class, however that is a valid use case.

.. classmethod:: Byte.from_other(item)

   Instantiate any ``BitMathClass`` using another instance as
   reference for it's initial value.

   The ``from_other()`` class method has one required parameter: an
   instance of a bitmath class.

   :param BitMathInstance item: An instance of a bitmath class.
   :return: a bitmath instance of type ``BitMathClass`` equivalent in
            value to ``item``
   :rtype: BitMathClass
   :raises TypeError: if ``item`` is not a valid :ref:`bitmath class

   In pure Python, this could also be written as:

   .. code-block:: python
      :emphasize-lines: 3

      >>> import bitmath

      >>> a_mebibyte = bitmath.MiB(1)

      >>> a_mebibyte_sized_kibibyte = bitmath.KiB(bytes=a_mebibyte.bytes)

      >>> a_mebibyte == a_mebibyte_sized_kibibyte

      >>> print a_mebibyte, a_mebibyte_sized_kibibyte
      1.0 MiB 1024.0 KiB

   Or, using the :py:meth:`BitMathClass.from_other` class method:

   .. code-block:: python

      >>> a_mebibyte = bitmath.MiB(1)

      >>> a_big_kibibyte = bitmath.KiB.from_other(a_mebibyte)

      >>> a_mebibyte == a_big_kibibyte

      >>> print a_mebibyte, a_big_kibibyte
      1.0 MiB 1024.0 KiB
You can’t perform that action at this time.