PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.3
Prev | Chapter 4. Library Reference | Next

# 4.13. The VLArray class

Instances of this class represents array objects in the object tree with the property that their rows can have a variable number of (homogeneous) elements (called atomic objects, or just atoms). Variable length arrays (or VLA's for short), similarly to `Table` instances, can have only one dimension, and likewise `Table`, the compound elements (the atoms) of the rows of `VLArrays` can be fully multidimensional objects.

`VLArray` provides methods to read/write data from/to variable length array objects residents on disk. Also, note that this object inherits all the public attributes and methods that `Leaf` already has.

## 4.13.1. VLArray instance variables

atom

  An `Atom` (see 4.16.3) instance representing the shape, type and flavor of the atomic objects to be saved.

nrow

  On iterators, this is the index of the current row.

nrows

  The total number of rows.

## 4.13.2. VLArray methods

### 4.13.2.1. getEnum()

Get the enumerated type associated with this array.

If this array is of an enumerated type, the corresponding `Enum` instance (see 4.17.4) is returned. If it is not of an enumerated type, a `TypeError` is raised.

### 4.13.2.2. append(sequence, *objects)

Append objects in the `sequence` to the array.

This method appends the objects in the `sequence` to a single row in this array. The type of individual objects must be compliant with the type of atoms in the array. In the case of variable length strings, the very string to append is the `sequence`.

Example of use (code available in `examples/vlarray1.py`):

    import tables
    from numpy import *   # or, from numarray import *

    # Create a VLArray:
    fileh = tables.openFile("vlarray1.h5", mode = "w")
    vlarray = fileh.createVLArray(fileh.root, 'vlarray1',
    tables.Int32Atom(flavor="numpy"),
                     "ragged array of ints", Filters(complevel=1))
    # Append some (variable length) rows:
    vlarray.append(array([5, 6]))
    vlarray.append(array([5, 6, 7]))
    vlarray.append([5, 6, 9, 8])

    # Now, read it through an iterator:
    for x in vlarray:
        print vlarray.name+"["+str(vlarray.nrow)+"]-->", x

    # Close the file
    fileh.close()

The output of the previous program looks like this:

    vlarray1[0]--> [5 6]
    vlarray1[1]--> [5 6 7]
    vlarray1[2]--> [5 6 9 8]

The `objects` argument is only retained for backwards compatibility; please do not use it.

### 4.13.2.3. iterrows(start=None, stop=None, step=1)

Returns an iterator yielding one row per iteration. If a range is supplied (i.e. some of the start, stop or step parameters are passed), only the appropriate rows are returned. Else, all the rows are returned. See also the `__iter__()` special methods in section 4.13.3 for a shorter way to call this iterator.

The meaning of the start, stop and step parameters is the same as in the `range()` python function, except that negative values of `step` are not allowed. Moreover, if only `start` is specified, then `stop` will be set to `start+1`. If you do not specify neither start nor stop, then all the rows in the object are selected.

Example of use:

    		for row in vlarray.iterrows(step=4):
    		print vlarray.name+"["+str(vlarray.nrow)+"]-->", row

### 4.13.2.4. read(start=None, stop=None, step=1)

Returns the actual data in `VLArray`. As the lengths of the different rows are variable, the returned value is a python list, with as many entries as specified rows in the range parameters.

The meaning of the start, stop and step parameters is the same as in the `range()` python function, except that negative values of `step` are not allowed. Moreover, if only `start` is specified, then `stop` will be set to `start+1`. If you do not specify neither start nor stop, then all the rows in the object are selected.

## 4.13.3. VLArray special methods

Following are described the methods that automatically trigger actions when a `VLArray` instance is accessed in a special way (e.g., `vlarray[2:5]` will be equivalent to a call to `vlarray.__getitem__(slice(2,5,None)`).

### 4.13.3.1. __iter__()

It returns the same iterator than `VLArray.iterrows(0,0,1)`. However, this does not accept parameters.

Example of use:

    		result = [ row for row in vlarray ]

Which is equivalent to:

    		result = [ row for row in vlarray.iterrows() ]

### 4.13.3.2. __getitem__(key)

It returns the slice of rows determined by `key`, which can be an integer index or an extended slice. The returned value is a list of objects of type `array.atom.type`.

Example of use:

    		list1 = vlarray[4]
    		list2 = vlarray[4:1000:2]

### 4.13.3.3. __setitem__(keys, value)

Updates a vlarray row described by `keys` by setting it to `value`. Depending on the value of `keys`, the action taken is different:

`keys` is an integer:

  It refers to the number of row to be modified. The `value` object must be type and shape compatible with the object that exists in the vlarray row.

`keys` is a tuple:

  The first element refers to the row to be modified, and the second element to the range (so, it can be an integer or an slice) of the row that will be updated. As above, the `value` object must be type and shape compatible with the object specified in the vlarray row and range.

Note: When updating `VLStrings` (codification UTF-8) or `Objects` atoms, there is a problem: one can only update values with exactly the same bytes than in the original row. With UTF-8 encoding this is problematic because, for instance, '`c`' takes 1 byte, but '`ç`' takes two. The same applies when using `Objects` atoms, because when cPickle applies to a class instance (for example), it does not guarantee to return the same number of bytes than over other instance, even of the same class than the former. These facts effectively limit the number of objects than can be updated in `VLArray`s.

Example of use:

    		vlarray[0] = vlarray[0]*2+3
    		vlarray[99,3:] = arange(96)*2+3
    		# Negative values for start and stop (but not step) are supported
    		vlarray[99,-99:-89:2] = vlarray[5]*2+3

Prev | Home | Next
The EArray class | Up | The UnImplemented class