Compressed-Array C Bindings

zfp 0.5.4 adds cfp: C language bindings for compressed arrays via wrappers around the C++ classes. zfp 1.0.0 modifies its API (see below).

The C API has been designed to facilitate working with compressed arrays without the benefits of C++ operator overloading and self-aware objects, which greatly simplify the syntax. Whereas one possible design considered is to map each C++ method to a C function with a prefix, such as zfp_array3d_get(a, i, j, k) in place of a(i, j, k) for accessing an element of a 3D array of doubles, such code would quickly become unwieldy when part of longer expressions.

Instead, cfp uses the notion of nested C namespaces that are structs of function pointers, such as cfp.array3d. Although this may seem no more concise than a design based on prefixes, the user may alias these namespaces (somewhat similar to C++ using namespace declarations) using far shorter names via C macros or local variables. For instance:

const cfp_array3d_api _ = cfp.array3d; // _ is a namespace alias
cfp_array3d a = _.ctor(nx, ny, nz, rate, 0, 0);
double value = _.get(a, i, j, k);
_.set(a, i, j, k, value + 1);

which is a substitute for the C++ code

zfp::array3d a(nx, ny, nz, rate, 0, 0);
double value = a(i, j, k);
a(i, j, k) = value + 1;

Because the underlying C++ array objects have no corresponding C representation, and because C objects are not self aware (they have no implicit this pointer), the C interface interacts with compressed arrays through array object pointers, wrapped in structs, that cfp converts to pointers to the corresponding C++ objects. As a consequence, cfp compressed arrays must be allocated on the heap and must be explicitly freed via designated destructor functions to avoid memory leaks (this is not necessary for references, pointers, and iterators, which have their own C representation). The C++ constructors are mapped to C by allocating objects via C++ new. Moreover, the C API requires passing an array self pointer (wrapped within a cfp array struct) in order to manipulate the array.

As with the C++ classes, array elements can be accessed via multidimensional array indexing, e.g., get(array, i, j), and via flat, linear indexing, e.g., get_flat(array, i + nx * j).

Note

The cfp API changed in zfp 1.0.0 by wrapping array self pointers in structs to align the interface more closely with the C++ API and to avoid confusion when discussing arrays (now cfp.array rather than cfp.array*) and pointers to arrays (now cfp.array* rather than cfp.array**). Furthermore, zfp 1.0.0 adds support for proxy references, proxy pointers, and iterators that also wrap C++ classes. Manipulating those indirectly via pointers (like the old cfp arrays) would require additional user effort to destroy dynamically allocated lightweight objects and would also reduce code readability, e.g., cfp_ptr1d* (whose corresponding C++ type is zfp::array1d::pointer*) reads more naturally as a raw pointer to a proxy pointer than an indirectly referenced proxy pointer object that the user must remember to implicitly dereference.

The following sections are available:

Arrays

cfp implements eight array types for 1D, 2D, 3D, and 4D arrays of floats and doubles. These array types share many functions that have the same signature. To reduce redundancy in the documentation, we define fictitious types cfp_arrayf and cfp_arrayd for N-dimensional (1 ≤ N ≤ 4) arrays of floats or doubles, cfp_array1, cfp_array2, cfp_array3, and cfp_array4 for 1D, 2D, 3D, and 4D arrays of either floats or doubles, and cfp_array for arrays of any dimensionality and type. We also make use of corresponding namespaces, e.g., :c:struct:`cfp.array1` refers to the API common to one-dimensional arrays of floats or doubles. These types and namespaces are not actually part of the cfp API.

Note

The cfp array API makes use of const qualifiers for struct parameters (passed by value) merely to indicate when the corresponding object is not modified, e.g., const cfp_array1f self. This construction serves to document functions that are analogous to const qualified C++ member functions.

Note

Support for 4D arrays was added to cfp in version 1.0.0.

cfp_array1f
cfp_array1d
cfp_array2f
cfp_array2d
cfp_array3f
cfp_array3d
cfp_array4f
cfp_array4d

Opaque types for 1D, 2D, 3D, and 4D compressed arrays of floats and doubles.


cfp_array1
cfp_array2
cfp_array3
cfp_array4

