.. include:: defs.rst .. _arrays: Compressed-Array C++ Classes ============================ .. cpp:namespace:: zfp |zfp|'s compressed arrays are C++ classes, plus :ref:`C wrappers ` around these classes, that implement random-accessible single- and multi-dimensional floating-point arrays. Since its first release, |zfp| provides *fixed-rate* arrays, :code:`zfp::array`, that support both read and write access to individual array elements. As of |carrrelease|, |zfp| also supports read-only arrays, :code:`zfp::const_array`, for data that is static or is updated only infrequently. The read-only arrays support all of |zfp|'s :ref:`compression modes ` including variable-rate and lossless compression. For fixed-rate arrays, the storage size, specified in number of bits per array element, is set by the user. Such arbitrary storage is achieved via |zfp|'s lossy :ref:`fixed-rate compression ` mode, by partitioning each *d*-dimensional array into blocks of |4powd| values and compressing each block to a fixed number of bits. The more smoothly the array values vary along each dimension, the more accurately |zfp| can represent them. In other words, these arrays are not suitable for representing data where adjacent elements are not correlated. Rather, the expectation is that the array represents a regularly sampled and predominantly continuous function, such as a temperature field in a physics simulation. The *rate*, measured in number of bits per array element, can be specified in fractions of a bit (but see FAQs :ref:`#12 ` and :ref:`#18 ` for limitations). |zfp| supports 1D, 2D, 3D, and (as of version |4darrrelease|) 4D arrays. For higher-dimensional arrays, consider using an array of |zfp| arrays. Note that array dimensions need not be multiples of four; |zfp| transparently handles partial blocks on array boundaries. Read-only arrays allow setting compression mode and parameters on construction, and can optionally be initialized with uncompressed data. These arrays do not allow updating individual array elements, though the contents of the whole array may be updated by re-compressing and overwriting the array. This may be useful in applications that decompress the whole array, perform a computation that updates its contents (e.g., a stencil operation that advances the solution of a PDE), and then compress to memory the updated array. The C++ templated array classes are implemented entirely as header files that call the |zfp| C library to perform compression and decompression. These arrays cache decompressed blocks to reduce the number of compression and decompression calls. Whenever an array value is read, the corresponding block is first looked up in the cache, and if found the uncompressed value is returned. Otherwise the block is first decompressed and stored in the cache. Whenever an array element is written (whether actually modified or not), a "dirty bit" is set with its cached block to indicate that the block must be compressed back to persistent storage when evicted from the cache. This section documents the public interface to the array classes, including base classes and member accessor classes like proxy references/pointers, iterators, and views. The following sections are available: * :ref:`array_classes` * :ref:`carray_classes` * :ref:`caching` * :ref:`serialization` * :ref:`references` * :ref:`pointers` * :ref:`iterators` * :ref:`views` * :ref:`codec` * :ref:`index` .. _array_classes: Read-Write Fixed-Rate Arrays ---------------------------- There are eight array classes for 1D, 2D, 3D, and 4D read-write arrays, each of which can represent single- or double-precision values. Although these arrays store values in a form different from conventional single- and double-precision floating point, the user interacts with the arrays via floats and doubles. The array classes can often serve as direct substitutes for C/C++ single- and multi-dimensional floating-point arrays and STL vectors, but have the benefit of allowing fine control over storage size. All classes below belong to the :cpp:any:`zfp` namespace. .. note:: Much of the compressed-array API was modified in |zfp| |64bitrelease| to support 64-bit indexing of very large arrays. In particular, array dimensions and indices now use the :code:`size_t` type instead of :code:`uint` and strides use the :code:`ptrdiff_t` type instead of :code:`int`. .. _array_base_class: Base Class ^^^^^^^^^^ .. cpp:class:: array Virtual base class for common array functionality. ---- .. cpp:function:: zfp_type array::scalar_type() const Return the underlying scalar type (:c:type:`zfp_type`) of the array. ---- .. cpp:function:: uint array::dimensionality() const Return the dimensionality (aka. rank) of the array: 1, 2, 3, or 4. ---- .. cpp:function:: array::header array::get_header() const Deprecated function as of |zfp| |crpirelease|. See the :ref:`header` section on how to construct a header. ---- .. _array_factory: .. cpp:function:: static array* array::construct(const header& h, const void* buffer = 0, size_t buffer_size_bytes = 0) Construct a compressed-array object whose scalar type, dimensions, and rate are given by the :ref:`header
` *h*. Return a base class pointer upon success. The optional *buffer* points to compressed data that, when passed, is copied into the array. If *buffer* is absent, the array is default initialized with all zeroes. The optional *buffer_size_bytes* parameter specifies the buffer length in bytes. When passed, a comparison is made to ensure that the buffer size is at least as large as the size implied by the header. If this function fails for any reason, an :cpp:class:`exception` is thrown. Common Methods ^^^^^^^^^^^^^^ The following methods are common to 1D, 2D, 3D, and 4D arrays, but are implemented in the array class specific to each dimensionality rather than in the base class. .. cpp:function:: size_t array::size() const Total number of elements in array, e.g., *nx* |times| *ny* |times| *nz* for 3D arrays. ---- .. cpp:function:: double array::rate() const Return rate in bits per value. ---- .. cpp:function:: double array::set_rate(double rate) Set desired compression rate in bits per value. Return the closest rate supported. See FAQ :ref:`#12 ` and FAQ :ref:`#18 ` for discussions of the rate granularity. This method destroys the previous contents of the array. ---- .. cpp:function:: size_t array::size_bytes(uint mask = ZFP_DATA_ALL) const Return storage size of components of array data structure indicated by *mask*. The mask is constructed via bitwise OR of :ref:`predefined constants `. Available as of |zfp| |carrrelease|. ---- .. cpp:function:: size_t array::compressed_size() const Return number of bytes of storage for the compressed data. This amount does not include the small overhead of other class members or the size of the cache. Rather, it reflects the size of the memory buffer returned by :cpp:func:`compressed_data`. ---- .. cpp:function:: void* array::compressed_data() const Return pointer to compressed data for read or write access. The size of the buffer is given by :cpp:func:`compressed_size`. .. note:: As of |zfp| |crpirelease|, the return value is :code:`void*` rather than :code:`uchar*` to simplify pointer conversion and to dispel any misconception that the compressed data needs only :code:`uchar` alignment. Compressed streams are always word aligned (see :c:var:`stream_word_bits` and :c:macro:`BIT_STREAM_WORD_TYPE`). ---- .. cpp:function:: size_t array::cache_size() const Return the cache size in number of bytes. ---- .. cpp:function:: void array::set_cache_size(size_t bytes) Set minimum cache size in bytes. The actual size is always a power of two bytes and consists of at least one block. If *bytes* is zero, then a default cache size is used, which requires the array dimensions to be known. ---- .. cpp:function:: void array::clear_cache() const Empty cache without compressing modified cached blocks, i.e., discard any cached updates to the array. ---- .. cpp:function:: virtual void array::flush_cache() const Flush cache by compressing all modified cached blocks back to persistent storage and emptying the cache. This method should be called before writing the compressed representation of the array to disk, for instance. ---- .. cpp:function:: void array::get(Scalar* p) const Decompress entire array and store at *p*, for which sufficient storage must have been allocated. The uncompressed array is assumed to be contiguous (with default strides) and stored in the usual "row-major" order, i.e., with *x* varying faster than *y*, *y* varying faster than *z*, etc. ---- .. cpp:function:: void array::set(const Scalar* p) Initialize array by copying and compressing data stored at *p*. The uncompressed data is assumed to be stored as in the :cpp:func:`get` method. If *p* = 0, then the array is zero-initialized. ---- .. cpp:function:: const_reference array::operator[](size_t index) const Return :ref:`const reference ` to scalar stored at given flat index (inspector). For a 3D array, :code:`index = x + nx * (y + ny * z)`. .. note:: As of |zfp| |crpirelease|, the return value is no longer :code:`Scalar` but is a :ref:`const reference ` to the corresponding array element (conceptually equivalent to :code:`const Scalar&`). This API change was necessary to allow obtaining a const pointer to the element when the array itself is const qualified, e.g., :code:`const_pointer p = &a[index];`. ---- .. _lvref_idx: .. cpp:function:: reference array::operator[](size_t index) Return :ref:`proxy reference ` to scalar stored at given flat index (mutator). For a 3D array, :code:`index = x + nx * (y + ny * z)`. ---- .. cpp:function:: iterator array::begin() Return random-access mutable iterator to beginning of array. ---- .. cpp:function:: iterator array::end() Return random-access mutable iterator to end of array. As with STL iterators, the end points to a virtual element just past the last valid array element. ---- .. cpp:function:: const_iterator array::begin() const .. cpp:function:: const_iterator array::cbegin() const Return random-access const iterator to beginning of array. ---- .. cpp:function:: const_iterator array::end() const .. cpp:function:: const_iterator array::cend() const Return random-access const iterator to end of array. .. note:: Const :ref:`references `, :ref:`pointers `, and :ref:`iterators ` are available as of |zfp| |crpirelease|. 1D, 2D, 3D, and 4D Arrays ^^^^^^^^^^^^^^^^^^^^^^^^^ Below are classes and methods specific to each array dimensionality and template scalar type (:code:`float` or :code:`double`). Since the classes and methods share obvious similarities regardless of dimensionality, only one generic description for all dimensionalities is provided. Note: In the class declarations below, the class template for the scalar type is omitted for readability, e.g., :code:`class array1` is used as shorthand for :code:`template class array1`. Wherever the type :code:`Scalar` appears, it refers to this template argument. .. .. cpp:class:: template array1 : public array .. cpp:class:: template array2 : public array .. cpp:class:: template array3 : public array .. cpp:class:: template array4 : public array .. cpp:class:: array1 : public array .. cpp:class:: array2 : public array .. cpp:class:: array3 : public array .. cpp:class:: array4 : public array This is a 1D, 2D, 3D, or 4D array that inherits basic functionality from the generic :cpp:class:`array` base class. The template argument, :cpp:type:`Scalar`, specifies the floating type returned for array elements. The suffixes :code:`f` and :code:`d` can also be appended to each class to indicate float or double type, e.g., :cpp:class:`array1f` is a synonym for :cpp:class:`array1\`. ---- .. cpp:class:: arrayANY : public array Fictitious class used to refer to any one of :cpp:class:`array1`, :cpp:class:`array2`, :cpp:class:`array3`, and :cpp:class:`array4`. This class is not part of the |zfp| API. ---- .. _array_ctor_default: .. cpp:function:: array1::array1() .. cpp:function:: array2::array2() .. cpp:function:: array3::array3() .. cpp:function:: array4::array4() Default constructor. Creates an empty array whose size and rate are both zero. .. note:: The default constructor is useful when the array size or rate is not known at time of construction. Before the array can become usable, however, it must be :ref:`resized ` and its rate must be set via :cpp:func:`array::set_rate`. These two tasks can be performed in either order. Furthermore, the desired cache size should be set using :cpp:func:`array::set_cache_size`, as the default constructor creates a cache that holds only one |zfp| block, i.e., the minimum possible. ---- .. _array_ctor: .. cpp:function:: array1::array1(size_t n, double rate, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: array2::array2(size_t nx, size_t ny, double rate, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: array3::array3(size_t nx, size_t ny, size_t nz, double rate, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: array4::array4(size_t nx, size_t ny, size_t nz, size_t nw, double rate, const Scalar* p = 0, size_t cache_size = 0) Constructor of array with dimensions *n* (1D), *nx* |times| *ny* (2D), *nx* |times| *ny* |times| *nz* (3D), or *nx* |times| *ny* |times| *nz* |times| *nw* (4D) using *rate* bits per value, at least *cache_size* bytes of cache, and optionally initialized from flat, uncompressed array *p*. If *cache_size* is zero, a default cache size suitable for the array dimensions is chosen. ---- .. _array_ctor_header: .. cpp:function:: array1::array1(const array::header& h, const void* buffer = 0, size_t buffer_size_bytes = 0) .. cpp:function:: array2::array2(const array::header& h, const void* buffer = 0, size_t buffer_size_bytes = 0) .. cpp:function:: array3::array3(const array::header& h, const void* buffer = 0, size_t buffer_size_bytes = 0) .. cpp:function:: array4::array4(const array::header& h, const void* buffer = 0, size_t buffer_size_bytes = 0) Constructor from previously :ref:`serialized ` compressed array. The :ref:`header
`, *h*, contains array metadata, while the optional *buffer* points to the compressed data that is to be copied to the array. The optional *buffer_size_bytes* parameter specifies the *buffer* length. If the constructor fails, an :ref:`exception ` is thrown. See :cpp:func:`array::construct` for further details on the *buffer* and *buffer_size_bytes* parameters. ---- .. _array_copy_constructor: .. cpp:function:: array1::array1(const array1& a) .. cpp:function:: array2::array2(const array2& a) .. cpp:function:: array3::array3(const array3& a) .. cpp:function:: array4::array4(const array4& a) Copy constructor. Performs a deep copy. ---- .. cpp:function:: virtual array1::~array1() .. cpp:function:: virtual array2::~array2() .. cpp:function:: virtual array3::~array3() .. cpp:function:: virtual array4::~array4() Virtual destructor (allows for inheriting from |zfp| arrays). ---- .. _array_copy: .. cpp:function:: array1& array1::operator=(const array1& a) .. cpp:function:: array2& array2::operator=(const array2& a) .. cpp:function:: array3& array3::operator=(const array3& a) .. cpp:function:: array4& array4::operator=(const array4& a) Assignment operator. Performs a deep copy. ---- .. _array_dims: .. cpp:function:: size_t array2::size_x() const .. cpp:function:: size_t array2::size_y() const .. cpp:function:: size_t array3::size_x() const .. cpp:function:: size_t array3::size_y() const .. cpp:function:: size_t array3::size_z() const .. cpp:function:: size_t array4::size_x() const .. cpp:function:: size_t array4::size_y() const .. cpp:function:: size_t array4::size_z() const .. cpp:function:: size_t array4::size_w() const Return array dimensions. ---- .. _array_resize: .. cpp:function:: void array1::resize(size_t n, bool clear = true) .. cpp:function:: void array2::resize(size_t nx, size_t ny, bool clear = true) .. cpp:function:: void array3::resize(size_t nx, size_t ny, size_t nz, bool clear = true) .. cpp:function:: void array4::resize(size_t nx, size_t ny, size_t nz, size_t nw, bool clear = true) Resize the array (all previously stored data will be lost). If *clear* is true, then the array elements are all initialized to zero. .. note:: It is often desirable (though not a requirement) to also set the cache size when resizing an array, e.g., in proportion to the array size; see :cpp:func:`array::set_cache_size`. This is particularly important when the array is default constructed, which initializes the cache size to the minimum possible of only one |zfp| block. ---- .. _array_accessor: .. cpp:function:: const_reference array1::operator()(size_t i) const .. cpp:function:: const_reference array2::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array3::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference array4::operator()(size_t i, size_t j, size_t k, size_t l) const Return const reference to element stored at multi-dimensional index given by *i*, *j*, *k*, and *l* (inspector). .. note:: As of |zfp| |crpirelease|, the return value is no longer :code:`Scalar` but is a :ref:`const reference ` to the corresponding array element (essentially equivalent to :code:`const Scalar&`). This API change was necessary to allow obtaining a const pointer to the element when the array itself is const qualified, e.g., :code:`const_pointer p = &a(i, j, k);`. ---- .. _lvref: .. cpp:function:: reference array1::operator()(size_t i) .. cpp:function:: reference array2::operator()(size_t i, size_t j) .. cpp:function:: reference array3::operator()(size_t i, size_t j, size_t k) .. cpp:function:: reference array4::operator()(size_t i, size_t j, size_t k, size_t l) Return :ref:`proxy reference ` to scalar stored at multi-dimensional index given by *i*, *j*, *k*, and *l* (mutator). .. _carray_classes: Read-Only Variable-Rate Arrays ------------------------------ Read-only arrays are preferable in applications that store static data, e.g., constant tables or simulation output, or data that is updated only periodically as a whole, such as when advancing the solution of a partial differential equation. Because such updates have to be applied to the whole array, one may choose to tile large arrays into smaller |zfp| arrays to support finer granularity updates. Read-only arrays have the benefit of supporting all of |zfp|'s :ref:`compression modes `, most of which provide higher accuracy per bit stored than fixed-rate mode. The read-only arrays share an API with the read-write fixed-rate arrays, with only a few differences: - All methods other than those that specify array-wide settings, such as compression mode and parameters, array dimensions, and array contents, are :code:`const` qualified. There are, thus, no methods for obtaining a writeable reference, pointer, or iterator. Consequently, one may not initialize such arrays one element at a time. Rather, the user initializes the whole array by passing a pointer to uncompressed data. - Whereas the constructors for fixed-rate arrays accept a *rate* parameter, the read-only arrays allow specifying any compression mode and corresponding parameters (if any) via a :c:type:`zfp_config` object. - Additional methods are available for setting and querying compression mode and parameters after construction. - Read-only arrays are templated on a block index class that encodes the bit offset to each block of data. Multiple index classes are available that trade compactness and speed of access. The default :cpp:class:`hybrid4` index represents 64-bit offsets using only 24 bits of amortized storage per block. An "implicit" index is available for fixed-rate read-only arrays, which computes rather than stores offsets to equal-sized blocks. .. note:: Whereas variable-rate compression almost always improves accuracy per bit of compressed data over fixed rate, one should also weigh the storage and compute overhead associated with the block index needed for variable-rate storage. The actual storage overhead can be determined by passing :c:macro:`ZFP_DATA_INDEX` to :cpp:func:`const_array::size_bytes`. This overhead tends to be small for 3D and 4D arrays. Array initialization may be done at construction time, by passing a pointer to uncompressed data, or via the method :cpp:func:`const_array::set`, which overwrites the contents of the whole array. This method may be called more than once to update (i.e., re-initialize) the array. Read-only arrays support a subset of references, pointers, iterators, and views; in particular those with a :code:`const_` prefix. Currently, not all capabilities of read-write arrays are available for read-only arrays. For example, (de)serialization and construction from a view have not yet been implemented, and there are no C bindings. Read-only arrays derive from the :ref:`array base class `. Additional methods are documented below. .. .. cpp:class:: template const_array1 : public array .. cpp:class:: template const_array2 : public array .. cpp:class:: template const_array3 : public array .. cpp:class:: template const_array4 : public array .. cpp:class:: const_array1 : public array .. cpp:class:: const_array2 : public array .. cpp:class:: const_array3 : public array .. cpp:class:: const_array4 : public array 1D, 2D, 3D, or 4D read-only array that inherits basic functionality from the generic :cpp:class:`array` base class. The template argument, :cpp:type:`Scalar`, specifies the floating type returned for array elements. The suffixes :code:`f` and :code:`d` can also be appended to each class to indicate float or double type, e.g., :cpp:class:`const_array1f` is a synonym for :cpp:class:`const_array1\`. ---- .. cpp:class:: const_array : public array Fictitious class used to denote one of the 1D, 2D, 3D, and 4D read-only array classes. This pseudo base class serves only to document the API shared among the four arrays. ---- .. _carray_ctor_default: .. cpp:function:: const_array1::const_array1() .. cpp:function:: const_array2::const_array2() .. cpp:function:: const_array3::const_array3() .. cpp:function:: const_array4::const_array4() Default constructor. Creates an empty array whose size is zero and whose compression mode is unspecified. The array's cache size is initialized to the minimum possible, which can have performance implications; see :ref:`this note `. ---- .. _carray_ctor: .. cpp:function:: const_array1::const_array1(size_t n, const zfp_config& config, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: const_array2::const_array2(size_t nx, size_t ny, const zfp_config& config, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: const_array3::const_array3(size_t nx, size_t ny, size_t nz, const zfp_config& config, const Scalar* p = 0, size_t cache_size = 0) .. cpp:function:: const_array4::const_array4(size_t nx, size_t ny, size_t nz, size_t nw, const zfp_config& config, const Scalar* p = 0, size_t cache_size = 0) Constructor of array with dimensions *n* (1D), *nx* |times| *ny* (2D), *nx* |times| *ny* |times| *nz* (3D), or *nx* |times| *ny* |times| *nz* |times| *nw* (4D). The compression mode and parameters are given by *config* (see :ref:`configuration `). The array uses at least *cache_size* bytes of cache, and is optionally initialized from flat, uncompressed array *p*. If *cache_size* is zero, a default cache size suitable for the array dimensions is chosen. ---- .. cpp:function:: const_array1::const_array1(const const_array1& a) .. cpp:function:: const_array2::const_array2(const const_array2& a) .. cpp:function:: const_array3::const_array3(const const_array3& a) .. cpp:function:: const_array4::const_array4(const const_array4& a) Copy constructor. Performs a deep copy. ---- .. cpp:function:: virtual const_array1::~const_array1() .. cpp:function:: virtual const_array2::~const_array2() .. cpp:function:: virtual const_array3::~const_array3() .. cpp:function:: virtual const_array4::~const_array4() Virtual destructor (allows for inheritance). ---- .. _carray_copy: .. cpp:function:: const_array1& const_array1::operator=(const const_array1& a) .. cpp:function:: const_array2& const_array2::operator=(const const_array2& a) .. cpp:function:: const_array3& const_array3::operator=(const const_array3& a) .. cpp:function:: const_array4& const_array4::operator=(const const_array4& a) Assignment operator. Performs a deep copy. ---- .. cpp:function:: size_t const_array::size() const Total number of elements in array, e.g., *nx* |times| *ny* |times| *nz* for 3D arrays. ---- .. _carray_dims: .. cpp:function:: size_t const_array2::size_x() const .. cpp:function:: size_t const_array2::size_y() const .. cpp:function:: size_t const_array3::size_x() const .. cpp:function:: size_t const_array3::size_y() const .. cpp:function:: size_t const_array3::size_z() const .. cpp:function:: size_t const_array4::size_x() const .. cpp:function:: size_t const_array4::size_y() const .. cpp:function:: size_t const_array4::size_z() const .. cpp:function:: size_t const_array4::size_w() const Return array dimensions. ---- .. _carray_resize: .. cpp:function:: void const_array1::resize(size_t n, bool clear = true) .. cpp:function:: void const_array2::resize(size_t nx, size_t ny, bool clear = true) .. cpp:function:: void const_array3::resize(size_t nx, size_t ny, size_t nz, bool clear = true) .. cpp:function:: void const_array4::resize(size_t nx, size_t ny, size_t nz, size_t nw, bool clear = true) Resize the array (all previously stored data will be lost). If *clear* is true, then the array elements are all initialized to zero. See also :ref:`this note `. ---- .. cpp:function:: zfp_mode const_array::mode() const Currently selected :ref:`compression mode `. If not yet specified, :code:`zfp_mode_null` is returned. ---- .. cpp:function:: double const_array::rate() const Return rate in compressed bits per value when :ref:`fixed-rate mode ` is enabled, else zero. ---- .. cpp:function:: uint const_array::precision() const Return precision in uncompressed bits per value when :ref:`fixed-precision mode ` is enabled, else zero. ---- .. cpp:function:: double const_array::accuracy() const Return accuracy as absolute error tolerance when :ref:`fixed-accuracy mode ` is enabled, else zero. ---- .. cpp:function:: void const_array::params(uint* minbits, uint* maxbits, uint* maxprec, int* minexp) const :ref:`Expert mode ` compression parameters (available for all compression modes). Pointers may be :code:`null` if the corresponding parameter is not requested. ---- .. cpp:function:: double const_array::set_reversible() Enable :ref:`reversible mode `. This method destroys the previous contents of the array. ---- .. cpp:function:: double const_array::set_rate(double rate) Set desired rate in compressed bits per value (enables :ref:`fixed-rate mode `). This method destroys the previous contents of the array. See also :cpp:func:`array::set_rate`. .. note:: Whereas the :ref:`read-write fixed-rate arrays ` (:cpp:class:`zfp::array`) require that block storage is word aligned, the read-only arrays (:cpp:class:`zfp::const_array`) are not subject to such restrictions and therefore support finer rate granularity. For a *d*-dimensional :cpp:class:`const_array`, the rate granularity is 4\ :sup:`-d` bits/value, e.g., a quarter bit/value for 1D arrays. ---- .. cpp:function:: uint const_array::set_precision(uint precision) Set desired precision in uncompressed bits per value (enables :ref:`fixed-precision mode `). This method destroys the previous contents of the array. ---- .. cpp:function:: double const_array::set_accuracy(double tolerance) Set desired accuracy as absolute error tolerance (enables :ref:`fixed-accuracy mode `). This method destroys the previous contents of the array. ---- .. cpp:function:: bool const_array::set_params(uint minbits, uint maxbits, uint maxprec, int minexp) Set :ref:`expert mode ` parameters. This method destroys the previous contents of the array. Return whether the codec supports the combination of parameters. ---- .. cpp:function:: void const_array::set_config(const zfp_config& config) Set compression mode and parameters given by *config* (see :ref:`configuration `). This is a more general method for setting compression parameters such as rate, precision, accuracy, and :ref:`expert mode ` parameters. ---- .. cpp:function:: size_t const_array::size_bytes(uint mask = ZFP_DATA_ALL) const Return storage size of components of array data structure indicated by *mask*. The mask is constructed via bitwise OR of :ref:`predefined constants `. ---- .. cpp:function:: size_t const_array::compressed_size() const Return number of bytes of storage for the compressed data. This amount does not include the small overhead of other class members or the size of the cache. Rather, it reflects the size of the memory buffer returned by :cpp:func:`compressed_data`. ---- .. cpp:function:: void* const_array::compressed_data() const Return pointer to compressed data for read or write access. The size of the buffer is given by :cpp:func:`compressed_size`. ---- .. cpp:function:: size_t const_array::cache_size() const Return the cache size in number of bytes. ---- .. cpp:function:: void const_array::set_cache_size(size_t bytes) Set minimum cache size in bytes. The actual size is always a power of two bytes and consists of at least one block. If *bytes* is zero, then a default cache size is used, which requires the array dimensions to be known. ---- .. cpp:function:: void const_array::clear_cache() const Empty cache. ---- .. cpp:function:: void const_array::get(Scalar* p) const Decompress entire array and store at *p*, for which sufficient storage must have been allocated. The uncompressed array is assumed to be contiguous (with default strides) and stored in the usual "row-major" order, i.e., with *x* varying faster than *y*, *y* varying faster than *z*, etc. ---- .. cpp:function:: void const_array::set(const Scalar* p, bool compact = true) Initialize array by copying and compressing floating-point data stored at *p*. If *p* = 0, then the array is zero-initialized. The uncompressed data is assumed to be stored as in the :cpp:func:`get` method. Since the size of compressed data may not be known a priori, this method conservatively allocates enough space to hold it. If *compact* is true, any unused storage for compressed data is freed after initialization. ---- .. _const_array_accessor: .. cpp:function:: const_reference const_array1::operator()(size_t i) const .. cpp:function:: const_reference const_array2::operator()(size_t i, size_t j) const .. cpp:function:: const_reference const_array3::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference const_array4::operator()(size_t i, size_t j, size_t k, size_t l) const Return const reference to element stored at multi-dimensional index given by *i*, *j*, *k*, and *l* (inspector). ---- .. cpp:function:: const_reference const_array::operator[](size_t index) const Return :ref:`const reference ` to scalar stored at given flat index (inspector). For a 3D array, :code:`index = x + nx * (y + ny * z)`. ---- .. cpp:function:: const_iterator const_array::begin() const .. cpp:function:: const_iterator const_array::cbegin() const Return random-access const iterator to beginning of array. ---- .. cpp:function:: const_iterator end() const .. cpp:function:: const_iterator cend() const Return random-access const iterator to end of array. .. include:: caching.inc .. include:: serialization.inc .. include:: references.inc .. include:: pointers.inc .. include:: iterators.inc .. include:: views.inc .. include:: codec.inc .. include:: index.inc