# 3. Classes

## 3.1. Available Classes

There are two fundamental classes available, the `Bit` and the `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:

NIST | SI
--- | ---
`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)`

Note

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 Table of Supported Operations and Appendix: Rules for Math for more details.

## 3.2. Initializing

class bitmath.Bit([value=0[, bytes=None[, bits=None]]])

class bitmath.Byte([value=0[, bytes=None[, bits=None]]])

class bitmath.EB([value=0[, bytes=None[, bits=None]]])

class bitmath.Eb([value=0[, bytes=None[, bits=None]]])

class bitmath.EiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Eib([value=0[, bytes=None[, bits=None]]])

class bitmath.GB([value=0[, bytes=None[, bits=None]]])

class bitmath.Gb([value=0[, bytes=None[, bits=None]]])

class bitmath.GiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Gib([value=0[, bytes=None[, bits=None]]])

class bitmath.kB([value=0[, bytes=None[, bits=None]]])

class bitmath.kb([value=0[, bytes=None[, bits=None]]])

class bitmath.KiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Kib([value=0[, bytes=None[, bits=None]]])

class bitmath.MB([value=0[, bytes=None[, bits=None]]])

class bitmath.Mb([value=0[, bytes=None[, bits=None]]])

class bitmath.MiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Mib([value=0[, bytes=None[, bits=None]]])

class bitmath.PB([value=0[, bytes=None[, bits=None]]])

class bitmath.Pb([value=0[, bytes=None[, bits=None]]])

class bitmath.PiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Pib([value=0[, bytes=None[, bits=None]]])

class bitmath.TB([value=0[, bytes=None[, bits=None]]])

class bitmath.Tb([value=0[, bytes=None[, bits=None]]])

class bitmath.TiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Tib([value=0[, bytes=None[, bits=None]]])

class bitmath.YB([value=0[, bytes=None[, bits=None]]])

class bitmath.Yb([value=0[, bytes=None[, bits=None]]])

class bitmath.ZB([value=0[, bytes=None[, bits=None]]])

class bitmath.Zb([value=0[, bytes=None[, bits=None]]])

class bitmath.Bitmath([value=0[, bytes=None[, bits=None]]])

  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.

  Parameters:

    - value (int) – 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)`.

    - bytes (int) – The value of the instance as measured in bytes.

    - bits (int) – 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.

     1>>> import bitmath
     2
     3# Omitting all keyword arguments defaults to 'value' behavior.
     4>>> a = bitmath.KiB(1)
     5
     6# This is equivalent to the previous statement
     7>>> b = bitmath.KiB(value=1)
     8
     9# We can also specify the initial value in bytes.
    10# Recall, 1KiB = 1024 bytes
    11>>> c = bitmath.KiB(bytes=1024)
    12
    13# Finally, we can specify exact number of bits in the
    14# instance. Recall, 1024B = 8192b
    15>>> d = bitmath.KiB(bits=8192)
    16
    17>>> a == b == c == d
    18True

## 3.3. Class Methods

### 3.3.1. Class Method: from_other()

bitmath class objects have one public class method, `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.

  Parameters:

    item (BitMathInstance) – An instance of a bitmath class.

  Returns:

    a bitmath instance of type `BitMathClass` equivalent in value to `item`

  Return type:

    BitMathClass

  Raises:

    TypeError – if `item` is not a valid bitmath class

  In pure Python, this could also be written as:

       1>>> import bitmath
       2
       3>>> a_mebibyte = bitmath.MiB(1)
       4
       5>>> a_mebibyte_sized_kibibyte = bitmath.KiB(bytes=a_mebibyte.bytes)
       6
       7>>> a_mebibyte == a_mebibyte_sized_kibibyte
       8True
       9
      10>>> print a_mebibyte, a_mebibyte_sized_kibibyte
      111.0 MiB 1024.0 KiB

  Or, using the `BitMathClass.from_other()` class method:

      1>>> a_mebibyte = bitmath.MiB(1)
      2
      3>>> a_big_kibibyte = bitmath.KiB.from_other(a_mebibyte)
      4
      5>>> a_mebibyte == a_big_kibibyte
      6True
      7
      8>>> print a_mebibyte, a_big_kibibyte
      91.0 MiB 1024.0 KiB