Fictitious types denoting 1D, 2D, 3D, and 4D arrays of any scalar type.


cfp_arrayf
cfp_arrayd

Fictitious types denoting any-dimensional arrays of floats and doubles.


cfp_array

Fictitious type denoting array of any dimensionality and scalar type.



cfp_array1f cfp.array1f.ctor(size_t nx, double rate, const float* p, size_t cache_size)
cfp_array1d cfp.array1d.ctor(size_t nx, double rate, const double* p, size_t cache_size)
cfp_array2f cfp.array2f.ctor(size_t nx, size_t ny, double rate, const float* p, size_t cache_size)
cfp_array2d cfp.array2d.ctor(size_t nx, size_t ny, double rate, const double* p, size_t cache_size)
cfp_array3f cfp.array3f.ctor(size_t nx, size_t ny, size_t nz, double rate, const float* p, size_t cache_size)
cfp_array3d cfp.array3d.ctor(size_t nx, size_t ny, size_t nz, double rate, const double* p, size_t cache_size)
cfp_array4f cfp.array4f.ctor(size_t nx, size_t ny, size_t nz, size_t nw, double rate, const float* p, size_t cache_size)
cfp_array4d cfp.array4d.ctor(size_t nx, size_t ny, size_t nz, size_t nw, double rate, const double* p, size_t cache_size)

Array constructors. If p is not NULL, then the array is initialized from uncompressed storage; otherwise the array is zero initialized. cache_size is the minimum size cache (in bytes) to use. If cache_size is zero, a default size is chosen.


cfp_array cfp.array.ctor_default()

Default constructor. Allocate an empty array that later can be resized and whose rate and cache size can be set by cfp.array.set_rate() and cfp.array.set_cache_size().


cfp_array cfp.array.ctor_copy(const cfp_array src)

Copy constructor.


cfp_array cfp.array.ctor_header(const cfp_header h, const void* buffer, size_t buffer_size_bytes);

Constructor from metadata given by the header h and optionally initialized with compressed data from buffer of size buffer_size_bytes. See corresponding C++ constructor.


void cfp.array.dtor(cfp_array self)

Destructor. The destructor not only deallocates any compressed data owned by the array, but also frees memory for itself, invalidating the self object upon return. Note that the user must explicitly call the destructor to avoid memory leaks.


void cfp.array.deep_copy(cfp_array self, const cfp_array src)

Perform a deep copy of src analogous to the C++ assignment operator.


float cfp.array1f.get(const cfp_array1f self, size_t i)
float cfp.array2f.get(const cfp_array2f self, size_t i, size_t j)
float cfp.array3f.get(const cfp_array3f self, size_t i, size_t j, size_t k)
float cfp.array4f.get(const cfp_array4f self, size_t i, size_t j, size_t k, size_t l)
double cfp.array1d.get(const cfp_array1d self, size_t i)
double cfp.array2d.get(const cfp_array2d self, size_t i, size_t j)
double cfp.array3d.get(const cfp_array3d self, size_t i, size_t j, size_t k)
double cfp.array4d.get(const cfp_array4d self, size_t i, size_t j, size_t k, size_t l)

Array inspectors via multidimensional indexing.


void cfp.array1f.set(const cfp_array1f self, size_t i, float val)
void cfp.array2f.set(const cfp_array2f self, size_t i, size_t j, float val)
void cfp.array3f.set(const cfp_array3f self, size_t i, size_t j, size_t k, float val)
void cfp.array4f.set(const cfp_array4f self, size_t i, size_t j, size_t k, size_t l, float val)
void cfp.array1d.set(const cfp_array1d self, size_t i, double val)
void cfp.array2d.set(const cfp_array2d self, size_t i, size_t j, double val)
void cfp.array3d.set(const cfp_array3d self, size_t i, size_t j, size_t k, double val)
void cfp.array4d.set(const cfp_array4d self, size_t i, size_t j, size_t k, size_t l, double val)

Array mutators for assigning values to array elements via multidimensional indexing.


float cfp.arrayf.get_flat(const cfp_arrayf self, size_t index)
double cfp.arrayd.get_flat(const cfp_arrayd self, size_t index)

