API Reference

This reference guide is mostly built from the documentation strings in the library, but some introductory notes are also included in each section.

For a more structured introduction to the library see the Tour of bitformat.

The Basics

The Bits and Dtype classes are the most fundamental ones to use and understand.

• Bits – An immutable container for storing binary data.

• MutableBits – A mutable version of Bits.

• Dtype – An abstract base class for data types used to interpret binary data.

• DtypeSingle – A Dtype representing a single value.

• DtypeArray – A Dtype representing a sequence of objects of the same type.

• DtypeTuple – A Dtype representing a sequence of objects of different types.

• Array – A mutable container for contiguously allocated objects with the same Dtype.

• Reader – Read and parse Bits as a bit stream with a bit position.

        ---
title: Basic bitformat classes
config:
    class:
        hideEmptyMembersBox: true
---
classDiagram
    direction BT
    class MutableBits {
        + append()
        + byte_swap()
        + replace()
        + ...()
    }
    class Bits {
        + from_string()
        + from_dtype()
        + from_bytes()
        + ...()
        + count()
        + find()
        + to_bytes()
        + unpack()
        + ...()
    }
    class Reader {
        + Bits bits
        + int pos
        + read()
        + peek()
        + parse()
    }
    Reader --* "1" Bits : contains
    MutableBits --* Bits : extends
    

        ---
title: Dtypes and Array
config:
    class:
        hideEmptyMembersBox: true
---
classDiagram
    direction BT
    class MutableBits
    class Array {
        + int item_size
        + Dtype dtype
        + MutableBits data
        + from_iterable()
        + from_bytes()
        + ...()
        + append()
        + as_type()
        + to_bytes()
        + unpack()
        + ...()
    }
    class Dtype {
        <<abstract>>
        + from_string()
        + from_params()
        + pack()
        + unpack()
    }
    class DtypeSingle {
        + DtypeKind kind
        + Endianness endianness
        + int size
    }
    class DtypeArray {
        + DtypeKind kind
        + Endianness endianness
        + int size
        + int items
    }
    class DtypeTuple {
        + List[Dtype] dtypes
    }
    DtypeSingle --|> Dtype
    DtypeArray --|> Dtype
    DtypeTuple --|> Dtype
    Array --* "1" Dtype : contains
    Array --* "1" MutableBits : contains
    

Field Types

These classes build upon those above to provide richer and more complex data structures.

• FieldType – The abstract base class for the other classes in this section.

• Format – A sequence of FieldType objects, such as Field or other Format instances.

• Field – A well-defined amount of binary data with a single data type, and optionally a name.

• If – A pair of FieldType obejcts, one of which is selected based on a condition.

• Repeat – Used to repeat another FieldType a number of times.

• Let - Creates or modifies a variable using an Expression.

• Pass – An empty FieldType used as a placeholder.

        ---
title: Field types
config:
    class:
        hideEmptyMembersBox: true
---
classDiagram
    direction BT
    class Bits
    class Dtype
    class FieldType{
        <<abstract>>
        + str name
    }
    class Field{
        + Dtype dtype
    }
    class If{
        + Expression condition
        + FieldType then_
        + FieldType else_
    }
    class Repeat{
        + int n
        + FieldType field
    }
    class Format{
        + List[FieldType] fields
    }
    Field --|> FieldType
    Format --|> FieldType
    If --|> FieldType
    Repeat --|> FieldType
    Field --* "1" Dtype : contains
    Field --* "0..1" Bits : contains
    

Miscellaneous

Other classes and enums are listed here. Some of the more important ones are:

• Expression – Use Field values elsewhere for conditionals and other logic.

• Options – Getting and setting module-wide options.

---