diff --git a/doc/H5.dox b/doc/H5.dox index 926dd5f..a6c6fd2 100644 --- a/doc/H5.dox +++ b/doc/H5.dox @@ -32,34 +32,114 @@ Previous developers: For more information, please contact the h5part mailing list. -*/ +\defgroup c_api C API +@{ + \note The C API is implemented with '\c static \c inline' functions to minimize overhead. + \defgroup h5_c_api H5 + @{ + \defgroup h5_file File interface -/*! - \defgroup c_api C API - @{ - \note The C API is implemented with '\c static \c inline' functions to minimize overhead. - \defgroup h5_c_api H5 - @{ - \defgroup h5_file file interface - \defgroup h5_model setting up the data model - \defgroup h5_file_attribs reading and writing file attributes - \defgroup h5_step_attribs reading and writing step attributes - \defgroup h5_log control verbosity level - \defgroup h5_debug control debug output - \defgroup h5_error error handling interface - @} - \defgroup h5part_c_api H5Part - @{ - \defgroup h5part_model setting up the data model - \defgroup h5part_io reading and writing datasets - @} - \defgroup h5block_c_api H5Block - @{ - \defgroup h5block_model setting up the data model - \defgroup h5block_io reading and writing datasets - \defgroup h5block_attrib reading and writing attributes - @} - @} + In this section we document the interface for accessing H5hut files. + + \defgroup h5_model Setting up the data model + + The fundamental data model of H5hut is pretty simple. There + are (time-)steps to group data, that's it. In this section we + document the interface to these (time-)steps. + + \defgroup h5_file_attribs File attributes interface + + File attributes are small datasets that can be used to + describe specific properties of a file. The H5hut API provides + functions to attach (write), read and inquire file attributes. + + \defgroup h5_step_attribs Step attributes interface + + Step attributes are similar to file attributes but are + attached to (time-)steps. They can be used to describe + specific properties of a specific step. The H5hut API provides + functions to attach (write), read and inquire step attributes. + + \defgroup h5_attach Attaching files + + Sometimes it is required (or at least useful) to attach + additional information to H5hut files. H5hut provides + functions to attach other files to H5hut files. The attached + files can be of any type. + + \defgroup h5_log Controlling verbosity level + + Controlling the verbosity level of H5hut. By default only + error messages are printed. For debugging it might be helpful + to increase the verbosity level. + + \defgroup h5_debug Controlling debug output + + Debug output mainly intended for developers. + + \defgroup h5_error Error handling interface + + H5hut comes with two error handler. The default error handler + prints an error message (which can be suppressed by setting + the verbosity level to \c 0), sets an internal error number + and returns to the calling program with the value \c + H5_FAILURE. It is up to the programmer to handle the error + properly. In certain use-cases it make sense just to abort the + program, so no additional error handling is needed. H5hut + provides an abort error-handler for this use-cases- + + @} + \defgroup h5part_c_api H5Part + @{ + \defgroup h5part_model Setting up the data model + + The H5Part data model interface provides functions to set and + inquire (per core) views on datasets. + + \defgroup h5part_io Dataset interface + + The dataset interface provides functions to read and write + datasets. The following data types are supported: + + - 64-bit floating point numbers (\c h5_float64_t) + - 32-bit floating point numbers (\c h5_float32_t) + - 64-bit integers (\c h5_int64_t) + - 32-bit integers (\c h5_int32_t) + + \note Before you can write or read a dataset, you have to + define a "view" on the dataset for each core. + + @} + \defgroup h5block_c_api H5Block + @{ + \defgroup h5block_model Setting up the data model + + The H5Block data model interface provides functions to set and + inquire (per core) views on fields. + + \defgroup h5block_io Interface to block structured data + + H5Block provides functions to store and retrieve + + - 3-dimensional fields with scalar values + - 3-dimensional fields with 3-dimensional vectors as values + + The following datatypes are supported: + + - 64-bit floating point numbers (\c h5_float64_t) + - 32-bit floating point numbers (\c h5_float32_t) + - 64-bit integers (\c h5_int64_t) + - 32-bit integers (\c h5_int32_t) + + \defgroup h5block_attrib Attaching attributes to field data + + Field attributes are small datasets that can be used to + describe specific properties of a field like origin, spacing + or coordinates. The H5hut API provides functions to attach + (write), read and inquire file attributes. + + @} +@} */ /*! diff --git a/src/include/H5Block_attribs.h b/src/include/H5Block_attribs.h index 8ee485c..1915161 100644 --- a/src/include/H5Block_attribs.h +++ b/src/include/H5Block_attribs.h @@ -17,29 +17,24 @@ #include "h5core/h5_debug.h" #include "h5core/h5b_attribs.h" -/** - \addtogroup h5block_attrib - @{ -*/ - #ifdef __cplusplus extern "C" { #endif /* - ! __ _ _ _ _ _ _ _ _ - ! / _(_) ___| | __| | __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ - ! | |_| |/ _ \ |/ _` | / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| - ! | _| | __/ | (_| | | (_| | |_| |_| | | | |_) | |_| | || __/\__ \ - ! |_| |_|\___|_|\__,_| \__,_|\__|\__|_| |_|_.__/ \__,_|\__\___||___/ - ! - ! - ! __ _ _ _ ___ _ __ _ _ - ! / _` | | | |/ _ \ '__| | | | - ! | (_| | |_| | __/ | | |_| | - ! \__, |\__,_|\___|_| \__, | - ! |_| |___/ - */ + ! _ _ + ! (_)_ __ __ _ _ _(_)_ __ ___ + ! | | '_ \ / _` | | | | | '__/ _ \ + ! | | | | | (_| | |_| | | | | __/ + ! |_|_| |_|\__, |\__,_|_|_| \___| + ! |_| + ! +*/ +/** + \addtogroup h5block_attrib + @{ +*/ + /** Query the number of attributes attached to a given field. @@ -79,7 +74,7 @@ H5BlockGetFieldAttribInfo ( const char* field_name, ///< [in] field name. const h5_size_t attrib_idx, ///< [in] index of attribute to query char* attrib_name, ///< [out] name of attribute. - const h5_size_t len_attrib_name,///< [in] length of buffer \c name. + const h5_size_t len_attrib_name,///< [in] size of buffer \c attrib_name. h5_int64_t* attrib_type, ///< [out] type of value. h5_size_t* attrib_nelem ///< [out] number of elements. ) { @@ -133,8 +128,7 @@ H5BlockHasFieldAttrib ( } /** - Get the type and number of elements of a field attribute - given by its name. + Get the type and number of elements of a given field attribute. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error @@ -167,323 +161,43 @@ H5BlockGetFieldAttribInfoByName ( } /* - ! _ __ _ _ - ! (_) / /__ ___| |_ _ __(_)_ __ __ _ - ! | | / / _ \ / __| __| '__| | '_ \ / _` | - ! | |/ / (_) | \__ \ |_| | | | | | | (_| | - ! |_/_/ \___/ |___/\__|_| |_|_| |_|\__, | - ! |___/ -*/ - -/** - Write the string in \c buffer as attribute \c attrib_name of field - \c field_name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockWriteFieldAttribString ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - const char* attrib_name, ///< [in] attribute name - const char* buffer ///< [in] attribute value - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "field_name='%s', " - "attrib_name='%s', " - "buffer='%s'", - (h5_file_p)f, - field_name, - attrib_name, - buffer); - H5_API_RETURN ( - h5b_write_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_CHAR, - buffer, - strlen(buffer) + 1)); -} - -/** - Read the string value from attribute \c attrib_name of field - \c field_name into \c buffer. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockReadFieldAttribString ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - char* buffer ///< [out] attribute value. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "field_name='%s', " - "attrib_name='%s', " - "buffer=%p", - (h5_file_p)f, - field_name, - attrib_name, - buffer); - H5_API_RETURN ( - h5b_read_field_attrib ( - f, - field_name, - attrib_name, - H5_STRING_T, - (void*)buffer)); -} - -/* - ! _ __ _ - ! (_) / /__ _ __ ___ __ _| | - ! | | / / _ \ | '__/ _ \/ _` | | - ! | |/ / (_) | | | | __/ (_| | | - ! |_/_/ \___/ |_| \___|\__,_|_| + ! _ _ _ _ + ! ___ _ __ ___ ___(_) __ _| | __ _| |_| |_ _ __ + ! / __| '_ \ / _ \/ __| |/ _` | | / _` | __| __| '__| + ! \__ \ |_) | __/ (__| | (_| | | | (_| | |_| |_| | + ! |___/ .__/ \___|\___|_|\__,_|_| \__,_|\__|\__|_| + ! |_| */ /** - Attach an array of 64 bit floating point data as attribute to given field. + Set field origin. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t -H5BlockWriteFieldAttribFloat64 ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] attach attribute to field with this name - const char* attrib_name, ///< [in] attribute name - const h5_float64_t* buffer, ///< [in] pointer to attribute data - const h5_size_t nelems ///< [in] number of elements to write +H5Block3dSetFieldOrigin ( + const h5_file_t f, ///< [in] file handle. + const char* field_name, ///< [in] field name. + const h5_float64_t x_origin, ///< [in] X origin. + const h5_float64_t y_origin, ///< [in] Y origin. + const h5_float64_t z_origin ///< [in] Z origin. ) { - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', " - "buffer=%p, nelems=%lld", - (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); + "f=%p, field_name='%s', " + "x_origin=%g, y_origin=%g, z_origin=%g", + (h5_file_p)f, field_name, + x_origin, y_origin, z_origin); + h5_float64_t origin[3] = { x_origin, y_origin, z_origin }; H5_API_RETURN (h5b_write_field_attrib ( f, field_name, - attrib_name, - H5T_NATIVE_DOUBLE, - buffer, - nelems )); + H5BLOCK_FIELD_ORIGIN_NAME, + (hid_t)H5_FLOAT64_T, + origin, + 3)); } -/** - Read float64 values from attribute \c attrib_name of field - \c field_name into a \c buffer. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockReadFieldAttribFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - h5_float64_t* buffer ///< [out] attribute values. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', buffer=%p", - (h5_file_p)f, field_name, attrib_name, buffer); - H5_API_RETURN (h5b_read_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_DOUBLE, - (void*)buffer )); -} - - -/** - Write float32 \c values as attribute \c attrib_name of field - \c field_name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockWriteFieldAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - const h5_float32_t* buffer, ///< [in] attribute values. - const h5_size_t nelems ///< [in] number of elements. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', " - "buffer=%p, nelems=%lld", - (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); - H5_API_RETURN (h5b_write_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_FLOAT, - buffer, - nelems )); -} - -/** - Read float32 values from attribute \c attrib_name of field - \c field_name into a \c buffer. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockReadFieldAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - h5_float32_t* const buffer ///< [out] attribute values. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', buffer=%p", - (h5_file_p)f, field_name, attrib_name, buffer); - H5_API_RETURN (h5b_read_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_FLOAT, - buffer )); -} - -/* - ! _ __ _ _ - ! (_) / /__ (_)_ __ | |_ ___ __ _ ___ _ __ - ! | | / / _ \ | | '_ \| __/ _ \/ _` |/ _ \ '__| - ! | |/ / (_) | | | | | | || __/ (_| | __/ | - ! |_/_/ \___/ |_|_| |_|\__\___|\__, |\___|_| - ! |___/ -*/ - -/** - Write int64 \c values as attribute \c attrib_name of field - \c field_name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockWriteFieldAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - const h5_int64_t* buffer, ///< [in] attribute values. - const h5_size_t nelems ///< [in] number of elements. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', buffer=%p, nelems=%lld", - (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); - H5_API_RETURN (h5b_write_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_INT64, - buffer, - nelems )); -} - -/** - Read int64 values from attribute \c attrib_name of field - \c field_name into a \c buffer. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockReadFieldAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - h5_int64_t* const buffer ///< [out] attribute values. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', buffer=%p", - (h5_file_p)f, field_name, attrib_name, buffer); - H5_API_RETURN (h5b_read_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_INT64, - buffer )); -} - - -/** - Write int32 \c values as attribute \c attrib_name of field - \c field_name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockWriteFieldAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - const h5_int32_t* buffer, ///< [in] attribute values. - const h5_size_t nelems ///< [in] number of elements. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', " - "buffer=%p, nelems=%lld", - (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); - H5_API_RETURN (h5b_write_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_INT32, - buffer, - nelems )); -} - -/** - Read int32 values from attribute \c attrib_name of field - \c field_name into a \c buffer. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockReadFieldAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const char* attrib_name, ///< [in] attribute name. - h5_int32_t* buffer ///< [out] attribute values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', attrib_name='%s', buffer=%p", - (h5_file_p)f, field_name, attrib_name, buffer); - H5_API_RETURN (h5b_read_field_attrib ( - f, - field_name, - attrib_name, - H5T_NATIVE_INT32, - (void*)buffer )); -} - -/* - ! __ _ _ _ _ _ - ! / _(_) ___| | __| | ___ _ __(_) __ _(_)_ __ - ! | |_| |/ _ \ |/ _` | / _ \| '__| |/ _` | | '_ \ - ! | _| | __/ | (_| | | (_) | | | | (_| | | | | | - ! |_| |_|\___|_|\__,_| \___/|_| |_|\__, |_|_| |_| - ! |___/ -*/ /** Get field origin. @@ -518,41 +232,34 @@ H5Block3dGetFieldOrigin ( } /** - Set field origin. + Set field spacing for field \c field_name in the current step. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t -H5Block3dSetFieldOrigin ( - const h5_file_t f, ///< [in] file handle. +H5Block3dSetFieldSpacing ( + const h5_file_t f, ///< [in] file handle. const char* field_name, ///< [in] field name. - const h5_float64_t x_origin, ///< [in] X origin. - const h5_float64_t y_origin, ///< [in] Y origin. - const h5_float64_t z_origin ///< [in] Z origin. + const h5_float64_t x_spacing, ///< [in] X spacing. + const h5_float64_t y_spacing, ///< [in] Y spacing. + const h5_float64_t z_spacing ///< [in] Z spacing. ) { H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', x_origin=%g, y_origin=%g, z_origin=%g", - (h5_file_p)f, field_name, x_origin, y_origin, z_origin); - h5_float64_t origin[3] = { x_origin, y_origin, z_origin }; + "f=%p, field_name='%s', " + "x_spacing=%g, y_spacing=%g, z_spacing=%g", + (h5_file_p)f, field_name, + x_spacing, y_spacing, z_spacing); + h5_float64_t spacing[3] = { x_spacing, y_spacing, z_spacing }; H5_API_RETURN (h5b_write_field_attrib ( f, field_name, - H5BLOCK_FIELD_ORIGIN_NAME, + H5BLOCK_FIELD_SPACING_NAME, (hid_t)H5_FLOAT64_T, - origin, + spacing, 3)); } -/* - ! __ _ _ _ _ - ! / _(_) ___| | __| | ___ _ __ __ _ ___(_)_ __ __ _ - ! | |_| |/ _ \ |/ _` | / __| '_ \ / _` |/ __| | '_ \ / _` | - ! | _| | __/ | (_| | \__ \ |_) | (_| | (__| | | | | (_| | - ! |_| |_|\___|_|\__,_| |___/ .__/ \__,_|\___|_|_| |_|\__, | - ! |_| |___/ -*/ - /** Get field spacing for field \c field_name in the current time step. @@ -585,56 +292,49 @@ H5Block3dGetFieldSpacing ( } /** - Set field spacing for field \c field_name in the current time step. + \fn h5_err_t H5Block3dSetFieldXCoords ( + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords + ) - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dSetFieldSpacing ( - const h5_file_t f, ///< [in] file handle. - const char* field_name, ///< [in] field name. - const h5_float64_t x_spacing, ///< [in] X spacing. - const h5_float64_t y_spacing, ///< [in] Y spacing. - const h5_float64_t z_spacing ///< [in] Z spacing. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, field_name='%s', x_spacing=%g, y_spacing=%g, z_spacing=%g", - (h5_file_p)f, field_name, x_spacing, y_spacing, z_spacing); - h5_float64_t spacing[3] = { x_spacing, y_spacing, z_spacing }; - H5_API_RETURN (h5b_write_field_attrib ( - f, - field_name, - H5BLOCK_FIELD_SPACING_NAME, - (hid_t)H5_FLOAT64_T, - spacing, - 3)); -} + \fn h5_err_t H5Block3dSetFieldYCoords ( + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords + ) -/* - ! __ _ _ _ _ - ! / _(_) ___| | __| | ___ ___ ___ _ __ __| |___ - ! | |_| |/ _ \ |/ _` | / __/ _ \ / _ \| '__/ _` / __| - ! | _| | __/ | (_| | | (_| (_) | (_) | | | (_| \__ \ - ! |_| |_|\___|_|\__,_| \___\___/ \___/|_| \__,_|___/ -*/ -/** - Set an explicit list of X coordinates for field \c field_name in the current - time step. The coordinates are a 1D array of floating point values with - dimension \c n_coords. + \fn h5_err_t H5Block3dSetFieldZCoords ( + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords + ) - By convention, the \c coords array should have the same length as the X - dimension of the field, and a warning will be printed if not. + Set an explicit list of X,Y respective Z coordinates for field \c + field_name in the current time step. The coordinates are a 1D array + of floating point values with dimension \c n_coords. + + By convention, the \c coords array should have the same length as + the X, Y respective Z dimension of the field. A warning will be + printed if not. + + \param f [in] file handle + \param field_name [in] field name + \param coords [in] X, Y or Z coordinates + \param n_coords [in] number of coordinates \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldXCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - const h5_float64_t* const coords,///< [in] X coordinates - const h5_int64_t n_coords ///< [in] number of coordinates + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords ) { H5_API_ENTER (h5_err_t, "f=%p, " @@ -648,24 +348,88 @@ H5Block3dSetFieldXCoords ( coords, n_coords)); } +static inline h5_err_t +H5Block3dSetFieldYCoords ( + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "field_name='%s', " + "coords=%p, n_coords=%llu", + (h5_file_p)f, + field_name, + coords, (long long unsigned)n_coords); + H5_API_RETURN (h5b_set_3d_field_coords ( + f, 1, field_name, H5BLOCK_FIELD_YCOORD_NAME, + coords, n_coords)); +} + +static inline h5_err_t +H5Block3dSetFieldZCoords ( + const h5_file_t f, + const char* field_name, + const h5_float64_t* const coords, + const h5_int64_t n_coords + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "field_name='%s', " + "coords=%p, n_coords=%llu", + (h5_file_p)f, + field_name, + coords, (long long unsigned)n_coords); + H5_API_RETURN (h5b_set_3d_field_coords ( + f, 2, field_name, H5BLOCK_FIELD_ZCOORD_NAME, + coords, n_coords)); +} /** - Get the explicit list of X coordinates for field \c field_name in the current - time step. The coordinates are read into the 1D array \c coords which has - length \c n_coords. + \fn h5_err_t H5Block3dGetFieldXCoords ( + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords + ) - By convention, the \c coords array should have the same length as the X - dimension of the field, and a warning will be printed if they differ. + \fn h5_err_t H5Block3dGetFieldYCoords ( + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords + ) + + \fn h5_err_t H5Block3dGetFieldZCoords ( + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords + ) + + Get the explicit list of X, Y respective Z coordinates for field \c + field_name in the current step. The coordinates are read into the 1D + array \c coords which has length \c n_coords. + + By convention, the \c coords array should have the same length as + the X, Y respective Z dimension of the field. A warning will be + printed if they differ. + + \param f [in] file handle + \param field_name [in] field name + \param coords [in] X, Y or Z coordinates + \param n_coords [in] number of coordinates \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldXCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - h5_float64_t* const coords, ///< [in] X coordinates - const h5_int64_t n_coords ///< [in] number of coordinates + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords ) { H5_API_ENTER (h5_err_t, "f=%p, " @@ -679,50 +443,12 @@ H5Block3dGetFieldXCoords ( coords, n_coords)); } -/** - Set an explicit list of Y coordinates for field \c field_name in the current - time step. - - \see H5Block3dSetFieldXCoords() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dSetFieldYCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - const h5_float64_t* const coords,///< [in] X coordinates - const h5_int64_t n_coords ///< [in] number of coordinates - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "field_name='%s', " - "coords=%p, n_coords=%llu", - (h5_file_p)f, - field_name, - coords, (long long unsigned)n_coords); - H5_API_RETURN (h5b_set_3d_field_coords ( - f, 1, field_name, H5BLOCK_FIELD_YCOORD_NAME, - coords, n_coords)); -} - - -/** - Get the explicit list of Y coordinates for field \c field_name in the current - time step. - - \see H5Block3dGetFieldXCoords() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5Block3dGetFieldYCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - h5_float64_t* const coords, ///< [in] Y coordinates - const h5_int64_t n_coords ///< [in] number of coordinates + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords ) { H5_API_ENTER (h5_err_t, "f=%p, " @@ -736,50 +462,12 @@ H5Block3dGetFieldYCoords ( coords, n_coords)); } -/** - Set an explicit list of Z coordinates for field \c field_name in the current - time step. - - \see H5Block3dSetFieldXCoords() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dSetFieldZCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - const h5_float64_t* const coords,///< [in] Z coordinates - const h5_int64_t n_coords ///< [in] number of coordinates - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "field_name='%s', " - "coords=%p, n_coords=%llu", - (h5_file_p)f, - field_name, - coords, (long long unsigned)n_coords); - H5_API_RETURN (h5b_set_3d_field_coords ( - f, 2, field_name, H5BLOCK_FIELD_ZCOORD_NAME, - coords, n_coords)); -} - - -/** - Get the explicit list of Y coordinates for field \c field_name in the current - time step. - - \see H5Block3dGetFieldXCoords() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5Block3dGetFieldZCoords ( - const h5_file_t f, ///< [in] file handle - const char* field_name, ///< [in] field name - h5_float64_t* const coords, ///< [in] Z coordinates - const h5_int64_t n_coords ///< [in] number of coordinates + const h5_file_t f, + const char* field_name, + h5_float64_t* const coords, + const h5_int64_t n_coords ) { H5_API_ENTER (h5_err_t, "f=%p, " @@ -793,9 +481,359 @@ H5Block3dGetFieldZCoords ( coords, n_coords)); } +/* + ! _ _ + ! __ ___ __(_) |_ ___ + ! \ \ /\ / / '__| | __/ _ \ + ! \ V V /| | | | || __/ + ! \_/\_/ |_| |_|\__\___| +*/ + +/** + \fn h5_err_t H5BlockWriteFieldAttribString ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const char* buffer + ) + + \fn h5_err_t H5BlockWriteFieldAttribFloat64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_float64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5BlockWriteFieldAttribFloat32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_float32_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5BlockWriteFieldAttribInt64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_int64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5BlockWriteFieldAttribInt32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_int32_t* buffer, + const h5_size_t nelems + ) + + Attach an attribute to a given field. + + The type of the attribute can be + - a C string (\c char*) + - an array of 64bit floating point numbers (\c h5_float64_t) + - an array of 32bit floating point numbers (\c h5_float32_t) + - an array of 64bit integers (\c h5_int64_t) + - an array of 32bit integers (\c h5_int32_t) + + \param f file handle + \param field_name name of field the attribute is attached to + \param attrib_name the attribute name + \param buffer data to be written + \param nelems number of elements to be written + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5BlockReadFieldAttribString() + \see H5BlockReadFieldAttribFloat64() + \see H5BlockReadFieldAttribFloat32() + \see H5BlockReadFieldAttribInt64() + \see H5BlockReadFieldAttribInt32() +*/ +static inline h5_err_t +H5BlockWriteFieldAttribString ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const char* buffer + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "field_name='%s', " + "attrib_name='%s', " + "buffer='%s'", + (h5_file_p)f, + field_name, + attrib_name, + buffer); + H5_API_RETURN ( + h5b_write_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_CHAR, + buffer, + strlen(buffer) + 1)); +} + +static inline h5_err_t +H5BlockWriteFieldAttribFloat64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_float64_t* buffer, + const h5_size_t nelems + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', " + "buffer=%p, nelems=%lld", + (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); + H5_API_RETURN (h5b_write_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_DOUBLE, + buffer, + nelems )); +} + +static inline h5_err_t +H5BlockWriteFieldAttribFloat32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_float32_t* buffer, + const h5_size_t nelems + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', " + "buffer=%p, nelems=%lld", + (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); + H5_API_RETURN (h5b_write_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_FLOAT, + buffer, + nelems )); +} + +static inline h5_err_t +H5BlockWriteFieldAttribInt64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_int64_t* buffer, + const h5_size_t nelems + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', buffer=%p, nelems=%lld", + (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); + H5_API_RETURN (h5b_write_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_INT64, + buffer, + nelems )); +} + +static inline h5_err_t +H5BlockWriteFieldAttribInt32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + const h5_int32_t* buffer, + const h5_size_t nelems + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', " + "buffer=%p, nelems=%lld", + (h5_file_p)f, field_name, attrib_name, buffer, (long long)nelems); + H5_API_RETURN (h5b_write_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_INT32, + buffer, + nelems )); +} + +/* + ! _ + ! _ __ ___ __ _ __| | + ! | '__/ _ \/ _` |/ _` | + ! | | | __/ (_| | (_| | + ! |_| \___|\__,_|\__,_| + */ + + +/** + \fn h5_err_t H5BlockReadFieldAttribString ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + char* buffer + ) + + \fn h5_err_t H5BlockReadFieldAttribFloat64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_float64_t* buffer + ) + + \fn h5_err_t H5BlockReadFieldAttribFloat32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_float32_t* buffer + ) + + \fn h5_err_t H5BlockReadFieldAttribInt64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_int64_t* buffer + ) + + \fn h5_err_t H5BlockReadFieldAttribInt32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_int32_t* buffer + ) + + Read attribute attached to a given field. + + \note Make sure that the size of the buffer is large enough! + + \param f [in] file handle + \param field_name [in] name of field the attribute is attached to + \param attrib_name [in] attribute name + \param buffer [out] buffer for data to be read + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5BlockGetFieldAttribInfo() + \see H5BlockGetFieldAttribInfoByName() + \see H5BlockWriteFieldAttribString() + \see H5BlockReadFieldAttribFloat64() + \see H5BlockReadFieldAttribFloat32() + \see H5BlockReadFieldAttribInt64() + \see H5BlockReadFieldAttribInt32() + */ +static inline h5_err_t +H5BlockReadFieldAttribString ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + char* buffer + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "field_name='%s', " + "attrib_name='%s', " + "buffer=%p", + (h5_file_p)f, + field_name, + attrib_name, + buffer); + H5_API_RETURN ( + h5b_read_field_attrib ( + f, + field_name, + attrib_name, + H5_STRING_T, + (void*)buffer)); +} + +static inline h5_err_t +H5BlockReadFieldAttribFloat64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_float64_t* buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', buffer=%p", + (h5_file_p)f, field_name, attrib_name, buffer); + H5_API_RETURN (h5b_read_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_DOUBLE, + (void*)buffer )); +} + +static inline h5_err_t +H5BlockReadFieldAttribFloat32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_float32_t* const buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', buffer=%p", + (h5_file_p)f, field_name, attrib_name, buffer); + H5_API_RETURN (h5b_read_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_FLOAT, + buffer )); +} + +static inline h5_err_t +H5BlockReadFieldAttribInt64 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_int64_t* const buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', buffer=%p", + (h5_file_p)f, field_name, attrib_name, buffer); + H5_API_RETURN (h5b_read_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_INT64, + buffer )); +} + +static inline h5_err_t +H5BlockReadFieldAttribInt32 ( + const h5_file_t f, + const char* field_name, + const char* attrib_name, + h5_int32_t* buffer + ) { + H5_API_ENTER (h5_err_t, + "f=%p, field_name='%s', attrib_name='%s', buffer=%p", + (h5_file_p)f, field_name, attrib_name, buffer); + H5_API_RETURN (h5b_read_field_attrib ( + f, + field_name, + attrib_name, + H5T_NATIVE_INT32, + (void*)buffer )); +} +///< @} + #ifdef __cplusplus } #endif -///< @} #endif diff --git a/src/include/H5Block_io.h b/src/include/H5Block_io.h index 3729796..cb818e2 100644 --- a/src/include/H5Block_io.h +++ b/src/include/H5Block_io.h @@ -15,32 +15,203 @@ #include "h5core/h5_debug.h" #include "h5core/h5b_io.h" +#ifdef __cplusplus +extern "C" { +#endif + +/* + ! _ _ + ! (_)_ __ __ _ _ _(_)_ __ ___ + ! | | '_ \ / _` | | | | | '__/ _ \ + ! | | | | | (_| | |_| | | | | __/ + ! |_|_| |_|\__, |\__,_|_|_| \___| + ! |_| + ! +*/ + + /** \addtogroup h5block_io @{ */ -#ifdef __cplusplus -extern "C" { -#endif +/** + Query number of fields in current time step. + + \return \c number of fields + \return H5_FAILURE on error +*/ +static inline h5_ssize_t +H5BlockGetNumFields ( + const h5_file_t f ///< [in] file handle. + ) { + H5_API_ENTER (h5_ssize_t, + "f=%p", + (h5_file_p)f); + H5_API_RETURN (h5b_get_num_fields(f)); +} /** - Write the 3-dimensional field \p name from the buffer pointed to by - \p buffer to the current step using the previously defined field - view. + Get the name, rank and dimensions of the field specified by the + index \c idx. - The data type is 64bit floating point (\c h5_float64_t). Ensure that - the number of items in the buffer matches the view. Use the FORTRAN - indexing scheme to store data in the buffer. + \c elem_rank reports the rank of the elements in the field + (e.g. scalar or vector). + + This function can be used to retrieve all fields bound to the + current time-step by looping from \c 0 to the number of fields + minus one. The number of fields bound to the current time-step + can be queried by calling the function \ref H5BlockGetNumFields. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t +H5BlockGetFieldInfo ( + const h5_file_t f, ///< [in] file handle + const h5_size_t idx, ///< [in] index of field + char* name, ///< [out] field name + const h5_size_t len_name, ///< [in] buffer size + h5_size_t* field_rank, ///< [out] field rank + h5_size_t* field_dims, ///< [out] field dimensions + h5_size_t* elem_rank, ///< [out] element rank + h5_int64_t* type ///< [out] datatype + ) { + H5_API_ENTER (h5_err_t, + "f=%p, idx=%llu, " + "name=%p, len_name=%llu, " + "field_rank=%p, field_dims=%p, elem_rank=%p, type=%p", + (h5_file_p)f, (long long unsigned)idx, + name, (long long unsigned)len_name, + field_rank, field_dims, elem_rank, + type); + H5_API_RETURN ( + h5b_get_field_info ( + f, + idx, + name, + len_name, + field_rank, + field_dims, + elem_rank, + type)); +} + +/** + Determines whether a field with a given name exists. + + \return true (value \c >0) if atrribute exists + \return false (\c 0) if attribute does not exist + \return \c H5_FAILURE on error + */ +static inline h5_err_t +H5BlockHasField ( + const h5_file_t f, ///< [in] file handle + const char* name ///< [in] field name + ) { + H5_API_ENTER (h5_err_t, + "f=%p, name='%s'", + (h5_file_p)f, name); + H5_API_RETURN ( + h5b_has_field ( + f, + name)); +} + +/** + Get the rank and dimensions of the field specified by its name. + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5BlockGetFieldInfo. +*/ +static inline h5_err_t +H5BlockGetFieldInfoByName ( + const h5_file_t f, ///< [in] file handle + const char* name, ///< [in] field name + h5_size_t* field_rank, ///< [out] field rank + h5_size_t* field_dims, ///< [out] field dimensions + h5_size_t* elem_rank, ///< [out] element rank + h5_int64_t* type ///< [out] datatype + ) { + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', " + "field_rank=%p, field_dims=%p, elem_rank=%p, type=%p", + (h5_file_p)f, name, field_rank, field_dims, elem_rank, type); + H5_API_RETURN ( + h5b_get_field_info_by_name ( + f, + name, + field_rank, + field_dims, + elem_rank, + type)); +} + +/* + ! _ _ _ + ! __ ___ __(_) |_ ___ ___ ___ __ _| | __ _ _ __ + ! \ \ /\ / / '__| | __/ _ \ / __|/ __/ _` | |/ _` | '__| + ! \ V V /| | | | || __/ \__ \ (_| (_| | | (_| | | + ! \_/\_/ |_| |_|\__\___| |___/\___\__,_|_|\__,_|_| +*/ + +/** + \fn h5_err_t H5Block3dWriteScalarFieldFloat64 ( + const h5_file_t f, + const char* name, + const h5_float64_t* buffer + ) + + \fn h5_err_t H5Block3dWriteScalarFieldFloat32 ( + const h5_file_t f, + const char* name, + const h5_float32_t* buffer + ) + + \fn h5_err_t H5Block3dWriteScalarFieldInt64 ( + const h5_file_t f, + const char* name, + const h5_int64_t* buffer + ) + + \fn h5_err_t H5Block3dWriteScalarFieldInt32 ( + const h5_file_t f, + const char* name, + const h5_int32_t* buffer + ) + + Write a 3-dimensional field with scalar values to the current step + using the previously defined field view. Ensure that the size of + the buffer matches the number of elements in the view. + + Supported data types are + + - 64-bit floating point (\c h5_float64_t) + - 32-bit floating point (\c h5_float32_t) + - 64-bit integer (\c h5_int64_t) + - 32-bit integer (\c h5_int32_t) + + \note Use the FORTRAN indexing scheme to store data in the buffer. + + \param f [in] file handle + \param name [in] name of field to be written + \param buffer [in] data to be written + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5Block3dReadScalarFieldFloat64() + \see H5Block3dReadScalarFieldFloat32() + \see H5Block3dReadScalarFieldInt64() + \see H5Block3dReadScalarFieldInt32() +*/ +static inline h5_err_t H5Block3dWriteScalarFieldFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_float64_t* buffer ///< [in] pointer to buffer containing data to write. + const h5_file_t f, + const char* name, + const h5_float64_t* buffer ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', buffer=%p", @@ -48,22 +219,98 @@ H5Block3dWriteScalarFieldFloat64 ( H5_API_RETURN (h5b_write_scalar_data(f, name, (void*)buffer, H5T_NATIVE_DOUBLE )); } -/** - Read the 3-dimensional field \c name into the buffer pointed to by - \p buffer from the current tep using the defined field layout. +static inline h5_err_t +H5Block3dWriteScalarFieldFloat32 ( + const h5_file_t f, + const char* name, + const h5_float32_t* buffer + ) { - The data type is 64bit floating point (\c h5_float64_t). Ensure that - the number of items in the buffer matches the view. Use the FORTRAN - indexing scheme to access data in the buffer. + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT )); +} + +static inline h5_err_t +H5Block3dWriteScalarFieldInt64 ( + const h5_file_t f, + const char* name, + const h5_int64_t* buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT64 )); +} + +static inline h5_err_t +H5Block3dWriteScalarFieldInt32 ( + const h5_file_t f, + const char* name, + const h5_int32_t* buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT32 )); +} + +/* + ! _ _ + ! _ __ ___ __ _ __| | ___ ___ __ _| | __ _ _ __ + ! | '__/ _ \/ _` |/ _` | / __|/ __/ _` | |/ _` | '__| + ! | | | __/ (_| | (_| | \__ \ (_| (_| | | (_| | | + ! |_| \___|\__,_|\__,_| |___/\___\__,_|_|\__,_|_| +*/ + +/** + \fn h5_err_t H5Block3dReadScalarFieldFloat64 ( + const h5_file_t f, + const char* name, + h5_float64_t* buffer + ) + + \fn h5_err_t H5Block3dReadScalarFieldFloat32 ( + const h5_file_t f, + const char* name, + h5_float32_t* buffer + ) + + \fn h5_err_t H5Block3dReadScalarFieldInt64 ( + const h5_file_t f, + const char* name, + h5_int64_t* buffer + ) + + \fn h5_err_t H5Block3dReadScalarFieldInt32 ( + const h5_file_t f, + const char* name, + h5_int32_t* buffer + ) + + Read a 3-dimensional field with scalar values from the current step + using the previously defined field layout. + + Ensure that the size of the buffer matches the number of elements in + the view. + + \note Use the FORTRAN indexing scheme to store data in the buffer. + + \param f [in] file handle + \param name [in] name of field to be read + \param buffer [out] buffer for data to be read \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadScalarFieldFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to read. - h5_float64_t* buffer ///< [out] pointer to read buffer. + const h5_file_t f, + const char* name, + h5_float64_t* buffer ) { H5_API_ENTER (h5_err_t, @@ -72,24 +319,120 @@ H5Block3dReadScalarFieldFloat64 ( H5_API_RETURN (h5b_read_scalar_data(f, name, (void*)buffer, H5T_NATIVE_DOUBLE)); } -/** - Write the 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with floating points (64-bit) values. +static inline h5_err_t +H5Block3dReadScalarFieldFloat32 ( + const h5_file_t f, + const char* name, + h5_float32_t* const buffer + ) { - You must use the Fortran indexing scheme to access items in \c x_buf. + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT)); +} + +static inline h5_err_t +H5Block3dReadScalarFieldInt64 ( + const h5_file_t f, + const char* name, + h5_int64_t* const buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_INT64)); +} + +static inline h5_err_t +H5Block3dReadScalarFieldInt32 ( + const h5_file_t f, + const char* name, + h5_int32_t* const buffer + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', buffer=%p", + (h5_file_p)f, name, buffer); + H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_INT32)); +} + +/* + ! _ _ _____ _ _ + ! __ ___ __(_) |_ ___ |___ / __| | __ _____ ___| |_ ___ _ __ + ! \ \ /\ / / '__| | __/ _ \ |_ \ / _` | \ \ / / _ \/ __| __/ _ \| '__| + ! \ V V /| | | | || __/ ___) | (_| | \ V / __/ (__| || (_) | | + ! \_/\_/ |_| |_|\__\___| |____/ \__,_| \_/ \___|\___|\__\___/|_| + */ + +/** + \fn h5_err_t H5Block3dWriteVector3dFieldFloat64 ( + const h5_file_t f, + const char* name, + const h5_float64_t* x_buf, + const h5_float64_t* y_buf, + const h5_float64_t* z_buf + ) + + \fn h5_err_t H5Block3dWriteVector3dFieldFloat32 ( + const h5_file_t f, + const char* name, + const h5_float32_t* x_buf, + const h5_float32_t* y_buf, + const h5_float32_t* z_buf + ) + + \fn h5_err_t H5Block3dWriteVector3dFieldInt64 ( + const h5_file_t f, + const char* name, + const h5_int64_t* x_buf, + const h5_int64_t* y_buf, + const h5_int64_t* z_buf + ) + \fn h5_err_t H5Block3dWriteVector3dFieldInt32 ( + const h5_file_t f, + const char* name, + const h5_int32_t* x_buf, + const h5_int32_t* y_buf, + const h5_int32_t* z_buf + ) + + Write a 3-dimensional field with 3-dimensional vectors as values to + the current step using the previously defined field view. Ensure + that the size of the buffer matches the number of elements in the + view. + + Supported data types are + + - 64-bit floating point (\c h5_float64_t) + - 32-bit floating point (\c h5_float32_t) + - 64-bit integer (\c h5_int64_t) + - 32-bit integer (\c h5_int32_t) + + \note Use the FORTRAN indexing scheme to store data in the buffer. + + \param f [in] file handle. + \param name [in] name of field to be written + \param x_buf [in] pointer to buffer with X axis data + \param y_buf [in] pointer to buffer with Y axis data + \param z_buf [in] pointer to buffer with Y axis data \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \see H5Block3dReadVector3dFieldFloat64() + \see H5Block3dReadVector3dFieldFloat32() + \see H5Block3dReadVector3dFieldInt64() + \see H5Block3dReadVector3dFieldInt32() */ static inline h5_err_t H5Block3dWriteVector3dFieldFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_float64_t* x_buf, ///< [in] pointer to X axis buffer. - const h5_float64_t* y_buf, ///< [in] pointer to Y axis buffer. - const h5_float64_t* z_buf ///< [in] pointer to Z axis buffer. + const h5_file_t f, + const char* name, + const h5_float64_t* x_buf, + const h5_float64_t* y_buf, + const h5_float64_t* z_buf ) { H5_API_ENTER (h5_err_t, @@ -99,98 +442,13 @@ H5Block3dWriteVector3dFieldFloat64 ( (void*)x_buf, (void*)y_buf, (void*)z_buf, H5T_NATIVE_DOUBLE)); } -/** - Read a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with floating points (64-bit) values. - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadVector3dFieldFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - h5_float64_t* const x_buf, ///< [out] pointer to X axis buffer. - h5_float64_t* const y_buf, ///< [out] pointer to Y axis buffer. - h5_float64_t* const z_buf ///< [out] pointer to Z axis buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", - (h5_file_p)f, name, x_buf, y_buf, z_buf); - H5_API_RETURN(h5b_read_vector3d_data(f, name, - x_buf, y_buf, z_buf, H5T_NATIVE_DOUBLE)); -} - - -/** - Write a 3-dimensional field \c name from the buffer starting at \c data - to the current time-step using the defined field layout. Values are - floating points (32-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dWriteScalarFieldFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_float32_t* buffer ///< [in] pointer to write buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT )); -} - -/** - Read a 3-dimensional field \c name into the buffer starting at \c data from - the current time-step using the defined field layout. Values are - floating points (32-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadScalarFieldFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to read. - h5_float32_t* const buffer ///< [out] pointer to read buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT)); -} - -/** - Write a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with floating points (32-bit) values. - - You must use the Fortran indexing scheme to access items in \c x_buf. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5Block3dWriteVector3dFieldFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_float32_t* x_buf, ///< [in] pointer to X axis buffer. - const h5_float32_t* y_buf, ///< [in] pointer to Y axis buffer. - const h5_float32_t* z_buf ///< [in] pointer to Z axis buffer. + const h5_file_t f, + const char* name, + const h5_float32_t* x_buf, + const h5_float32_t* y_buf, + const h5_float32_t* z_buf ) { H5_API_ENTER (h5_err_t, @@ -200,99 +458,13 @@ H5Block3dWriteVector3dFieldFloat32 ( x_buf, y_buf, z_buf, H5T_NATIVE_FLOAT)); } -/** - Read a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with floating points (32-bit) values. - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadVector3dFieldFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - h5_float32_t* const x_buf, ///< [out] pointer to X axis buffer. - h5_float32_t* const y_buf, ///< [out] pointer to Y axis buffer. - h5_float32_t* const z_buf ///< [out] pointer to Z axis buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", - (h5_file_p)f, name, x_buf, y_buf, z_buf); - H5_API_RETURN(h5b_read_vector3d_data(f, name, - x_buf, y_buf, z_buf, H5T_NATIVE_FLOAT)); -} - - -/** - Write a 3-dimensional field \c name from the buffer starting at \c data - to the current time-step using the defined field layout. Values are - integers (64-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dWriteScalarFieldInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_int64_t* buffer ///< [in] pointer to write buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT64 )); -} - -/** - Read a 3-dimensional field \c name into the buffer starting at \c data from - the current time-step using the defined field layout. Values are - integers (64-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadScalarFieldInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to read. - h5_int64_t* const buffer ///< [out] pointer to read buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_INT64)); -} - - -/** - Write a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with integers (64-bit) values. - - You must use the Fortran indexing scheme to access items in \c x_buf. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5Block3dWriteVector3dFieldInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_int64_t* x_buf, ///< [in] pointer to X axis buffer. - const h5_int64_t* y_buf, ///< [in] pointer to Y axis buffer. - const h5_int64_t* z_buf ///< [in] pointer to Z axis buffer. + const h5_file_t f, + const char* name, + const h5_int64_t* x_buf, + const h5_int64_t* y_buf, + const h5_int64_t* z_buf ) { H5_API_ENTER (h5_err_t, @@ -302,99 +474,13 @@ H5Block3dWriteVector3dFieldInt64 ( x_buf, y_buf, z_buf, H5T_NATIVE_INT64)); } -/** - Read a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with integers (64-bit) values. - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadVector3dFieldInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - h5_int64_t* const x_buf, ///< [out] pointer to X axis buffer. - h5_int64_t* const y_buf, ///< [out] pointer to Y axis buffer. - h5_int64_t* const z_buf ///< [out] pointer to Z axis buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", - (h5_file_p)f, name, x_buf, y_buf, z_buf); - H5_API_RETURN (h5b_read_vector3d_data(f, name, - x_buf, y_buf, z_buf, H5T_NATIVE_INT64)); -} - - -/** - Write a 3-dimensional field \c name from the buffer starting at \c data - to the current time-step using the defined field layout. Values are - integers (32-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dWriteScalarFieldInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_int32_t* buffer ///< [in] pointer to write buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT32 )); -} - -/** - Read a 3-dimensional field \c name into the buffer starting at \c data from - the current time-step using the defined field layout. Values are - integers (32-bit). - - You must use the Fortran indexing scheme to access items in \c data. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5Block3dReadScalarFieldInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to read. - h5_int32_t* const buffer ///< [out] pointer to read buffer. - ) { - - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); - H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_INT32)); -} - - -/** - Write a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with integers (32-bit) values. - - You must use the Fortran indexing scheme to access items in \c x_buf. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5Block3dWriteVector3dFieldInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - const h5_int32_t* x_buf, ///< [in] pointer to X axis buffer. - const h5_int32_t* y_buf, ///< [in] pointer to Y axis buffer. - const h5_int32_t* z_buf ///< [in] pointer to Z axis buffer. + const h5_file_t f, + const char* name, + const h5_int32_t* x_buf, + const h5_int32_t* y_buf, + const h5_int32_t* z_buf ) { H5_API_ENTER (h5_err_t, @@ -404,24 +490,123 @@ H5Block3dWriteVector3dFieldInt32 ( x_buf, y_buf, z_buf, H5T_NATIVE_INT32)); } +/* + ! _ _____ _ _ + ! _ __ ___ __ _ __| | |___ / __| | __ _____ ___| |_ ___ _ __ + ! | '__/ _ \/ _` |/ _` | |_ \ / _` | \ \ / / _ \/ __| __/ _ \| '__| + ! | | | __/ (_| | (_| | ___) | (_| | \ V / __/ (__| || (_) | | + ! |_| \___|\__,_|\__,_| |____/ \__,_| \_/ \___|\___|\__\___/|_| + */ /** - Read a 3-dimensional field \c name with 3-dimensional vectors as values - from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the - current time-step using the defined field layout. Values are 3-dimensional - vectors with integers (32-bit) values. + \fn h5_err_t H5Block3dReadVector3dFieldFloat64 ( + const h5_file_t f, + const char* name, + h5_float64_t* const x_buf, + h5_float64_t* const y_buf, + h5_float64_t* const z_buf + ) - You must use the Fortran indexing scheme to access items in \c data. + \fn h5_err_t H5Block3dReadVector3dFieldFloat32 ( + const h5_file_t f, + const char* name, + h5_float32_t* const x_buf, + h5_float32_t* const y_buf, + h5_float32_t* const z_buf + ) + + \fn h5_err_t H5Block3dReadVector3dFieldInt64 ( + const h5_file_t f, + const char* name, + h5_int64_t* const x_buf, + h5_int64_t* const y_buf, + h5_int64_t* const z_buf + ) + + \fn h5_err_t H5Block3dReadVector3dFieldInt32 ( + const h5_file_t f, + const char* name, + h5_int32_t* const x_buf, + h5_int32_t* const y_buf, + h5_int32_t* const z_buf + ) + + Read a 3-dimensional field with 3-dimensional vectors as values from + the current step using the previously defined field layout. + + Ensure that the size of the buffer matches the number of elements in + the view. + + \note Use the FORTRAN indexing scheme to store data in the buffer. + + \param f [in] file handle + \param name [in] name of field to be read + \param x_buf [in] buffer for X axis data to be read + \param y_buf [in] buffer for Y axis data to be read + \param z_buf [in] buffer for Z axis data to be read \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \see H5Block3dWriteVector3dFieldFloat64() + \see H5Block3dWriteVector3dFieldFloat32() + \see H5Block3dWriteVector3dFieldInt64() + \see H5Block3dWriteVector3dFieldInt32() */ +static inline h5_err_t +H5Block3dReadVector3dFieldFloat64 ( + const h5_file_t f, + const char* name, + h5_float64_t* const x_buf, + h5_float64_t* const y_buf, + h5_float64_t* const z_buf + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", + (h5_file_p)f, name, x_buf, y_buf, z_buf); + H5_API_RETURN(h5b_read_vector3d_data(f, name, + x_buf, y_buf, z_buf, H5T_NATIVE_DOUBLE)); +} + +static inline h5_err_t +H5Block3dReadVector3dFieldFloat32 ( + const h5_file_t f, + const char* name, + h5_float32_t* const x_buf, + h5_float32_t* const y_buf, + h5_float32_t* const z_buf + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", + (h5_file_p)f, name, x_buf, y_buf, z_buf); + H5_API_RETURN(h5b_read_vector3d_data(f, name, + x_buf, y_buf, z_buf, H5T_NATIVE_FLOAT)); +} + +static inline h5_err_t +H5Block3dReadVector3dFieldInt64 ( + const h5_file_t f, + const char* name, + h5_int64_t* const x_buf, + h5_int64_t* const y_buf, + h5_int64_t* const z_buf + ) { + + H5_API_ENTER (h5_err_t, + "f=%p, name='%s', x_buf=%p, y_buf=%p, z_buf=%p", + (h5_file_p)f, name, x_buf, y_buf, z_buf); + H5_API_RETURN (h5b_read_vector3d_data(f, name, + x_buf, y_buf, z_buf, H5T_NATIVE_INT64)); +} + static inline h5_err_t H5Block3dReadVector3dFieldInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name of dataset to write. - h5_int32_t* const x_buf, ///< [out] pointer to X axis buffer. - h5_int32_t* const y_buf, ///< [out] pointer to Y axis buffer. - h5_int32_t* const z_buf ///< [out] pointer to Z axis buffer. + const h5_file_t f, + const char* name, + h5_int32_t* const x_buf, + h5_int32_t* const y_buf, + h5_int32_t* const z_buf ) { H5_API_ENTER (h5_err_t, @@ -430,10 +615,10 @@ H5Block3dReadVector3dFieldInt32 ( H5_API_RETURN(h5b_read_vector3d_data(f, name, x_buf, y_buf, z_buf, H5T_NATIVE_INT32)); } +///< @} #ifdef __cplusplus } #endif -///< @} #endif diff --git a/src/include/H5Block_model.h b/src/include/H5Block_model.h index b6034e2..6e0faef 100644 --- a/src/include/H5Block_model.h +++ b/src/include/H5Block_model.h @@ -302,99 +302,6 @@ H5Block3dSetHalo ( H5_API_RETURN (h5b_3d_set_halo(f, i, j, k)); } -/** - Query number of fields in current time step. - - \return \c number of fields - \return H5_FAILURE on error -*/ -static inline h5_ssize_t -H5BlockGetNumFields ( - const h5_file_t f ///< [in] file handle. - ) { - H5_API_ENTER (h5_ssize_t, - "f=%p", - (h5_file_p)f); - H5_API_RETURN (h5b_get_num_fields(f)); -} - - -/** - Get the name, rank and dimensions of the field specified by the - index \c idx. - - \c elem_rank reports the rank of the elements in the field - (e.g. scalar or vector). - - This function can be used to retrieve all fields bound to the - current time-step by looping from \c 0 to the number of fields - minus one. The number of fields bound to the current time-step - can be queried by calling the function \ref H5BlockGetNumFields. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5BlockGetFieldInfo ( - const h5_file_t f, ///< [in] file handle. - const h5_size_t idx, ///< [in] index of field. - char* name, ///< [out] field name. - const h5_size_t len_name, ///< [in] buffer size. - h5_size_t* field_rank, ///< [out] field rank. - h5_size_t* field_dims, ///< [out] field dimensions. - h5_size_t* elem_rank, ///< [out] element rank. - h5_int64_t* type ///< [out] datatype. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, idx=%llu, " - "name=%p, len_name=%llu, " - "field_rank=%p, field_dims=%p, elem_rank=%p, type=%p", - (h5_file_p)f, (long long unsigned)idx, - name, (long long unsigned)len_name, - field_rank, field_dims, elem_rank, - type); - H5_API_RETURN ( - h5b_get_field_info ( - f, - idx, - name, - len_name, - field_rank, - field_dims, - elem_rank, - type)); -} - -/** - Get the rank and dimensions of the field specified by its name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error - - \see H5BlockGetFieldInfo. -*/ -static inline h5_err_t -H5BlockGetFieldInfoByName ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] field name. - h5_size_t* field_rank, ///< [out] field rank. - h5_size_t* field_dims, ///< [out] field dimensions. - h5_size_t* elem_rank, ///< [out] element rank. - h5_int64_t* type ///< [out] datatype. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', " - "field_rank=%p, field_dims=%p, elem_rank=%p, type=%p", - (h5_file_p)f, name, field_rank, field_dims, elem_rank, type); - H5_API_RETURN ( - h5b_get_field_info_by_name ( - f, - name, - field_rank, - field_dims, - elem_rank, - type)); -} #ifdef __cplusplus } diff --git a/src/include/H5Part_io.h b/src/include/H5Part_io.h index b58a51b..5eff1e1 100644 --- a/src/include/H5Part_io.h +++ b/src/include/H5Part_io.h @@ -14,21 +14,181 @@ #include "h5core/h5.h" #include "h5core/h5_debug.h" #include "h5core/h5u_io.h" - -/** - \addtogroup h5part_io - @{ -*/ +#include "h5core/h5u_model.h" #ifdef __cplusplus extern "C" { #endif -/** - Write array of 64 bit floating point data to file. +/* + ! _ _ + ! (_)_ __ __ _ _ _(_)_ __ ___ + ! | | '_ \ / _` | | | | | '__/ _ \ + ! | | | | | (_| | |_| | | | | __/ + ! |_|_| |_|\__, |\__,_|_|_| \___| + ! |_| + ! +*/ - After setting the number of elements with \c H5PartSetNumParticles() and - the current timestep using \c H5SetStep(), you can start writing datasets +/** + \addtogroup h5part_io + @{ +*/ +/** + Get the number of datasets that are stored at the current step. + + \return number of datasets in current timestep + \return \c H5_FAILURE on error +*/ +static inline h5_ssize_t +H5PartGetNumDatasets ( + const h5_file_t f ///< [in] file handle + ) { + H5_API_ENTER (h5_err_t, + "f=%p", + (h5_file_p)f); + H5_API_RETURN (h5u_get_num_datasets(f)); +} + +/** + Query the name of a dataset given by it's index in the current step. + + If the number of datasets is \c n, the range of \c _index is \c 0 to \c n-1. + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error +*/ +static inline h5_err_t +H5PartGetDatasetName ( + const h5_file_t f, ///< [in] file handle + const h5_id_t idx, ///< [in] index of the dataset + char* name, ///< [out] name of dataset + const h5_size_t len ///< [in] size of buffer \c name + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "idx=%lld, " + "name='%p', len=%llu, ", + (h5_file_p)f, + (long long)idx, + name, (unsigned long long)len); + H5_API_RETURN (h5u_get_dataset_info(f, idx, name, len, NULL, NULL)); +} + +/** + Gets the name, type and number of elements of a dataset based on its + index in the current timestep. + + Type is one of the following values: + + - \c H5_FLOAT64_T (for \c h5_float64_t) + - \c H5_FLOAT32_T (for \c h5_float32_t) + - \c H5_INT64_T (for \c h5_int64_t) + - \c H5_INT32_T (for \c h5_int32_t) + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error +*/ +static inline h5_err_t +H5PartGetDatasetInfo ( + const h5_file_t f, ///< [in] file handle + const h5_id_t idx, ///< [in] index of the dataset + char* name, ///< [out] name of dataset + const h5_size_t len_name, ///< [in] size of buffer \c name + h5_int64_t* type, ///< [out] type of data in dataset + h5_size_t* nelems ///< [out] number of elements + ) { + H5_API_ENTER (h5_int64_t, + "f=%p, " + "idx=%lld, " + "name='%p', len_name=%llu, " + "type=%p, nelems=%p", + (h5_file_p)f, + (long long)idx, + name, (long long unsigned)len_name, + type, nelems); + H5_API_RETURN (h5u_get_dataset_info ( + f, idx, name, len_name, type, nelems)); +} + +/** + This function returns the number of particles in this processor's view, + if a view has been set. + + If not, it returns the total number of particles across all processors + from the last \ref H5PartSetNumParticles() call. + + If you have neither set the number of particles + nor set a view, then this returns the total number of + particles in the first data set of the current time step. + Note that H5Part assumes that all data sets within a given time step + have the same number of particles (although the number particles can + vary across time steps). + + If none of these conditions are met, an error is thrown. + + \return number of elements in datasets in current step. + \return \c H5_FAILURE on error. + */ + static inline h5_ssize_t +H5PartGetNumPoints ( + const h5_file_t f ///< [in] file handle. + ) { + H5_API_ENTER (h5_ssize_t, + "f=%p", + (h5_file_p)f); + H5_API_RETURN (h5u_get_num_points (f)); +} + +/** + \see H5PartGetNumPoints() +*/ +static inline h5_ssize_t +H5PartGetNumParticles ( + const h5_file_t f ///< [in] file handle. + ) { + H5_API_ENTER (h5_ssize_t, + "f=%p", + (h5_file_p)f); + H5_API_RETURN (h5u_get_num_points (f)); +} + +/* + ! _ _ + ! __ ___ __(_) |_ ___ + ! \ \ /\ / / '__| | __/ _ \ + ! \ V V /| | | | || __/ + ! \_/\_/ |_| |_|\__\___| +*/ + +/** + \fn h5_err_t H5PartWriteDataFloat64 ( + const h5_file_t f, + const char* name, + const h5_float64_t* data + ) + + \fn h5_err_t H5PartWriteDataFloat32 ( + const h5_file_t f, + const char* name, + const h5_float32_t* data + ) + + \fn h5_err_t H5PartWriteDataInt64 ( + const h5_file_t f, + const char* name, + const h5_int64_t* data + ) + + \fn h5_err_t H5PartWriteDataInt32 ( + const h5_file_t f, + const char* name, + const h5_int32_t* data + ) + + Write a dataset to the current step. + + After the current (time-)step and view, you can start writing datasets into the file. Each dataset has a name associated with it (chosen by the user) in order to facilitate later retrieval. The name of the dataset is specified in the parameter \c name, which must be a null-terminated string. @@ -45,15 +205,23 @@ extern "C" { cannot change the number of elements in the middle of a given timestep. The data is committed to disk before the routine returns. + \param f [in] file handle. + \param name [in] name to associate array with + \param data [in] array to commit to disk. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \see H5PartReadDataFloat64() + \see H5PartReadDataFloat32() + \see H5PartReadDataInt64() + \see H5PartReadDataInt32() */ static inline h5_err_t H5PartWriteDataFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate array with. - const h5_float64_t* data ///< [in] array to commit to disk. + const h5_file_t f, + const char* name, + const h5_float64_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -61,19 +229,11 @@ H5PartWriteDataFloat64 ( H5_API_RETURN (h5u_write_data (f, name, (void*)data, H5T_NATIVE_DOUBLE)); } -/** - Write array of 32 bit floating point data to file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error - */ static inline h5_err_t H5PartWriteDataFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate array with. - const h5_float32_t* data ///< [in] array to commit to disk. + const h5_file_t f, + const char* name, + const h5_float32_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -81,19 +241,11 @@ H5PartWriteDataFloat32 ( H5_API_RETURN (h5u_write_data(f, name, (void*)data, H5T_NATIVE_FLOAT)); } -/** - Write array of 64 bit integer data to file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error - */ static inline h5_err_t H5PartWriteDataInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate array with. - const h5_int64_t* data ///< [in] array to commit to disk. + const h5_file_t f, + const char* name, + const h5_int64_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -101,19 +253,11 @@ H5PartWriteDataInt64 ( H5_API_RETURN (h5u_write_data (f, name, (void*)data, H5T_NATIVE_INT64)); } -/** - Write array of 32 bit integer data to file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error - */ static inline h5_err_t H5PartWriteDataInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate array with. - const h5_int32_t* data ///< [in] array to commit to disk. + const h5_file_t f, + const char* name, + const h5_int32_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -122,18 +266,51 @@ H5PartWriteDataInt32 ( } /** - Read array of 64 bit floating point data from file. + \fn h5_err_t H5PartReadDataFloat64 ( + const h5_file_t f, + const char* name, + h5_float64_t* data + ) - See \ref H5PartWriteDataFloat64() for more details. + \fn h5_err_t H5PartReadDataFloat32 ( + const h5_file_t f, + const char* name, + h5_float32_t* data + ) + + \fn h5_err_t H5PartReadDataInt64 ( + const h5_file_t f, + const char* name, + h5_int64_t* data + ) + + \fn h5_err_t H5PartReadDataInt32 ( + const h5_file_t f, + const char* name, + h5_int32_t* data + ) + + Read dataset from file. + + See \ref H5PartWriteDataFloat64() etc. for more details. + + \param f [in] file handle + \param name [in] name of dataset to be read + \param data [out] buffer for data to be read \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \see H5PartWriteDataFloat64() + \see H5PartWriteDataFloat32() + \see H5PartWriteDataInt64() + \see H5PartWriteDataInt32() */ static inline h5_err_t H5PartReadDataFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate dataset with. - h5_float64_t* data ///< [out] array of data. + const h5_file_t f, + const char* name, + h5_float64_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -141,19 +318,11 @@ H5PartReadDataFloat64 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_DOUBLE)); } -/** - Read array of 32 bit floating point data from file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5PartReadDataFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate dataset with. - h5_float32_t* data ///< [out] array of data. + const h5_file_t f, + const char* name, + h5_float32_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -161,19 +330,11 @@ H5PartReadDataFloat32 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_FLOAT)); } -/** - Read array of 64 bit integer data from file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5PartReadDataInt64 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate dataset with. - h5_int64_t* data ///< [out] array of data. + const h5_file_t f, + const char* name, + h5_int64_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", @@ -181,19 +342,11 @@ H5PartReadDataInt64 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_INT64)); } -/** - Read array of 32 bit integer data from file. - - See \ref H5PartWriteDataFloat64() for more details. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5PartReadDataInt32 ( - const h5_file_t f, ///< [in] file handle. - const char* name, ///< [in] name to associate dataset with. - h5_int32_t* data ///< [out] Array of data. + const h5_file_t f, + const char* name, + h5_int32_t* data ) { H5_API_ENTER (h5_err_t, "f=%p, name='%s', date=%p", diff --git a/src/include/H5Part_model.h b/src/include/H5Part_model.h index 0a78b9f..c72c8d1 100644 --- a/src/include/H5Part_model.h +++ b/src/include/H5Part_model.h @@ -144,125 +144,6 @@ H5PartSetChunkSize ( H5_API_RETURN (h5u_set_chunk (f, size)); } -/** - Get the number of datasets that are stored at the current time-step. - - \return number of datasets in current timestep - \return \c H5_FAILURE on error -*/ -static inline h5_ssize_t -H5PartGetNumDatasets ( - const h5_file_t f ///< [in] file handle. - ) { - H5_API_ENTER (h5_err_t, - "f=%p", - (h5_file_p)f); - H5_API_RETURN (h5u_get_num_datasets(f)); -} - -/** - This reads the name of a dataset specified by it's index in the current - time-step. - - If the number of datasets is \c n, the range of \c _index is \c 0 to \c n-1. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5PartGetDatasetName ( - const h5_file_t f, ///< [in] file handle. - const h5_id_t idx, ///< [in] index of the dataset. - char* name, ///< [out] name of dataset. - const h5_size_t len ///< [in] size of buffer \c name. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "idx=%lld, " - "name='%p', len=%llu, ", - (h5_file_p)f, - (long long)idx, - name, (unsigned long long)len); - H5_API_RETURN (h5u_get_dataset_info(f, idx, name, len, NULL, NULL)); -} - -/** - Gets the name, type and number of elements of a dataset based on its - index in the current timestep. - - Type is one of the following values: - - - \c H5_FLOAT64_T (for \c h5_float64_t) - - \c H5_FLOAT32_T (for \c h5_float32_t) - - \c H5_INT64_T (for \c h5_int64_t) - - \c H5_INT32_T (for \c h5_int32_t) - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5PartGetDatasetInfo ( - const h5_file_t f, ///< [in] file handle. - const h5_id_t idx, ///< [in] index of the dataset. - char* name, ///< [out] name of dataset. - const h5_size_t len_name, ///< [in] size of buffer \c name. - h5_int64_t* type, ///< [out] type of data in dataset. - h5_size_t* nelems ///< [out] number of elements. - ) { - H5_API_ENTER (h5_int64_t, - "f=%p, " - "idx=%lld, " - "name='%p', len_name=%llu, " - "type=%p, nelems=%p", - (h5_file_p)f, - (long long)idx, - name, (long long unsigned)len_name, - type, nelems); - H5_API_RETURN (h5u_get_dataset_info ( - f, idx, name, len_name, type, nelems)); -} - -/** - This function returns the number of particles in this processor's view, - if a view has been set. - - If not, it returns the total number of particles across all processors - from the last \ref H5PartSetNumParticles() call. - - If you have neither set the number of particles - nor set a view, then this returns the total number of - particles in the first data set of the current time step. - Note that H5Part assumes that all data sets within a given time step - have the same number of particles (although the number particles can - vary across time steps). - - If none of these conditions are met, an error is thrown. - - \return number of elements in datasets in current step. - \return \c H5_FAILURE on error. - */ - static inline h5_ssize_t -H5PartGetNumPoints ( - const h5_file_t f ///< [in] file handle. - ) { - H5_API_ENTER (h5_ssize_t, - "f=%p", - (h5_file_p)f); - H5_API_RETURN (h5u_get_num_points (f)); -} - -/** - \see H5PartGetNumPoints() -*/ -static inline h5_ssize_t -H5PartGetNumParticles ( - const h5_file_t f ///< [in] file handle. - ) { - H5_API_ENTER (h5_ssize_t, - "f=%p", - (h5_file_p)f); - H5_API_RETURN (h5u_get_num_points (f)); -} /** Reset the view. diff --git a/src/include/H5_debug.f90 b/src/include/H5_debug.f90 index d15202b..0833498 100644 --- a/src/include/H5_debug.f90 +++ b/src/include/H5_debug.f90 @@ -8,7 +8,7 @@ ! INTERFACE - !> \addtogroup h5_debug_f + !> \addtogroup h5_debug_fvalue !! @{ !> diff --git a/src/include/H5_file.h b/src/include/H5_file.h index bc93b50..67bc6f6 100644 --- a/src/include/H5_file.h +++ b/src/include/H5_file.h @@ -14,11 +14,6 @@ #include "h5core/h5.h" #include "h5core/h5_debug.h" -/** - \addtogroup h5_file - @{ -*/ - #ifdef __cplusplus extern "C" { #endif @@ -29,6 +24,11 @@ extern "C" { #define H5OpenFile1 H5OpenFile #endif +/** + \addtogroup h5_file + @{ +*/ + /** Create a new, empty file property list. diff --git a/src/include/H5_file_attribs.h b/src/include/H5_file_attribs.h index 8bdc477..036b1b5 100644 --- a/src/include/H5_file_attribs.h +++ b/src/include/H5_file_attribs.h @@ -17,81 +17,27 @@ #include "h5core/h5_debug.h" #include "h5core/h5_attribs.h" -/** - \addtogroup h5_file_attribs - @{ -*/ - #ifdef __cplusplus extern "C" { #endif /* - __ _ _ _ _ _ _ _ - / _(_) | ___ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ - | |_| | |/ _ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| - | _| | | __/ | (_| | |_| |_| | | | |_) | |_| | || __/\__ \ - |_| |_|_|\___| \__,_|\__|\__|_| |_|_.__/ \__,_|\__\___||___/ - - __ _ _ _ ___ _ __ _ _ - / _` | | | |/ _ \ '__| | | | - | (_| | |_| | __/ | | |_| | - \__, |\__,_|\___|_| \__, | - |_| |___/ + ! _ _ + ! (_)_ __ __ _ _ _(_)_ __ ___ + ! | | '_ \ / _` | | | | | '__/ _ \ + ! | | | | | (_| | |_| | | | | __/ + ! |_|_| |_|\__, |\__,_|_|_| \___| + ! |_| + ! */ /** - Determines whether a file attribute with a given name exists. - - \return true (value \c >0) if atrribute exists - \return false (\c 0) if attribute does not exist - \return \c H5_FAILURE on error - */ -static inline h5_err_t -H5HasFileAttrib ( - const h5_file_t f, ///< [in] file handle - const char* const name ///< [in] name of attribute to query - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "name=%p", - (h5_file_p)f, - name); - H5_API_RETURN ( - h5_has_file_attrib ( - f, - name)); -} - -/** - Get the type and number of elements of the file attribute - given by its name. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error + \addtogroup h5_file_attribs + @{ */ -static inline h5_err_t -H5GetFileAttribInfoByName ( - const h5_file_t f, ///< [in] file handle. - const char* const name, ///< [in] name of attribute. - h5_int64_t* type, ///< [out] type of value.. - h5_size_t* nelems ///< [out] number of elements. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, " - "name=%s, " - "type=%p, nelems=%p", - (h5_file_p)f, - name, - type, nelems); - H5_API_RETURN (h5_get_file_attrib_info_by_name ( - f, - name, - type, nelems)); -} /** - Gets the number of attributes in the file's root ("/"). + Query the number of attributes attached to the file's root ("/"). \return Number of attributes \return \c H5_FAILURE on error @@ -100,7 +46,7 @@ H5GetFileAttribInfoByName ( */ static inline h5_int64_t H5GetNumFileAttribs ( - const h5_file_t f ///< [in] file handle. + const h5_file_t f ///< [in] file handle ) { H5_API_ENTER (h5_int64_t, "f=%p", @@ -113,297 +59,388 @@ H5GetNumFileAttribs ( given by its index. This function can be used to retrieve all attributes bound to the - file \c f by looping from \c 0 to the number of attribute minus - one. The number of attributes bound to file \c f can be queried - by calling \ref H5GetNumFileAttribs. + file \c f by looping from \c 0 to the number of attribute minus one. + The number of attributes attached to the file \c f can be queried by + calling \ref H5GetNumFileAttribs(). \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5GetFileAttribInfo ( - const h5_file_t f, ///< [in] file handle. + const h5_file_t f, ///< [in] file handle const h5_size_t idx, ///< [in] index of attribute to query - char* name, ///< [out] name of attribute. - const h5_size_t len_name, ///< [in] length of buffer \c name. - h5_int64_t* type, ///< [out] type of value.. - h5_size_t* nelems ///< [out] number of elements. + char* attrib_name, ///< [out] name of attribute + const h5_size_t len_attrib_name,///< [in] size of buffer \c attrib_name + h5_int64_t* attrib_type, ///< [out] type of value + h5_size_t* nelems ///< [out] number of elements ) { H5_API_ENTER (h5_err_t, "f=%p, " - "idx=%llu, name=%p, len_name=%llu, " - "type=%p, nelems=%p", + "idx=%llu, attrib_name=%p, len_attrib_name=%llu, " + "attrib_type=%p, nelems=%p", (h5_file_p)f, (long long unsigned)idx, - name, - (long long unsigned)len_name, - type, + attrib_name, + (long long unsigned)len_attrib_name, + attrib_type, nelems); H5_API_RETURN (h5_get_file_attrib_info_by_idx ( f, idx, - name, len_name, - type, + attrib_name, len_attrib_name, + attrib_type, + nelems)); +} + +/** + Determines whether a file attribute with a given name exists. + + \return true (value \c >0) if atrribute exists + \return false (\c 0) if attribute does not exist + \return \c H5_FAILURE on error + */ +static inline h5_err_t +H5HasFileAttrib ( + const h5_file_t f, ///< [in] file handle + const char* const attrib_name ///< [in] name of attribute to query + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "attrib_name=%p", + (h5_file_p)f, + attrib_name); + H5_API_RETURN ( + h5_has_file_attrib ( + f, + attrib_name)); +} + +/** + Get the type and number of elements of the file attribute + given by its name. + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error +*/ +static inline h5_err_t +H5GetFileAttribInfoByName ( + const h5_file_t f, ///< [in] file handle. + const char* const attrib_name, ///< [in] name of attribute. + h5_int64_t* attrib_type, ///< [out] type of value.. + h5_size_t* nelems ///< [out] number of elements. + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "attrib_name=%s, " + "attrib_type=%p, nelems=%p", + (h5_file_p)f, + attrib_name, + attrib_type, nelems); + H5_API_RETURN (h5_get_file_attrib_info_by_name ( + f, + attrib_name, + attrib_type, nelems)); +} + +/* + ! _ _ + ! __ ___ __(_) |_ ___ + ! \ \ /\ / / '__| | __/ _ \ + ! \ V V /| | | | || __/ + ! \_/\_/ |_| |_|\__\___| +*/ + +/** + \fn h5_err_t H5WriteFileAttribString ( + const h5_file_t f, + const char* attrib_name, + const char* buffer + ) + + \fn h5_err_t H5WriteFileAttribFloat64 ( + const h5_file_t f, + const char* attrib_name, + const h5_float64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteFileAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + const h5_float32_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteFileAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + const h5_int64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteFileAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + const h5_int32_t* buffer, + const h5_size_t nelems + ) + + Attach an attribute to a file given by a handle. + + The type of the attribute can be + + - a C string (\c char*) + - an array of 64bit floating point numbers (\c h5_float64_t) + - an array of 32bit floating point numbers (\c h5_float32_t) + - an array of 64bit integers (\c h5_int64_t) + - an array of 32bit integers (\c h5_int32_t) + + \param f [in] file handle + \param attrib_name [in] the attribute name + \param buffer [in] data to be written + \param nelems [in] number of elements to be written + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5ReadFileAttribString() + \see H5ReadFileAttribFloat64() + \see H5ReadFileAttribFloat32() + \see H5ReadFileAttribInt64() + \see H5ReadFileAttribInt32() +*/ +static inline h5_err_t +H5WriteFileAttribString ( + const h5_file_t f, + const char* attrib_name, + const char* buffer + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffer='%s'", + (h5_file_p)f, attrib_name, buffer); + H5_API_RETURN (h5_write_file_attrib ( + f, + attrib_name, + H5T_NATIVE_CHAR, + buffer, + strlen(buffer) + 1 )); +} + +static inline h5_err_t +H5WriteFileAttribFloat64 ( + const h5_file_t f, ///< [in] file handle. + const char *attrib_name, ///< [in] name of attribute to create. + const h5_float64_t *buffers, ///< [in] buffers of attribute. + const h5_size_t nelems ///< [in] number of buffers. + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffers=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems); + H5_API_RETURN (h5_write_file_attrib ( + f, + attrib_name, + H5T_NATIVE_DOUBLE, + buffers, + nelems)); +} + +static inline h5_err_t +H5WriteFileAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + const h5_float32_t* buffers, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffers=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems); + H5_API_RETURN (h5_write_file_attrib ( + f, + attrib_name, + H5T_NATIVE_FLOAT, + buffers, + nelems )); +} + +static inline h5_err_t +H5WriteFileAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + const h5_int64_t* buffers, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffers=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems); + H5_API_RETURN (h5_write_file_attrib ( + f, + attrib_name, + H5T_NATIVE_INT64, + buffers, + nelems)); +} + +static inline h5_err_t +H5WriteFileAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + const h5_int32_t* buffers, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffers=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems); + H5_API_RETURN (h5_write_file_attrib ( + f, + attrib_name, + H5T_NATIVE_INT32, + buffers, nelems)); } /* - __ _ _ _ _ _ _ _ - / _(_) | ___ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ - | |_| | |/ _ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| - | _| | | __/ | (_| | |_| |_| | | | |_) | |_| | || __/\__ \ - |_| |_|_|\___| \__,_|\__|\__|_| |_|_.__/ \__,_|\__\___||___/ - - _ __ - (_) / /__ - | | / / _ \ - | |/ / (_) | - |_/_/ \___/ -*/ + ! _ + ! _ __ ___ __ _ __| | + ! | '__/ _ \/ _` |/ _` | + ! | | | __/ (_| | (_| | + ! |_| \___|\__,_|\__,_| + */ /** - Write an attribute \c name with the string \c value to - the file root ("/"). + \fn h5_err_t H5ReadFileAttribString ( + const h5_file_t f, + const char* attrib_name, + char* buffer + ) - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteFileAttribString ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const char *value ///< [in] value of attribute. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', value='%s'", - (h5_file_p)f, name, value); - H5_API_RETURN (h5_write_file_attrib ( - f, - name, - H5T_NATIVE_CHAR, - value, - strlen(value) + 1 )); -} + \fn h5_err_t H5ReadFileAttribFloat64 ( + const h5_file_t f, + const char* attrib_name, + h5_float64_t* buffer + ) -/** - Read a string into a \c buffer from an attribute \c name - in the file root ("/"). + \fn h5_err_t H5ReadFileAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + h5_float32_t* buffer + ) - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ + \fn h5_err_t H5ReadFileAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + h5_int64_t* buffer + ) + + \fn h5_err_t H5ReadFileAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + h5_int32_t* buffer + ) + + Read attribute attached to a file given by a handle. + + \note Make sure that the size of the buffer is large enough! + + \param f [in] file handle + \param attrib_name [in] attribute name + \param buffer [out] buffer for data to be read + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5GetFileAttribInfo() + \see H5GetFileAttribInfoByName() + \see H5WriteFileAttribString() + \see H5WriteFileAttribFloat64() + \see H5WriteFileAttribFloat32() + \see H5WriteFileAttribInt64() + \see H5WriteFileAttribInt32() + + */ static inline h5_err_t H5ReadFileAttribString ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - char *buffer ///< [out] value of attribute. + const h5_file_t f, + const char* attrib_name, + char* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', value='%s'", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer='%s'", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_file_attrib ( f, - name, + attrib_name, H5_STRING_T, (void*)buffer)); } -/** - Write an attribute \c name with float64 \c values to - the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteFileAttribFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_float64_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_file_attrib ( - f, - name, - H5T_NATIVE_DOUBLE, - values, - nelems)); -} - -/** - Read float64 values into a \c buffer from an attribute \c name - in the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadFileAttribFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_float64_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_float64_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_file_attrib ( f, - name, + attrib_name, H5_FLOAT64_T, (void*)buffer)); } - -/** - Write an attribute \c name with float32 \c values to - the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteFileAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_float32_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_file_attrib ( - f, - name, - H5T_NATIVE_FLOAT, - values, - nelems )); -} - -/** - Read float32 values into a \c buffer from an attribute \c name - in the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadFileAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_float32_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_float32_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_file_attrib ( f, - name, + attrib_name, H5_FLOAT32_T, (void*)buffer)); } -/** - Write an attribute \c name with int64 \c values to - the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteFileAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_int64_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_file_attrib ( - f, - name, - H5T_NATIVE_INT64, - values, - nelems)); -} - -/** - Read int64 values into a \c buffer from an attribute \c name - in the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadFileAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_int64_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_int64_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_file_attrib ( f, - name, + attrib_name, H5_INT64_T, (void*)buffer)); } -/** - Write an attribute \c name with int32 \c values to - the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteFileAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_int32_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_file_attrib ( - f, - name, - H5T_NATIVE_INT32, - values, - nelems)); -} - -/** - Read int32 values into a \c buffer from an attribute \c name - in the file root ("/"). - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadFileAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_int32_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_int32_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_file_attrib ( f, - name, + attrib_name, H5_INT32_T, (void*)buffer)); } +///< @} #ifdef __cplusplus } #endif -///< @} #endif diff --git a/src/include/H5_model.h b/src/include/H5_model.h index 0e34b08..40c2b36 100644 --- a/src/include/H5_model.h +++ b/src/include/H5_model.h @@ -186,6 +186,14 @@ H5TraverseSteps ( (h5_file_p)f); H5_API_RETURN (h5_traverse_steps (f)); } +/** + @} +*/ + +/** + \addtogroup h5_attach + @{ +*/ /** Return number of attached files. diff --git a/src/include/H5_step_attribs.h b/src/include/H5_step_attribs.h index 4a77c01..d753f48 100644 --- a/src/include/H5_step_attribs.h +++ b/src/include/H5_step_attribs.h @@ -17,39 +17,33 @@ #include "h5core/h5_debug.h" #include "h5core/h5_attribs.h" -/** - \addtogroup h5_step_attribs - @{ -*/ - #ifdef __cplusplus extern "C" { #endif /* - _ _ _ _ _ _ - ___| |_ ___ _ __ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ - / __| __/ _ \ '_ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| - \__ \ || __/ |_) | | (_| | |_| |_| | | | |_) | |_| | || __/\__ \ - |___/\__\___| .__/ \__,_|\__|\__|_| |_|_.__/ \__,_|\__\___||___/ - |_| - - __ _ _ _ ___ _ __ _ _ - / _` | | | |/ _ \ '__| | | | - | (_| | |_| | __/ | | |_| | - \__, |\__,_|\___|_| \__, | - |_| |___/ + ! _ _ + ! (_)_ __ __ _ _ _(_)_ __ ___ + ! | | '_ \ / _` | | | | | '__/ _ \ + ! | | | | | (_| | |_| | | | | __/ + ! |_|_| |_|\__, |\__,_|_|_| \___| + ! |_| + ! +*/ +/** + \addtogroup h5_step_attribs + @{ */ /** - Gets the number of attributes bound to the current step. + Query the number of attributes attached to the current step. - \return Number of attributes + \return number of attributes \return \c H5_FAILURE on error */ static inline h5_int64_t H5GetNumStepAttribs ( - const h5_file_t f ///< [in] file handle. + const h5_file_t f ///< [in] file handle ) { H5_API_ENTER (h5_int64_t, "f=%p", @@ -59,329 +53,392 @@ H5GetNumStepAttribs ( /** Gets the name, type and number of elements of the step attribute - specified by its index. + given by its index. - This function can be used to retrieve all attributes bound to the - current time-step by looping from \c 0 to the number of attribute - minus one. The number of attributes bound to the current - time-step can be queried by calling \ref H5GetNumStepAttribs. + This function can be used to retrieve all attributes attached to the + current step by looping from \c 0 to the number of attribute + minus one. The number of attributes attached to the current + step can be queried by calling \ref H5GetNumStepAttribs(). \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5GetStepAttribInfo ( - const h5_file_t f, ///< [in] file handle. + const h5_file_t f, ///< [in] file handle const h5_size_t idx, ///< [in] index of attribute to query - char* name, ///< [out] name of attribute. - const h5_size_t len_name, ///< [in] length of buffer \c name. - h5_int64_t* type, ///< [out] type of value.. - h5_size_t* nelems ///< [out] number of elements. + char* attrib_name, ///< [out] name of attribute + const h5_size_t len_attrib_name,///< [in] size of buffer \c name + h5_int64_t* attrib_type, ///< [out] type of attribute + h5_size_t* nelems ///< [out] number of elements ) { H5_API_ENTER (h5_err_t, "f=%p, " - "idx=%llu, name=%p, len_name=%llu, " - "type=%p, nelems=%p", + "idx=%llu, attrib_name=%p, len_attrib_name=%llu, " + "attrib_type=%p, nelems=%p", (h5_file_p)f, (long long unsigned)idx, - name, - (long long unsigned)len_name, - type, + attrib_name, + (long long unsigned)len_attrib_name, + attrib_type, nelems); H5_API_RETURN (h5_get_step_attrib_info_by_idx ( f, idx, - name, - len_name, - type, + attrib_name, + len_attrib_name, + attrib_type, nelems)); } /** - Gets the type and number of elements of the step attribute - specified by its name. + Determines whether a step attribute with a given name exists in current step. + + \return true (value \c >0) if atrribute exists + \return false (\c 0) if attribute does not exist + \return \c H5_FAILURE on error + */ +static inline h5_err_t +H5HasStepAttrib ( + const h5_file_t f, ///< [in] file handle + const char* const attrib_name ///< [in] name of attribute to query + ) { + H5_API_ENTER (h5_err_t, + "f=%p, " + "attrib_name=%p", + (h5_file_p)f, + attrib_name); + H5_API_RETURN ( + h5_has_step_attrib ( + f, + attrib_name)); +} + +/** + Gets the type and number of elements of a given step attribute. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5GetStepAttribInfoByName ( - const h5_file_t f, ///< [in] file handle. - const char* const name, ///< [in] name of attribute. - h5_int64_t* type, ///< [out] type of value.. - h5_size_t* nelems ///< [out] number of elements. + const h5_file_t f, ///< [in] file handle + const char* const attrib_name, ///< [in] name of attribute to query + h5_int64_t* attrib_type, ///< [out] type of attribute + h5_size_t* nelems ///< [out] number of elements ) { H5_API_ENTER (h5_err_t, "f=%p, " - "name=%s, " - "type=%p, nelems=%p", + "attrib_name=%s, " + "attrib_type=%p, nelems=%p", (h5_file_p)f, - name, - type, nelems); + attrib_name, + attrib_type, nelems); H5_API_RETURN (h5_get_step_attrib_info_by_name ( f, - name, - type, nelems)); + attrib_name, + attrib_type, nelems)); } /* - _ _ _ _ _ _ - ___| |_ ___ _ __ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ - / __| __/ _ \ '_ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| - \__ \ || __/ |_) | | (_| | |_| |_| | | | |_) | |_| | || __/\__ \ - |___/\__\___| .__/ \__,_|\__|\__|_| |_|_.__/ \__,_|\__\___||___/ - |_| - - _ __ - (_) / /__ - | | / / _ \ - | |/ / (_) | - |_/_/ \___/ + ! _ _ + ! __ ___ __(_) |_ ___ + ! \ \ /\ / / '__| | __/ _ \ + ! \ V V /| | | | || __/ + ! \_/\_/ |_| |_|\__\___| */ /** - Write an attribute \c name with the string \c value to - the current timestep. + \fn h5_err_t H5WriteStepAttribString ( + const h5_file_t f, + const char* attrib_name, + const char* buffer + ) - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error + \fn h5_err_t H5WriteStepAttribFloat64 ( + const h5_file_t f, + const char* attrib_name, + const h5_float64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteStepAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + const h5_float32_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteStepAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + const h5_int64_t* buffer, + const h5_size_t nelems + ) + + \fn h5_err_t H5WriteStepAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + const h5_int32_t* buffer, + const h5_size_t nelems + ) + + Attach an attribute to current step. + + The type of the attribute can be + + - a C string (\c char*) + - an array of 64bit floating point numbers (\c h5_float64_t) + - an array of 32bit floating point numbers (\c h5_float32_t) + - an array of 64bit integers (\c h5_int64_t) + - an array of 32bit integers (\c h5_int32_t) + + \param f [in] file handle + \param attrib_name [in] the attribute name + \param buffer [in] data to be written + \param nelems [in] number of elements to be written + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5ReadStepAttribString() + \see H5ReadStepAttribFloat64() + \see H5ReadStepAttribFloat32() + \see H5ReadStepAttribInt64() + \see H5ReadStepAttribInt32() */ static inline h5_err_t H5WriteStepAttribString ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const char *value ///< [in] value of attribute. + const h5_file_t f, + const char* attrib_name, + const char* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', value='%s'", - (h5_file_p)f, name, value); + "f=%p, attrib_name='%s', buffer='%s'", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_write_step_attrib ( f, - name, + attrib_name, H5T_NATIVE_CHAR, - value, - strlen(value) + 1 )); + buffer, + strlen(buffer) + 1 )); } -/** - Read a string into a \c buffer from an attribute \c name - in the current timestep. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t -H5ReadStepAttribString ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - char *buffer ///< [out] value of attribute. +H5WriteStepAttribFloat64 ( + const h5_file_t f, + const char* attrib_name, + const h5_float64_t* buffer, + const h5_size_t nelems ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', value='%s'", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffer, (long long unsigned)nelems); + H5_API_RETURN (h5_write_step_attrib ( + f, + attrib_name, + H5T_NATIVE_DOUBLE, + buffer, + nelems)); +} + +static inline h5_err_t +H5WriteStepAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + const h5_float32_t* buffer, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffer=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffer, (long long unsigned)nelems); + H5_API_RETURN (h5_write_step_attrib ( + f, + attrib_name, + H5T_NATIVE_FLOAT, + buffer, + nelems )); +} + +static inline h5_err_t +H5WriteStepAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + const h5_int64_t* buffer, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffer=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffer, (long long unsigned)nelems); + H5_API_RETURN (h5_write_step_attrib ( + f, + attrib_name, + H5T_NATIVE_INT64, + buffer, + nelems)); +} + +static inline h5_err_t +H5WriteStepAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + const h5_int32_t* buffer, + const h5_size_t nelems + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffer=%p, nelems=%llu", + (h5_file_p)f, attrib_name, buffer, (long long unsigned)nelems); + H5_API_RETURN (h5_write_step_attrib ( + f, + attrib_name, + H5T_NATIVE_INT32, + buffer, + nelems)); +} + +/* + ! _ + ! _ __ ___ __ _ __| | + ! | '__/ _ \/ _` |/ _` | + ! | | | __/ (_| | (_| | + ! |_| \___|\__,_|\__,_| + */ + +/** + \fn h5_err_t H5ReadStepAttribString ( + const h5_file_t f, + const char* attrib_name, + char* buffer + ) + + \fn h5_err_t H5ReadStepAttribFloat64 ( + const h5_file_t f, + const char* attrib_name, + h5_float64_t* buffer + ) + + \fn h5_err_t H5ReadStepAttribFloat32 ( + const h5_file_t f, + const char* attrib_name, + h5_float32_t* buffer + ) + + \fn h5_err_t H5ReadStepAttribInt64 ( + const h5_file_t f, + const char* attrib_name, + h5_int64_t* buffer + ) + + \fn h5_err_t H5ReadStepAttribInt32 ( + const h5_file_t f, + const char* attrib_name, + h5_int32_t* buffer + ) + + Read attribute attached to current step. + + \note Make sure that the size of the buffer is large enough! + + \param f [in] file handle + \param attrib_name [in] attribute name + \param buffer [out] buffer for data to be read + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5GetStepAttribInfo() + \see H5GetStepAttribInfoByName() + \see H5WriteStepAttribString() + \see H5WriteStepAttribFloat64() + \see H5WriteStepAttribFloat32() + \see H5WriteStepAttribInt64() + \see H5WriteStepAttribInt32() + */ + +static inline h5_err_t +H5ReadStepAttribString ( + const h5_file_t f, + const char* attrib_name, + char* buffer + ) { + H5_API_ENTER (h5_err_t, + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_step_attrib ( f, - name, + attrib_name, H5_STRING_T, (void*)buffer)); } -/** - Write an attribute \c name with float64 \c values to - the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteStepAttribFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_float64_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_step_attrib ( - f, - name, - H5T_NATIVE_DOUBLE, - values, - nelems)); -} - -/** - Read float64 values into a \c buffer from an attribute \c name - in the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadStepAttribFloat64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_float64_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_float64_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_step_attrib ( f, - name, + attrib_name, H5_FLOAT64_T, (void*)buffer)); } -/** - Write an attribute \c name with float32 \c values to - the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteStepAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_float32_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_step_attrib ( - f, - name, - H5T_NATIVE_FLOAT, - values, - nelems )); -} - -/** - Read float32 values into a \c buffer from an attribute \c name - in the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadStepAttribFloat32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_float32_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_float32_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_step_attrib ( f, - name, + attrib_name, H5_FLOAT32_T, (void*)buffer)); } -/** - Write an attribute \c name with int64 \c values to - the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteStepAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_int64_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_step_attrib ( - f, - name, - H5T_NATIVE_INT64, - values, - nelems)); -} - -/** - Read int64 values into a \c buffer from an attribute \c name - in the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadStepAttribInt64 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_int64_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_int64_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); h5_err_t h5err = h5_read_step_attrib ( f, - name, + attrib_name, H5_INT64_T, (void*)buffer); H5_API_RETURN (h5err); } -/** - Write an attribute \c name with int32 \c values to - the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ -static inline h5_err_t -H5WriteStepAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - const h5_int32_t *values, ///< [in] values of attribute. - const h5_size_t nelems ///< [in] number of values. - ) { - H5_API_ENTER (h5_err_t, - "f=%p, name='%s', values=%p, nelems=%llu", - (h5_file_p)f, name, values, (long long unsigned)nelems); - H5_API_RETURN (h5_write_step_attrib ( - f, - name, - H5T_NATIVE_INT32, - values, - nelems)); -} - -/** - Read int32 values into a \c buffer from an attribute \c name - in the current time step. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error -*/ static inline h5_err_t H5ReadStepAttribInt32 ( - const h5_file_t f, ///< [in] file handle. - const char *name, ///< [in] name of attribute to create. - h5_int32_t *buffer ///< [out] values of attribute. + const h5_file_t f, + const char* attrib_name, + h5_int32_t* buffer ) { H5_API_ENTER (h5_err_t, - "f=%p, name='%s', buffer=%p", - (h5_file_p)f, name, buffer); + "f=%p, attrib_name='%s', buffer=%p", + (h5_file_p)f, attrib_name, buffer); H5_API_RETURN (h5_read_step_attrib ( f, - name, + attrib_name, H5_INT32_T, (void*)buffer)); } +///< @} #ifdef __cplusplus } #endif -///< @} #endif