1.1. Defining Structs#

Structs are at the heart of this library, and understanding how to define and use them is key to leveraging the full power of Caterpillar. In this section, we’ll begin by defining a simple struct for the PLTE chunk of a PNG file, which consists of three-byte entries.

RGB struct for the PLTE chunk#
from caterpillar.py import * # <-- just import everything

@struct         # <-- just decorate the class with the struct() function
class RGB:
    r: uint8    # <-- a field can be defined just like this
    g: uint8
    b: uint8
RGB struct for the PLTE chunk (using Caterpillar C)#
from caterpillar.c import * # <-- just import everything

@struct         # <-- just decorate the class with the struct() function
class RGB:
    r: u8       # <-- a field can be defined just like this
    g: u8
    b: u8

By using the @struct decorator, we’ve defined the RGB class as a struct. This simple annotation turns the class into a structured representation of the data. Once defined, you can easily instantiate objects of the RGB class and assign values to its fields:

>>> obj = RGB(1, 2, 3)

At this point, the RGB class is ready to be used as part of larger struct definitions or on its own.

Tip

If you’re working with large numbers of instances or require fast attribute access, you can optimize the memory usage and speed by enabling the S_SLOTS option. This reduces the overhead of using dictionaries for attribute storage. For more details on how to enable this option, refer to the documentation on Options.

Thats it? That was less than expected? Let’s move directly to working with the defined class.

This Page