Flat index array inspectors; see array::operator[]().


void cfp.arrayf.set_flat(cfp_arrayf self, size_t index, float val)
void cfp.arrayd.set_flat(cfp_arrayd self, size_t index, double val)

Flat index array mutators; set array element with flat index to val.


void cfp.arrayf.get_array(const cfp_arrayf self, float* p)
void cfp.arrayd.get_array(const cfp_arrayd self, double* p)

Decompress entire array; see array::get().


void cfp.arrayf.set_array(cfp_arrayf self, const float* p)
void cfp.arrayd.set_array(cfp_arrayd self, const double* p)

Initialize entire array; see array::set().


size_t cfp.array2.size_x(const cfp_array2 self)
size_t cfp.array2.size_y(const cfp_array2 self)
size_t cfp.array3.size_x(const cfp_array3 self)
size_t cfp.array3.size_y(const cfp_array3 self)
size_t cfp.array3.size_z(const cfp_array3 self)
size_t cfp.array4.size_x(const cfp_array4 self)
size_t cfp.array4.size_y(const cfp_array4 self)
size_t cfp.array4.size_z(const cfp_array4 self)
size_t cfp.array4.size_w(const cfp_array4 self)

Array dimensions.


size_t cfp.array.size(const cfp_array self)

See array::size().


void cfp.array1.resize(cfp_array1 self, size_t n, zfp_bool clear)
void cfp.array2.resize(cfp_array2 self, size_t nx, size_t ny, zfp_bool clear)
void cfp.array3.resize(cfp_array3 self, size_t nx, size_t ny, size_t nz, zfp_bool clear)
void cfp.array4.resize(cfp_array4 self, size_t nx, size_t ny, size_t nz, size_t nw, zfp_bool clear)

Resize array.


double cfp.array.rate(const cfp_array self)

See array::rate().


double cfp.array.set_rate(cfp_array self, double rate)

See array::set_rate().


size_t cfp.array.cache_size(const cfp_array self)

See array::cache_size().


void cfp.array.set_cache_size(cfp_array self, size_t cache_size)

See array::set_cache_size().


void cfp.array.clear_cache(const cfp_array self)

See array::clear_cache().


void cfp.array.flush_cache(const cfp_array self)

See array::flush_cache().


size_t cfp.array.size_bytes(const cfp_array self, uint mask)

See array::size_bytes().


size_t cfp.array.compressed_size(const cfp_array self)

See array::compressed_size().


void* cfp.array.compressed_data(const cfp_array self)

See array::compressed_data().


cfp_ref1 cfp.array1.ref(cfp_array1 self, size_t i)
cfp_ref2 cfp.array2.ref(cfp_array2 self, size_t i, size_t j)
cfp_ref3 cfp.array3.ref(cfp_array3 self, size_t i, size_t j, size_t k)
cfp_ref4 cfp.array4.ref(cfp_array4 self, size_t i, size_t j, size_t k, size_t l)

Reference constructor via multidimensional indexing.


cfp_ref cfp.array.ref_flat(cfp_array self, size_t i)

Reference constructor via flat indexing.


cfp_ptr1 cfp.array1.ptr(cfp_array1 self, size_t i)
cfp_ptr2 cfp.array2.ptr(cfp_array2 self, size_t i, size_t j)
cfp_ptr3 cfp.array3.ptr(cfp_array3 self, size_t i, size_t j, size_t k)
cfp_ptr4 cfp.array4.ptr(cfp_array4 self, size_t i, size_t j, size_t k, size_t l)

Obtain pointer to array element via multidimensional indexing.


cfp_ptr cfp.array.ptr_flat(cfp_array self, size_t i)

Obtain pointer to array element via flat indexing.


cfp_iter cfp.array.begin(cfp_array self)

Return iterator to beginning of array; see array::begin().


cfp_iter cfp.array.end(cfp_array self)

Return iterator to end of array; see array::end().

Serialization

zfp 1.0.0 adds cfp array serialization. Like zfp’s C++ arrays, cfp arrays can be serialized and deserialized to and from sequential storage. As with the C++ arrays, (de)serialization is done with the assistance of a header class, cfp_header. Currently, cfp provides no factory function—the caller must either know which type of array (dimensionality and scalar type) to construct at compile-time or obtain this information at run-time from a header constructed from a memory buffer.

Array Accessors

zfp 1.0.0 adds cfp support for proxy references and pointers to individual array elements, as well as iterators for traversing arrays. These are analogues to the corresponding C++ classes. As with arrays, fictitious types and namespaces are used to shorten the documentation.

Note

Unlike the case of arrays, for which the surrounding struct stores a pointer to the underlying array object to allow modifications of the array, the cfp proxy reference, proxy pointer, and iterator objects are all passed by value, and hence none of the functions below modify the self argument. To increment a pointer, for instance, one should call p = cfp.array.pointer.inc(p). Note that while the references, pointers, and iterators are not themselves modified, the array elements that they reference can be modified.

References

cfp proxy references wrap the C++ reference classes. References are constructed via cfp.array.ref(), cfp.array.pointer.ref(), and cfp.array.iterator.ref() (as well as associated ref_flat and ref_at calls).

Note

cfp references exist primarily to provide parity with zfp references. As references do not exist in C, the preferred way of accessing arrays is via proxy pointers, iterators, or index-based array accessors.

cfp references do provide the same guarantees as C++ references, functioning as aliases to initialized members of the cfp wrapped zfp array. This is with the caveat that they are only accessed via cfp API calls (use of the = C assignment operator to shallow copy a cfp_ref is also allowed in this case).

cfp_ref1f
cfp_ref2f
cfp_ref3f
cfp_ref4f
cfp_ref1d
cfp_ref2d
cfp_ref3d
cfp_ref4d

Opaque types for proxy references to 1D, 2D, 3D, and 4D compressed float or double array elements.


cfp_ref1
cfp_ref2
cfp_ref3
cfp_ref4

Fictitious types denoting references into 1D, 2D, 3D, and 4D arrays of any scalar type.


cfp_reff
cfp_refd

Fictitious types denoting references into float or double arrays of any dimensionality.


cfp_ref

Fictitious type denoting reference into array of any dimensionality and scalar type.


float cfp.arrayf.reference.get(const cfp_reff self)
double cfp.arrayd.reference.get(const cfp_refd self)

Retrieve value referenced by self.


void cfp.arrayf.reference.set(cfp_reff self, float val)
void cfp.arrayd.reference.set(cfp_refd self, double val)

Update value referenced by self; see reference::operator=().


cfp_ptr cfp.array.reference.ptr(cfp_ref self)

Obtain proxy pointer to value referenced by self; see reference::operator&().


void cfp.array.reference.copy(cfp_ref self, const cfp_ref src)

Copy value referenced by src to value referenced by self; see reference::operator=(). This performs a deep copy. This is in contrast to self = src, which performs only a shallow copy.

Pointers

cfp proxy pointers wrap the C++ pointer classes. Pointers are constructed via cfp.array.ptr() and cfp.array.reference.ptr() (and associated ptr_flat and ptr_at calls). All pointers are passed by value and are themselves not modified by these functions.

Note

As with array::pointer, cfp_ptr indexing is based on element-wise ordering and is unaware of zfp blocks. This may result in a suboptimal access pattern if sequentially accessing array members. To take advantage of zfp block traversal optimization, see iterators.

cfp_ptr1f
cfp_ptr2f
cfp_ptr3f
cfp_ptr4f
cfp_ptr1d
cfp_ptr2d
cfp_ptr3d
cfp_ptr4d

Opaque types for proxy pointers to 1D, 2D, 3D, and 4D compressed float or double array elements.


cfp_ptr1
cfp_ptr2
cfp_ptr3
cfp_ptr4

Fictitious types denoting pointers into 1D, 2D, 3D, and 4D arrays of any scalar type.


cfp_ptrf
cfp_ptrd

Fictitious types denoting pointers into float or double arrays of any dimensionality.


cfp_ptr

Fictitious type denoting pointer into array of any dimensionality and scalar type.


float cfp.arrayf.pointer.get(const cfp_ptrf self)
double cfp.arrayd.pointer.get(const cfp_ptrd self)

