nxfield base class More...
#include <nxfield.hpp>
Public Types | |
| typedef nximp_map< IMPID > ::field_imp | imp_type |
| implementation type More... | |
| typedef nximp_map< IMPID > ::type_imp | type_type |
| type implementation type More... | |
| typedef nxfield< IMPID > | field_type |
| typedef for this type More... | |
| typedef nxobject_trait< IMPID > ::attribute_type | attribute_type |
| attribute type More... | |
Public Member Functions | |
| nxfield () | |
| default constructor More... | |
| nxfield (const field_type &o) | |
| copy constructor More... | |
| nxfield (field_type &&o) | |
| move constructor More... | |
| nxfield (imp_type &&o) | |
| move constructor from implementation object More... | |
| nxfield (const typename nxobject_trait< IMPID >::object_type &o) | |
| constructor More... | |
| ~nxfield () | |
| destructor More... | |
| field_type & | operator= (const field_type &f) |
| copy assignment operator More... | |
| field_type & | operator= (field_type &&f) |
| move assignment operator More... | |
| field_type & | operator= (const typename nxobject_trait< IMPID >::object_type &o) |
| conversion assignment More... | |
| template<typename CTYPE > | |
| CTYPE | shape () const |
| field shape More... | |
| size_t | size () const |
| return size More... | |
| pni::core::type_id_t | type_id () const |
| get the type ID More... | |
| nxobject_trait< IMPID > ::object_type | parent () const |
| get parent object More... | |
| void | grow (const size_t &e, const size_t &n=1) |
| grow field along a particular dimension More... | |
| size_t | rank () const |
| number of dimensions More... | |
| template<typename T > | |
| void | read (T &value) const |
| reading simple data from the dataset More... | |
| template<typename T > | |
| void | read (size_t n, T *values) const |
| reading data to memory More... | |
| template<typename T > | |
| void | read (std::vector< T > &data) const |
| reading data vector More... | |
| template<typename STORAGE , typename IMAP , typename IPA > | |
| void | read (pni::core::mdarray< STORAGE, IMAP, IPA > &array) const |
| read data to array More... | |
| template<typename ATYPE > | |
| void | read (pni::core::array_view< ATYPE > &v) const |
| template<typename ATYPE > | |
| void | read (pni::core::array_view< ATYPE > &&v) const |
| void | read (array &a) const |
| read data to a array instance More... | |
| template<typename T > | |
| void | write (const T &value) const |
| write a single value More... | |
| template<typename T > | |
| void | write (size_t n, const T *value) const |
| write data from memory More... | |
| template<typename T > | |
| void | write (const std::vector< T > &data) const |
| write data from vector More... | |
| template<typename STORAGE , typename IMAP , typename IPA > | |
| void | write (const pni::core::mdarray< STORAGE, IMAP, IPA > &a) const |
| write data from mdarray More... | |
| template<typename ATYPE > | |
| void | write (const pni::core::array_view< ATYPE > &v) const |
| write data from array view More... | |
| void | write (const char *value) const |
| write old style string More... | |
| void | write (const pni::core::array &a) const |
| write array erasure More... | |
| template<typename... ITYPES> | |
| field_type | operator() (ITYPES...indices) const |
| set a selection on the field More... | |
| field_type | operator() () |
| clear a selection More... | |
| field_type | operator() (const std::vector< pni::core::slice > &selection) const |
| set a selection on the field More... | |
| pni::core::string | name () const |
| return field name More... | |
| pni::core::string | filename () const |
| return filename More... | |
| void | close () |
| close field More... | |
| bool | is_valid () const noexcept |
| check validity More... | |
Data Fields | |
| nxattribute_manager< field_type > | attributes |
| attribute manager More... | |
Private Member Functions | |
| template<typename ATYPE > | |
| void | _read_array (ATYPE &a) const |
| read data to array More... | |
| template<typename ATYPE > | |
| void | _write_array (const ATYPE &a) const |
| write data from array More... | |
Static Private Member Functions | |
| static pni::core::string | _shape_mismatch_error_message (const pni::core::shape_t &ashape, const pni::core::shape_t &fshape) |
| gernerate error message More... | |
Private Attributes | |
| imp_type | _imp |
| field implementation More... | |
Detailed Description
template<nximp_code IMPID>
class pni::io::nx::nxfield< IMPID >
nxfield is a type used to store multidimensional data in a file. The IO methods it provides support all the array templates provided by libpnicore. Partial IO is provided by the () operator (see below). The interface of nxfield is quite similar to those of the array templates provided by libpnicore. Like them it provides a shape() and a size() method returning the number of elements along each dimension and the total number of elements in the field. rank() returns the number of dimensions of the field.
Unlike the array templates which provide the ID of their element type via a static member variable the method type_id() is provided by NXField for the same purpose. The number of dimensions a field provides is fixed at the time it is created. However, the number of elements along each of these dimensions can be altered at runtime. Two methods of the class are responsible for resizing a field: resize() and grow(). The difference between resize and grow is shown in the figure below. While the grow() operation resizes the field by a fixed amount of elements along a particular dimension a resize operation can enlarge multiple dimensions at the same time. The latter one is useful in situations where the number of elements along each dimension is unknown at the time the field is created. The grow() operation is however very useful in situations where the number of elements to store in an element is not known at the time the field is created. One can use this to append data along one dimensions. Consider for instance this example that shows a very common situation during experiments. Data should be stored in a field but the total number of points is not known when the field is created
The above loop runs until get_break_condition() return true. In no case we can no in advance when the loop will exit and thus how many elements should be stored. The grow() method offers an easy way to handle such situations.
As HDF5 datasets, nxfield objects provide the possibility to read or write only a part of the data. The mechanism works pretty much as the array view selection in libpnicore. Compare the following code with the figures on the right side
Under the hood the () operator of NXField applies a selection to the underlying HDF5 dataset according to the arguments passed to it. Every call to read or write immediately after reading or writing the data removes this selections.
- Template Parameters
-
IMPID implementation id
Member Typedef Documentation
| typedef nxobject_trait<IMPID>::attribute_type pni::io::nx::nxfield< IMPID >::attribute_type |
| typedef nxfield<IMPID> pni::io::nx::nxfield< IMPID >::field_type |
| typedef nximp_map<IMPID>::field_imp pni::io::nx::nxfield< IMPID >::imp_type |
| typedef nximp_map<IMPID>::type_imp pni::io::nx::nxfield< IMPID >::type_type |
Constructor & Destructor Documentation
|
inlineexplicit |
|
inline |
|
inline |
|
inlineexplicit |
|
inline |
Constructs a field from an instance of nxobject.
- Exceptions
-
type_error if o does not store a field
- Parameters
-
o reference to nxobject that should hold a field
|
inline |
Member Function Documentation
|
inlineprivate |
Read data from the field and store its content into an array.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array data type cannot be handled io_error in case of IO errors
- Template Parameters
-
ATYPE array type
- Parameters
-
a reference to an instance fo ATYPE
|
inlinestaticprivate |
Generate the error message for a shape mismatch error between a field and an array type.
- Parameters
-
ashape array shape fshape field shape
- Returns
- error message
|
inlineprivate |
Write the content of an array to a field.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array type cannot be handled io_error in case of IO errors
- Template Parameters
-
ATYPE array type
- Parameters
-
a reference to an instance fo ATYPE
|
inline |
- Exceptions
-
type_error if object type could not be determined during closing object_error in case of any other error
|
inline |
Returns the name of the file the field belongs too.
- Exceptions
-
invalid_object_error if the field is not valid io_error if the filename information retrieval fails type_error if the internal object type does not support filename retrieval object_error in case of any other error
- Returns
- name of the file
|
inline |
Grows the field by n elements along dimension e. This method is pretty useful in cases where an arbitrary number of points shall be stored in a field and their number is not known when the field was created.
- Exceptions
-
index_error if e exceeds the rank of the field object_error in case of any other error invalid_object_error if field not valid
- Parameters
-
e index of dimension along which to grow n number of elements by which to grow
|
inlinenoexcept |
- Exceptions
-
object_error validity check fails
- Returns
- true if the field is valid, false otherwise
|
inline |
- Exceptions
-
invalid_object_error if field is not valid io_error if name could not be read type_error in case of an internal type issue object_error in case of any other error
- Returns
- name of the field
|
inline |
This method applies a selection to the field and return a reference to this field. This can now be used to write data only to the selection of the array.
The selection will be reset with every call to the read() or write methods.
- Exceptions
-
invalid_object_error if field is not valid shape_missmatch_error if selection and field rank do not match object_error in case of any other error
- Template Parameters
-
ITYPES index types
- Parameters
-
indices instances of ITYPES
- Returns
- field object with selection set
|
inline |
Clears a selection applied to the field.
- Exceptions
-
object_error in case of failure
- Returns
- new field instance with clearn selection
|
inline |
Operator to set a selection to the field. The selection is given by a vector container of slice objects. The selection will be reset with each call to the read() or write() methods.
- Exceptions
-
invalid_object_error if field is not valid shape_missmatch_error if selection and field rank do not match object_error in case of any other error
- Parameters
-
selection container with instances of slice
- Returns
- instance of NXField with selection set
|
inline |
- Parameters
-
f lvalue reference to a field
- Returns
- reference to the new field
|
inline |
- Parameters
-
f rvalue reference to an instance of nxfield
- Returns
- reference to nxfield
|
inline |
- Exceptions
-
type_error if object is not a field
- Parameters
-
o lvalue reference to an instance of nxobject
- Returns
- reference to the new field
|
inline |
Returns the parent object of the field.
- Exceptions
-
invalid_object_error if field is not valid type_error if the interal type of the field object could not be determined objet_error in case of any other error
- Returns
- parent object
|
inline |
Returns the number of dimensions of the field.
- Exceptions
-
invalid_object_error if field is not valid object_error in case of any other error
- Returns
- number of dimensions
|
inline |
Read a single data value from the dataset. In order to succeed the dataset must be a scalar dataset or the total size of the dataset must be 1.
- Exceptions
-
size_mismatch_error if dataset is not scalar invalid_object_error if field is not valid type_error if argument type cannot be handled io_error in case of IO failure object_error in case of any other error
- Template Parameters
-
T data type of the argument
- Parameters
-
value variable where to store the data
|
inline |
Read data from a field to a region in memory referedn to by poitner values. This method does not check any shape or size bounds.
- Exceptions
-
size_mismatch_error if n does not match the array size invalid_object_error if field is not valid type_error if argument type cannot be handled io_error in case of IO failure object_error in case of any other error
- Template Parameters
-
T data type to read (in memory)
- Parameters
-
n number of elements that should be read to values values pointer to memory reagion
|
inline |
Read from disk and store it to an STL vector.
- Exceptions
-
size_mismatch_error if the size of the vector does not match the size of the field invalid_object_error if field is not valid type_error if argument type cannot be handled io_error in case of IO failure object_error in case of any other error
- Template Parameters
-
T value type of the vector
- Parameters
-
data reference to the STL vector where to store the data
|
inline |
Copy the data stored in the field to an array object. An exception is thrown if the buffer holding the arrays data is not allocated or the shape of the array does not match the shape of the field.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array data type cannot be handled io_error in case of IO errors
- Template Parameters
-
STORAGE storage type of the mdarray template IMAP index map type of the array type IPA inplace arithmetic policy
- Parameters
-
array Array instance where to store the data
|
inline |
|
inline |
|
inline |
This method reads data to an array type erasure.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array data type cannot be handled io_error in case of IO errors
- Parameters
-
a instance of the array
|
inline |
Returns the shape of the field
- Exceptions
-
invalid_object_error if field is not valid object_error in case of any other error
- Returns
- container with elements per dimension
|
inline |
Return the size (number of elements) in the field.
- Exceptions
-
invalid_object_error if field is not valid objecct_error in case of any other error
- Returns
- total number of elements in the field
|
inline |
Return the ID of the data type stored in the field.
- Exceptions
-
invalid_object_error if field is not valid object_error in case of any other error type_error if data type is not supported
- Returns
- data type ID
|
inline |
Writes a single value of type T to the field. This method will succeed only if the field can hold only a single value.
- Exceptions
-
size_mismatch_error if the dataspace is not scalar invalid_object_error in case of IO errors io_error in case of IO errors object_error in case of all other errors type_error if tid does not have a corresponding HDF5 data type
- Template Parameters
-
T memory data type of the source
- Parameters
-
value value to write
|
inline |
Write data from a memory region referend to by value to the field. The method does not perform any size or shape checking. It assumes that the region of memory is large enough.
- Exceptions
-
size_mismatch_error if n does not match field size invalid_object_error in case of IO errors io_error in case of IO errors object_error in case of all other errors type_error if tid does not have a corresponding HDF5 data type
- Template Parameters
-
T memory data type of the source
- Parameters
-
n number of elements that should be written to the field value pointer to memory region
|
inline |
Write data stored in an STL vector to disk.
- Exceptions
-
size_mismatch_error if the size of the vector does not match the size of the field invalid_object_error in case of IO errors io_error in case of IO errors object_error in case of all other errors type_error if tid does not have a corresponding HDF5 data type
- Template Parameters
-
T value type of the vector
- Parameters
-
data reference to the STL vector
|
inline |
Write data stored in an instance of mdarray.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array type cannot be handled io_error in case of IO errors
- Template Parameters
-
STORAGE storage type for mdarray IMAP index map type for mdarray IPA inplance arithmetic type
- Parameters
-
a instance of mdarray
|
inline |
This function writes data from an array view. In principle this function works the same as for mdarray. However, there can be a significant performance penalty when the selection is not contiguous. In this case the content of the view must be copied to a temporary buffer before being writen to disk.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array type cannot be handled io_error in case of IO errors
- Template Parameters
-
ATYPE the array type of the view
- Parameters
-
v array view instance
|
inline |
Writes a C-style string to disk. This method is a specialization of the write(const T &value) template mathod.
- Exceptions
-
size_mismatch_error if the dataspace is not scalar invalid_object_error in case of IO errors io_error in case of IO errors object_error in case of all other errors type_error if tid does not have a corresponding HDF5 data type
- Parameters
-
value pointer to string data
|
inline |
Write the data stored by an array erasure.
- Exceptions
-
memory_not_allocated_error if array buffer not allocated size_mismatch_error if array and field size do not match invalid_object_error if field is not valid object_error in case of any other error type_error if array type cannot be handled io_error in case of IO errors
- Parameters
-
a reference to array erasure
Field Documentation
|
private |
| nxattribute_manager<field_type> pni::io::nx::nxfield< IMPID >::attributes |
This public attribute provides access to the attribute manager instance of this field.
- See also
- nxattribute_manager
The documentation for this class was generated from the following file:
