Documentation Index | From module structarray.

StructArray

StructArray(attributes, [initial_data, swizzles, size, defaults])

StructArray provides an array of structred data.

attributes the list of attribute names. e.g., ('x', 'y', 'dx', 'dy') An Array will be created for each of these.

initial_data is a list of tuples to fill the array with.

swizzles provides shortcuts for accessing multiple attributes at a time. (This is currently not implemented.)

size is the initial length of the array. If size is longer than initial_data, the remaining items will be filled in by defaults. If if initial_data is longer than size, it's length will be used instead.

If size is a tuple with more than one item, the array will be multidimensional. See the documentation for the structarray module for more on multidimensional arrays.

defaults is a tuple of default values for the items. (One value corresponding to each attribute.) This is used both for initially creating the array, and when set_length() is called.

Item access on a StructArray returns an item object, which has attributes corresponding to the attributes of the StructArray.

This might make it clearer:

>>> particles = StructArray(('x', 'y', 'dx', 'dy'), size=10)
>>> p = particles[1]
>>> print p
<item at index 1 (0.0, 0.0, 0.0, 0.0)>
>>> p.x, p.y = 0, 100
>>> p.dx, p.dy = 0, 5
>>> print particles[0]
<item at index 1 (0.0, 100.0, 0.0, 5.0)>

Additionally, an array is created for each attribute, allowing you to work with the value of that attribute for all of the items:

>>> print particles.y
<OffsetArray [0.0, 100.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]>

(OffsetArray is simply a subclass of Array that stores it's data at an offset inside of another array. It works just like Array, only you can't change the length.)

Assigning to an attribute will do the 'right thing':

>>> particles.dx = 6.5
>>> particles.x += particles.dx*2
>>> print particles[1]
<item at index 1 (13.0, 100.0, 6.5, 5.0)>

You can also assign a tuple to an item:

>>> particles[2] = (15, 20, 0, 100)
>>> print particles[2]
<item at index 2 (15.0, 20.0, 0.0, 100.0)>

When assigning a tuple, you can ommit some values, leaving them as they are:

>>> particles[2] = (100, 200)
>>> print particles[2]
<item at index 2 (100.0, 200.0, 0.0, 100.0)>

Methods

append

append(item)

Appends an item to the array.

extend

extend(items)

Iterates over items, calling append() on each one.

get_data_addr

get_data_addr()

Gets the memory address of the data.

This, together with get_data_stride(), can be used with PyOpenGL or Pyglet for OpenGL vertex arrays. For example:

>>> array = StructArray(("x", "y"), size=100, defaults=(0,0))
>>> glVertexPointer(2, GL_FLOAT,
...     array.get_data_stride(),
...     array.get_data_addr())

get_data_stride

get_data_stride()

Gets the number of bytes between the begining of each array element.

get_dimensions

get_size()

Returns a tuple of this array's dimensional size.

If it is a single dimension array, a tuple containing the length will be returned.

sanitize_index

sanitize_index(index) -> sanitized index

This method takes an index, such as passed to __getitem__, and returns an index that is between 0 and len(self). (So that it can be used with the underlying C array.) This includes handling negitive and/or multidimensional indexes.

Slices are currently not supported.

set_length

set_length(length)

Sets the length explicitly.

This is an alternative to using append and extend. (It should be a little faster.)