Dereference operator; *self. See pointer::operator*().


float cfp.arrayf.pointer.get_at(const cfp_ptrf self, ptrdiff_t d)
double cfp.arrayd.pointer.get_at(const cfp_ptrd self, ptrdiff_t d)

Offset dereference operator; self[d]. See pointer::operator[]().


void cfp.arrayf.pointer.set(cfp_ptrf self, float val)
void cfp.arrayd.pointer.set(cfp_ptrd self, double val)

Dereference operator with assignment; *self = val. See pointer::operator*().


void cfp.arrayf.pointer.set_at(cfp_ptrf self, ptrdiff_t d, float val)
void cfp.arrayd.pointer.set_at(cfp_ptrd self, ptrdiff_t d, double val)

Offset dereference operator with assignment; self[d] = val. See pointer::operator[]().


cfp_ref cfp.array.pointer.ref(cfp_ptr self)

Get proxy reference to element stored at *self. See pointer::operator*().


cfp_ref cfp.array.pointer.ref_at(cfp_ptr self, ptrdiff_t d)

Get proxy reference to element stored at self[d]. See pointer::operator[]().


zfp_bool cfp.array.pointer.lt(const cfp_ptr lhs, const cfp_ptr rhs)
zfp_bool cfp.array.pointer.gt(const cfp_ptr lhs, const cfp_ptr rhs)
zfp_bool cfp.array.pointer.leq(const cfp_ptr lhs, const cfp_ptr rhs)
zfp_bool cfp.array.pointer.geq(const cfp_ptr lhs, const cfp_ptr rhs)

Return true if the two pointers satisfy the given relationship; lhs < rhs, lhs > rhs, lhs <= rhs, lhs >= rhs.


zfp_bool cfp.array.pointer.eq(const cfp_ptr lhs, const cfp_ptr rhs)

Compare two proxy pointers for equality; lhs == rhs. The pointers must be to elements with the same index within the same array to satisfy equality. See pointer::operator==().


int cfp.array.pointer.neq(const cfp_ptr lhs, const cfp_ptr rhs)

Compare two proxy pointers for inequality; lhs != rhs. The pointers are not equal if they point to different arrays or to elements with different index within the same array. See pointer::operator!=().


ptrdiff_t cfp.array.pointer.distance(const cfp_ptr first, const cfp_ptr last)

Return the difference between two proxy pointers in number of linear array elements; last - first. See pointer::operator-().


cfp_ptr cfp.array.pointer.next(const cfp_ptr p, ptrdiff_t d)

Return the result of incrementing pointer by d elements; p + d. See pointer::operator+().


cfp_ptr cfp.array.pointer.prev(const cfp_ptr p, ptrdiff_t d)

Return the result of decrementing pointer by d elements; p - d. See pointer::operator-().


cfp_ptr cfp.array.pointer.inc(const cfp_ptr p)

Return the result of incrementing pointer by one element; p + 1. See pointer::operator++().


cfp_ptr cfp.array.pointer.dec(const cfp_ptr p)

Return the result of decrementing pointer by one element; p - 1. See pointer::operator--().

Iterators

cfp random-access iterators wrap the C++ iterator classes. All iterators are passed by value and are themselves not modified by these functions. Iterators are constructed similar to C++ iterators via cfp.array.begin() and cfp.array.end(). Iterator usage maps closely to equivalent C++ iterator syntax. For example, to set an array to all ones:

// _ and _iter are namespace aliases
const cfp_array3d_api _ = cfp.array3d;
const cfp_iter3d_api _iter = _.iterator;

cfp_array3d a = _.ctor(nx, ny, nz, rate, 0, 0);
cfp_iter3d it;

for (it = _.begin(a); _iter.neq(it, _.end(a)); it = _iter.inc(it))
  _iter.set(it, 1.0);
cfp_iter1f
cfp_iter2f
cfp_iter3f
cfp_iter4f
cfp_iter1d
cfp_iter2d
cfp_iter3d
cfp_iter4d

Opaque types for block iterators over 1D, 2D, 3D, and 4D compressed float or double array elements.


cfp_iter1
cfp_iter2
cfp_iter3
cfp_iter4

Fictitious types denoting iterators over 1D, 2D, 3D, and 4D arrays of any scalar type.


cfp_iterf
cfp_iterd

Fictitious types denoting iterators over float or double arrays of any dimensionality.


cfp_iter

Fictitious type denoting iterator over array of any dimensionality and scalar type.


float cfp.arrayf.iterator.get(const cfp_iterf self)
double cfp.arrayd.iterator.get(const cfp_iterd self)

Return element referenced by iterator; *self. See iterator::operator*().


float cfp.array1f.iterator.get_at(const cfp_iter1f self, ptrdiff_t d)
double cfp.array1d.iterator.get_at(const cfp_iter1d self, ptrdiff_t d)

Return element d elements (may be negative) from iterator; self[d]. See iterator::operator[]().


void cfp.arrayf.iterator.set(cfp_iterf self, float val)
void cfp.arrayd.iterator.set(cfp_iterd self, double val)

Update element referenced by iterator; *self = val. See iterator::operator*().


void cfp.array1f.iterator.set_at(cfp_iter1 self, ptrdiff_t d, float val)
void cfp.array1d.iterator.set_at(cfp_iter1 self, ptrdiff_t d, double val)

Update element d elements (may be negative) from iterator; self[d] = val. See iterator::operator[]().


cfp_ref cfp.array.iterator.ref(cfp_iter self)

Return reference to element referenced by iterator; *self. See iterator::operator*().


cfp_ref cfp.array.iterator.ref_at(cfp_iter self, ptrdiff_t d)

Return reference to an element offset d elements (may be negative) from iterator; self[d]. See iterator::operator[]().


cfp_ptr cfp.array.iterator.ptr(cfp_iter self)

Return pointer to element referenced by iterator; &*self.


cfp_ptr cfp.array.iterator.ptr_at(cfp_iter self, ptrdiff_t d)

Return pointer to element offset d elements (may be negative) from iterator; &self[d].


size_t cfp.array.iterator.i(const cfp_iter self)
size_t cfp.array.iterator.j(const cfp_iter self)
size_t cfp.array.iterator.k(const cfp_iter self)
size_t cfp.array.iterator.l(const cfp_iter self)

Return i, j, k, and l component of array element referenced by iterator; see iterator::i(), iterator::j(), iterator::k(), and iterator::l().


zfp_bool cfp.array.iterator.lt(const cfp_iter lhs, const cfp_iter rhs)
zfp_bool cfp.array.iterator.gt(const cfp_iter lhs, const cfp_iter rhs)
zfp_bool cfp.array.iterator.leq(const cfp_iter lhs, const cfp_iter rhs)
zfp_bool cfp.array.iterator.geq(const cfp_iter lhs, const cfp_iter rhs)

Return true if the two iterators satisfy the given relationship; lhs < rhs, lhs > rhs, lhs <= rhs, lhs >= rhs.


zfp_bool cfp.array.iterator.eq(const cfp_iter lhs, const cfp_iter rhs)

Return whether two iterators are equal; lhs == rhs. See iterator::operator==().


zfp_bool cfp.array.iterator.neq(const cfp_iter lhs, const cfp_iter rhs)

Return whether two iterators are not equal; lhs != rhs. See iterator::operator!=().


ptrdiff_t cfp.array.iterator.distance(const cfp_iter first, const cfp_iter last)

Return the difference between two iterators; last - first. See iterator::operator-().


cfp_iter cfp.array.iterator.next(const cfp_iter it, ptrdiff_t d)

Return the result of advancing iterator by d elements; it + d. See iterator::operator+().


cfp_iter cfp.array.iterator.prev(const cfp_iter it, ptrdiff_t d)

Return the result of decrementing iterator by d elements; it - d. See iterator::operator-().


cfp_iter cfp.array.iterator.inc(const cfp_iter it)

Return the result of incrementing iterator by one element; it + 1. See iterator::operator++().


cfp_iter cfp.array.iterator.dec(const cfp_iter it)

Return the result of decrementing iterator by one element; it - 1. See iterator::operator--().