1411 lines
54 KiB
C
1411 lines
54 KiB
C
/*
|
|
* gta.h
|
|
*
|
|
* This file is part of libgta, a library that implements the Generic Tagged
|
|
* Array (GTA) file format.
|
|
*
|
|
* Copyright (C) 2010, 2011, 2012, 2014
|
|
* Martin Lambers <marlam@marlam.de>
|
|
*
|
|
* Libgta is free software: you can redistribute it and/or modify it under the
|
|
* terms of the GNU Lesser General Public License as published by the Free
|
|
* Software Foundation, either version 2.1 of the License, or (at your option)
|
|
* any later version.
|
|
*
|
|
* Libgta is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
* WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
|
|
* A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
|
|
* details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public License
|
|
* along with Libgta. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
|
|
/**
|
|
* \file gta.h
|
|
* \brief The libgta C interface.
|
|
*
|
|
* This document describes the C language interface of libgta.
|
|
*/
|
|
|
|
|
|
/**
|
|
* \mainpage libgta Reference
|
|
*
|
|
* \section file_format The Generic Tagged Array (GTA) File Format
|
|
*
|
|
* The GTA file format has the following features:\n
|
|
* - GTAs can store any kind of data in multidimensional arrays\n
|
|
* - GTAs can optionally use simple tags to store rich metadata\n
|
|
* - GTAs are streamable, which allows direct reading from and writing to pipes, network sockets, and other non-seekable media\n
|
|
* - GTAs can use ZLIB, BZIP2, or XZ compression, allowing a tradeoff between compression/decompression speed and compression ratio\n
|
|
* - Uncompressed GTA files allow easy out-of-core data access for very large arrays
|
|
*
|
|
* See the <a href="http://www.nongnu.org/gta/doc/specification.pdf">GTA file format specification</a> for details.
|
|
*
|
|
* \section lib The libgta Library
|
|
*
|
|
* The library works with three basic entities: GTA headers, GTA tag lists, and the array data.\n
|
|
* A GTA header stores all the information about the array data: array dimensions, array element components,
|
|
* and tag lists. There is one global tag list for the whole array, one tag list for each dimension, and one
|
|
* tag list for each element component.\n
|
|
*
|
|
* The array data can be read and written in one of three ways:
|
|
* - completely in memory (for arrays that are not too big),
|
|
* - stream-based (for streamable tasks),
|
|
* - or block-based (for random access to the array data).
|
|
*
|
|
* The library provides interfaces for C and C++. See the <a href="files.html">Files</a> section.
|
|
*
|
|
* \section examples Examples
|
|
*
|
|
* Examples written in C:
|
|
* - <a href="example-basic_8c.html">Introductory example</a>
|
|
* - <a href="example-tags_8c.html">Using tags</a>
|
|
* - <a href="example-stream-io_8c.html">Stream-based input/output</a>
|
|
* - <a href="example-block-io_8c.html">Block-based input/output</a>
|
|
*
|
|
* Examples written in C++:
|
|
* - <a href="example-basic_8cpp.html">Introductory example</a>
|
|
* - <a href="example-tags_8cpp.html">Using tags</a>
|
|
* - <a href="example-stream-io_8cpp.html">Stream-based input/output</a>
|
|
* - <a href="example-block-io_8cpp.html">Block-based input/output</a>
|
|
*
|
|
* \page example-basic.c Examples written in C: Introductory example
|
|
* \include example-basic.c
|
|
* \page example-tags.c Examples written in C: Using tags
|
|
* \include example-tags.c
|
|
* \page example-stream-io.c Examples written in C: Stream-based input/output
|
|
* \include example-stream-io.c
|
|
* \page example-block-io.c Examples written in C: Block-based input/output
|
|
* \include example-block-io.c
|
|
*
|
|
* \page example-basic.cpp Examples written in C++: Introductory example
|
|
* \include example-basic.cpp
|
|
* \page example-tags.cpp Examples written in C++: Using tags
|
|
* \include example-tags.cpp
|
|
* \page example-stream-io.cpp Examples written in C++: Stream-based input/output
|
|
* \include example-stream-io.cpp
|
|
* \page example-block-io.cpp Examples written in C++: Block-based input/output
|
|
* \include example-block-io.cpp
|
|
*/
|
|
|
|
|
|
#ifndef GTA_H
|
|
#define GTA_H
|
|
|
|
#include <stdio.h>
|
|
|
|
#if defined _MSC_VER && _MSC_VER < 1600
|
|
/* MSVC versions older than Visual Studio 2010 lack the C99 header <stdint.h> */
|
|
typedef signed __int64 intmax_t;
|
|
typedef unsigned __int64 uintmax_t;
|
|
# ifdef _WIN64
|
|
typedef signed __int64 intptr_t;
|
|
# else
|
|
typedef signed int intptr_t;
|
|
# endif
|
|
#else
|
|
/* Everyone else has it */
|
|
# include <stdint.h>
|
|
#endif
|
|
|
|
|
|
/* GTA_EXPORT: Declare functions as part of the library API.
|
|
* (You only need to define GTA_STATIC for a static GTA library
|
|
* if you use Microsoft compilers). */
|
|
#if (defined _WIN32 || defined __WIN32__) && !defined __CYGWIN__
|
|
# ifdef GTA_BUILD
|
|
# ifdef DLL_EXPORT
|
|
# define GTA_EXPORT __declspec(dllexport)
|
|
# else
|
|
# define GTA_EXPORT
|
|
# endif
|
|
# else
|
|
# if defined _MSC_VER && !defined GTA_STATIC
|
|
# define GTA_EXPORT __declspec(dllimport)
|
|
# else
|
|
# define GTA_EXPORT
|
|
# endif
|
|
# endif
|
|
#else
|
|
# define GTA_EXPORT
|
|
#endif
|
|
|
|
/* Several attributes that may help the compiler to optimize the code or to
|
|
* produce better warnings.
|
|
* See http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html
|
|
* and http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html
|
|
*/
|
|
#ifdef __GNUC__
|
|
# define GTA_ATTR_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
|
|
# define GTA_ATTR_NONNULL_ALL __attribute__((nonnull))
|
|
# define GTA_ATTR_NONNULL1(a) __attribute__((nonnull(a)))
|
|
# define GTA_ATTR_NONNULL2(a, b) __attribute__((nonnull(a, b)))
|
|
# define GTA_ATTR_NONNULL3(a, b, c) __attribute__((nonnull(a, b, c)))
|
|
# define GTA_ATTR_CONST __attribute__((const))
|
|
# define GTA_ATTR_PURE __attribute__((pure))
|
|
# define GTA_ATTR_NOTHROW __attribute__((nothrow))
|
|
# define GTA_ATTR_UNUSED __attribute__((unused))
|
|
#else
|
|
# define GTA_ATTR_WARN_UNUSED_RESULT
|
|
# define GTA_ATTR_NONNULL_ALL
|
|
# define GTA_ATTR_NONNULL1(a)
|
|
# define GTA_ATTR_NONNULL2(a, b)
|
|
# define GTA_ATTR_NONNULL3(a, b, c)
|
|
# define GTA_ATTR_CONST
|
|
# define GTA_ATTR_PURE
|
|
# define GTA_ATTR_NOTHROW
|
|
# define GTA_ATTR_UNUSED
|
|
#endif
|
|
|
|
/* The C99 'restrict' keyword. */
|
|
#if __STDC_VERSION__ >= 199901L
|
|
# define GTA_RESTRICT restrict
|
|
#else
|
|
# define GTA_RESTRICT
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
/*
|
|
*
|
|
* Version information
|
|
*
|
|
*/
|
|
|
|
#include <gta/gta_version.h>
|
|
|
|
|
|
/*
|
|
*
|
|
* Types
|
|
*
|
|
*/
|
|
|
|
|
|
/**
|
|
* \brief The GTA header type
|
|
*/
|
|
typedef struct gta_internal_header_struct gta_header_t;
|
|
|
|
/**
|
|
* \brief The GTA tag list type
|
|
*
|
|
* A tag consists of a name and a value. A tag list stores these name/value pairs.\n
|
|
* Tag names are non-empty UTF-8 strings that must not contain '='.\n
|
|
* Tag values are UTF-8 strings.\n
|
|
* If you do not want to deal with conversions between the local character set and UTF-8,
|
|
* you must restrict names and values to ASCII.
|
|
*/
|
|
typedef struct gta_internal_taglist_struct gta_taglist_t;
|
|
|
|
/**
|
|
* \brief GTA result type
|
|
*
|
|
* The return value of most GTA functions is of this type, to indicate failures
|
|
* and their causes.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GTA_OK = 0,
|
|
/**<
|
|
* \brief Success / no error
|
|
*/
|
|
GTA_OVERFLOW = 1,
|
|
/**<
|
|
* \brief Size overflow
|
|
*/
|
|
GTA_UNSUPPORTED_DATA = 2,
|
|
/**<
|
|
* \brief Unsupported data
|
|
*
|
|
* The input seems to require features that are not available in this version
|
|
* of the library.
|
|
*/
|
|
GTA_UNEXPECTED_EOF = 3,
|
|
/**<
|
|
* \brief Unexpected end of file
|
|
*
|
|
* The GTA library intended to read more data, but the input did not provide it.
|
|
*/
|
|
GTA_INVALID_DATA = 4,
|
|
/**<
|
|
* \brief Invalid data
|
|
*
|
|
* Some data was invalid. For example, an input file is not in GTA format,
|
|
* or decompression of the data failed.
|
|
*/
|
|
GTA_SYSTEM_ERROR = 5
|
|
/**<
|
|
* \brief System error
|
|
*
|
|
* A system error occured. More information is available in errno.
|
|
* Examples: memory allocation failure (errno == ENOMEM), input/output
|
|
* errors (errno == EIO), no space left on device (errno == ENOSPC).
|
|
*/
|
|
} gta_result_t;
|
|
|
|
/**
|
|
* \brief GTA data types
|
|
*
|
|
* Data types supported by GTA.
|
|
*
|
|
* All integer types contain the exact number of bits indicated by their name
|
|
* and use the common two's complement representation.\n
|
|
* All floating point types contain the exact number of bits indicated by their
|
|
* name and conform to the binary representation defined by IEEE 754.\n
|
|
* The complex types (GTA_CFLOAT*) consist of two floating point values with the
|
|
* number of bits indicated by the name, as defined above. The first value is
|
|
* the real part, the second value is the imaginary part. For example,
|
|
* \a GTA_CFLOAT32 consists of two \a GTA_FLOAT32 values.\n
|
|
* The name \a GTA_BLOB can be used for data types that are not defined in this
|
|
* list. In this case, the size of the data type must be given, and the data type
|
|
* must be independent of endianness.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GTA_INT8 = 1, /**< \brief int8_t */
|
|
GTA_UINT8 = 2, /**< \brief uint8_t */
|
|
GTA_INT16 = 3, /**< \brief int16_t */
|
|
GTA_UINT16 = 4, /**< \brief uint16_t */
|
|
GTA_INT32 = 5, /**< \brief int32_t */
|
|
GTA_UINT32 = 6, /**< \brief uint32_t */
|
|
GTA_INT64 = 7, /**< \brief int64_t */
|
|
GTA_UINT64 = 8, /**< \brief uint64_t */
|
|
GTA_INT128 = 9, /**< \brief int128_t (unavailable on many platforms) */
|
|
GTA_UINT128 = 10, /**< \brief uint128_t (unavailable on many platforms) */
|
|
GTA_FLOAT32 = 11, /**< \brief IEEE 754 single precision floating point (on many platforms: float) */
|
|
GTA_FLOAT64 = 12, /**< \brief IEEE 754 double precision floating point (on many platforms: double) */
|
|
GTA_FLOAT128 = 13, /**< \brief IEEE 754 quadrupel precision floating point (unavailable on many platforms, even if long double exists) */
|
|
GTA_CFLOAT32 = 14, /**< \brief complex (re,im) based on two \a GTA_FLOAT32 */
|
|
GTA_CFLOAT64 = 15, /**< \brief complex (re,im) based on two \a GTA_FLOAT64 */
|
|
GTA_CFLOAT128 = 16, /**< \brief complex (re,im) based on two \a GTA_FLOAT128 */
|
|
GTA_BLOB = 0 /**< \brief Data blob; must be endianness-independent; user must specify the size */
|
|
} gta_type_t;
|
|
|
|
/**
|
|
* \brief GTA compression algorithms
|
|
*
|
|
* Compression algorithms used to compress the array.\n
|
|
* Only uncompressed files are suitable for out-of-core data access; compressed
|
|
* files must be decompressed first.\n
|
|
* \a GTA_ZLIB compression is fast and achieves a moderate compression ratio.
|
|
* \a GTA_BZIP2 compression is moderately fast and achieves a good compression ratio.
|
|
* \a GTA_XZ compression is slow for compression, moderately fast for decompression,
|
|
* and achieves good or very good compression rates.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GTA_NONE = 0, /**< \brief No compression */
|
|
GTA_ZLIB = 1, /**< \brief ZLIB compression with default level (fast, moderate compression rate) */
|
|
GTA_ZLIB1 = 4, /**< \brief ZLIB compression with level 1 */
|
|
GTA_ZLIB2 = 5, /**< \brief ZLIB compression with level 2 */
|
|
GTA_ZLIB3 = 6, /**< \brief ZLIB compression with level 3 */
|
|
GTA_ZLIB4 = 7, /**< \brief ZLIB compression with level 4 */
|
|
GTA_ZLIB5 = 8, /**< \brief ZLIB compression with level 5 */
|
|
GTA_ZLIB6 = 9, /**< \brief ZLIB compression with level 6 */
|
|
GTA_ZLIB7 = 10, /**< \brief ZLIB compression with level 7 */
|
|
GTA_ZLIB8 = 11, /**< \brief ZLIB compression with level 8 */
|
|
GTA_ZLIB9 = 12, /**< \brief ZLIB compression with level 9 */
|
|
GTA_BZIP2 = 2, /**< \brief BZIP2 compression (moderate speed, good compression rates) */
|
|
GTA_XZ = 3 /**< \brief XZ compression (low/moderate speed, good/very good compression rates) */
|
|
} gta_compression_t;
|
|
|
|
/**
|
|
* \brief Custom input function
|
|
*
|
|
* You can specify your own input function to read from your own custom sources.\n
|
|
* It must read the given number of bytes into the given buffer.\n
|
|
* Its return value must be the number of bytes successfully read.\n
|
|
* If an error occured, the error flag must be set to true (1).
|
|
* The function must set errno to indicate the type of error. If the
|
|
* error type is unknown, errno should be set to EIO.
|
|
*/
|
|
typedef size_t (*gta_read_t)(intptr_t userdata, void *buffer, size_t size, int *error);
|
|
|
|
/**
|
|
* \brief Custom output function
|
|
*
|
|
* You can specify your own output function to write to your own custum destinations.\n
|
|
* It must write the given number of bytes from the given buffer.\n
|
|
* Its return value must be the number of bytes successfully written.\n
|
|
* If an error occured, the error flag must be set to true (1).
|
|
* The function must set errno to indicate the type of error. If the
|
|
* error type is unknown, errno should be set to EIO.
|
|
*/
|
|
typedef size_t (*gta_write_t)(intptr_t userdata, const void *buffer, size_t size, int *error);
|
|
|
|
/**
|
|
* \brief Custom seek function
|
|
*
|
|
* You can specify your own seek function to seek in your own custum media.\n
|
|
* It must change its file position indicator as indicated by the parameters \a
|
|
* offset and \a whence, just like fseeko() and lseek() do. The parameter \a whence
|
|
* can be SEEK_SET or SEEK_CUR (SEEK_END is never used).\n
|
|
* If an error occured, the error flag must be set to true (1).
|
|
* The function must set errno to indicate the type of error. If the
|
|
* error type is unknown, errno should be set to EIO.
|
|
*/
|
|
typedef void (*gta_seek_t)(intptr_t userdata, intmax_t offset, int whence, int *error);
|
|
|
|
/**
|
|
* \brief State for element-based input/output
|
|
*
|
|
* See gta_read_elements() and gta_write_elements().
|
|
*/
|
|
typedef struct gta_internal_io_state_struct gta_io_state_t;
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Version information
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Get the libgta version.
|
|
* \param major Buffer for the major version number, or NULL.
|
|
* \param minor Buffer for the minor version number, or NULL.
|
|
* \param patch Buffer for the patch version number, or NULL.
|
|
* \return The libgta version string.
|
|
*
|
|
* This function returns the version string "MAJOR.MINOR.PATCH".
|
|
* If the pointers \a major, \a minor, \a patch are not NULL,
|
|
* the requested version number will be stored there.
|
|
*/
|
|
extern GTA_EXPORT const char *
|
|
gta_version(int *GTA_RESTRICT major, int *GTA_RESTRICT minor, int *GTA_RESTRICT patch)
|
|
GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
/**
|
|
*
|
|
* \name Create and destroy GTA Headers
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Create a new GTA header structure and initialize it.
|
|
* \param header The header.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Creates a new GTA header and initializes it.
|
|
* The GTA will initially be empty (zero element components, zero dimensions)
|
|
* and contain no tags. The compression method will be \a GTA_NONE.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_create_header(gta_header_t *GTA_RESTRICT *GTA_RESTRICT header)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Clone a GTA header structure.
|
|
* \param dst_header The destination header.
|
|
* \param src_header The source header.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Clones \a src_header into \a dst_header.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_clone_header(gta_header_t *GTA_RESTRICT dst_header,
|
|
const gta_header_t *GTA_RESTRICT src_header)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Destroy a GTA header structure and free its resources.
|
|
* \param header The header.
|
|
*
|
|
* Destroys a GTA header structure and fress all of its resources.
|
|
*/
|
|
extern GTA_EXPORT void
|
|
gta_destroy_header(gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Read and Write GTA Headers
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Read a GTA header.
|
|
* \param header The header.
|
|
* \param read_fn The custom input function.
|
|
* \param userdata A parameter to the custom input function.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_INVALID_DATA, or \a GTA_SYSTEM_ERROR.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_header(gta_header_t *GTA_RESTRICT header, gta_read_t read_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Read a GTA header from a stream.
|
|
* \param header The header.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_INVALID_DATA, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads a GTA header from a stream.\n
|
|
* The file position indicator will be positioned after the GTA header, on the
|
|
* first data byte.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_header_from_stream(gta_header_t *GTA_RESTRICT header, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Read a GTA header from a file descriptor.
|
|
* \param header The header.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_INVALID_DATA, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads a GTA header from a file descriptor.\n
|
|
* The file position indicator will be positioned after the GTA header, on the
|
|
* first data byte.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_header_from_fd(gta_header_t *GTA_RESTRICT header, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
|
|
/**
|
|
* \brief Write a GTA header.
|
|
* \param header The header.
|
|
* \param write_fn The custom output function.
|
|
* \param userdata A parameter to the custom output function.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_header(const gta_header_t *GTA_RESTRICT header, gta_write_t write_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Write a GTA header to a stream.
|
|
* \param header The header.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_header_to_stream(const gta_header_t *GTA_RESTRICT header, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Write a GTA header to a file descriptor.
|
|
* \param header The header.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_header_to_fd(const gta_header_t *GTA_RESTRICT header, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Access GTA Headers
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Get the global tag list (non-modifiable).
|
|
* \param header The header.
|
|
* \return The global tag list (non-modifiable).
|
|
*/
|
|
extern GTA_EXPORT const gta_taglist_t *
|
|
gta_get_global_taglist_const(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the global tag list (modifiable).
|
|
* \param header The header.
|
|
* \return The global tag list (modifiable).
|
|
*/
|
|
extern GTA_EXPORT gta_taglist_t *
|
|
gta_get_global_taglist(gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Return the size of an array element.
|
|
* \param header The header.
|
|
* \return The size of an array element, which is the sum of the component sizes.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_element_size(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the number of components.
|
|
* \param header The header.
|
|
* \return The number of components in an array element.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_components(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the type of a component.
|
|
* \param header The header.
|
|
* \param i The component index.
|
|
* \return The type of the element component.
|
|
*/
|
|
extern GTA_EXPORT gta_type_t
|
|
gta_get_component_type(const gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the size of a component.
|
|
* \param header The header.
|
|
* \param i The component index.
|
|
* \return The size (in bytes) of the element component.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_component_size(const gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag list of a component (non-modifiable).
|
|
* \param header The header.
|
|
* \param i The component index.
|
|
* \return The tag list of the element component (non-modifiable).
|
|
*/
|
|
extern GTA_EXPORT const gta_taglist_t *
|
|
gta_get_component_taglist_const(const gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag list of a component (modifiable).
|
|
* \param header The header.
|
|
* \param i The component index.
|
|
* \return The tag list of the element component (modifiable).
|
|
*/
|
|
extern GTA_EXPORT gta_taglist_t *
|
|
gta_get_component_taglist(gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the number of dimensions.
|
|
* \param header The header.
|
|
* \return The number of dimensions of the array data.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_dimensions(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the size in a dimension.
|
|
* \param header The header.
|
|
* \param i The dimension index.
|
|
* \return The size of the array in the given dimension.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_dimension_size(const gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag list of a dimension (non-modifiable).
|
|
* \param header The header.
|
|
* \param i The dimension index.
|
|
* \return The tag list of the dimension (non-modifiable).
|
|
*/
|
|
extern GTA_EXPORT const gta_taglist_t *
|
|
gta_get_dimension_taglist_const(const gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag list of a dimension (modifiable).
|
|
* \param header The header.
|
|
* \param i The dimension index.
|
|
* \return The tag list of the dimension (modifiable).
|
|
*/
|
|
extern GTA_EXPORT gta_taglist_t *
|
|
gta_get_dimension_taglist(gta_header_t *GTA_RESTRICT header, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the total number of elements in the array.
|
|
* \param header The header.
|
|
* \return The total number of elements in the array.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_elements(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the total size of the array data.
|
|
* \param header The header.
|
|
* \return The total size (in bytes) of the array data.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_data_size(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the compression.
|
|
* \param header The header.
|
|
* \return The compression type.
|
|
*
|
|
* Gets the compression type for the header and data.\n
|
|
* See \a gta_compression_t for more information on compression types.\n
|
|
* Compressed data is always stored in chunks, while uncompressed
|
|
* data is never stored in chunks.
|
|
*/
|
|
extern GTA_EXPORT gta_compression_t
|
|
gta_get_compression(const gta_header_t *GTA_RESTRICT header)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Set the compression.
|
|
* \param header The header.
|
|
* \param compression The compression type.
|
|
*
|
|
* Sets the compression type for writing the header and data.\n
|
|
* See \a gta_compression_t for more information on compression types.
|
|
*/
|
|
extern GTA_EXPORT void
|
|
gta_set_compression(gta_header_t *GTA_RESTRICT header, gta_compression_t compression)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Define an Array
|
|
*
|
|
*/
|
|
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Set the components of an array element.
|
|
* \param header The header.
|
|
* \param n The number of components.
|
|
* \param types The types of the \a n components.
|
|
* \param sizes NULL, or the sizes of the components that have type \a GTA_BLOB.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_UNSUPPORTED_DATA, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Set the components of the array elements.\n
|
|
* The \a sizes parameter can be NULL if no components have the type \a GTA_BLOB.
|
|
* Otherwise, it must point to a list that contains the sizes of these components (and only
|
|
* these components). For example, if there are five components, but only two have the type
|
|
* \a GTA_BLOB, then the \a sizes list must contain two size values.\n
|
|
* All components will initially have an empty tag list.\n
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_set_components(gta_header_t *GTA_RESTRICT header, uintmax_t n, const gta_type_t *GTA_RESTRICT types, const uintmax_t *GTA_RESTRICT sizes)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL1(1) GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Set the dimensions.
|
|
* \param header The header.
|
|
* \param n The number of dimensions.
|
|
* \param sizes The array sizes in each of the \n dimensions.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_INVALID_DATA, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Sets the array dimensions.\n
|
|
* All dimensions will initially have an empty tag list.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_set_dimensions(gta_header_t *GTA_RESTRICT header, uintmax_t n, const uintmax_t *GTA_RESTRICT sizes)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL1(1) GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Access Tag Lists
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Get the number of tags in a tag list.
|
|
* \param taglist The tag list.
|
|
* \return The number of tags in the list.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_get_tags(const gta_taglist_t *GTA_RESTRICT taglist)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag name with the given index.
|
|
* \param taglist The tag list.
|
|
* \param i The tag index.
|
|
* \return The name of the tag.
|
|
*/
|
|
extern GTA_EXPORT const char *
|
|
gta_get_tag_name(const gta_taglist_t *GTA_RESTRICT taglist, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the tag value with the given index.
|
|
* \param taglist The tag list.
|
|
* \param i The tag index.
|
|
* \return The value of the tag.
|
|
*/
|
|
extern GTA_EXPORT const char *
|
|
gta_get_tag_value(const gta_taglist_t *GTA_RESTRICT taglist, uintmax_t i)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get a tag value by its name.
|
|
* \param taglist The tag list.
|
|
* \param name The tag name.
|
|
* \return The tag value, or NULL if the tag name is not found.
|
|
*/
|
|
extern GTA_EXPORT const char *
|
|
gta_get_tag(const gta_taglist_t *GTA_RESTRICT taglist, const char *GTA_RESTRICT name)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Set a tag.
|
|
* \param taglist The tag list.
|
|
* \param name The name.
|
|
* \param value The value.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Sets the given tag, possibly overwriting an existing tag with the same name.
|
|
* The name and value must be valid UTF-8 strings without control characters.
|
|
* Additionally, the name must not contain the equal sign and must not be empty.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_set_tag(gta_taglist_t *GTA_RESTRICT taglist, const char *GTA_RESTRICT name, const char *GTA_RESTRICT value)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Unset a tag.
|
|
* \param taglist The tag list.
|
|
* \param name The tag name.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Removes the tag with the given name, if it exists.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_unset_tag(gta_taglist_t *GTA_RESTRICT taglist, const char *GTA_RESTRICT name)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Unset all tags.
|
|
* \param taglist The tag list.
|
|
*
|
|
* Removes all tags from the tag list.
|
|
*/
|
|
extern GTA_EXPORT void
|
|
gta_unset_all_tags(gta_taglist_t *GTA_RESTRICT taglist)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Clone a tag list.
|
|
* \param dst_taglist The destination tag list.
|
|
* \param src_taglist The source tag list.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Copies \a src_taglist to \a dst_taglist.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_clone_taglist(gta_taglist_t *GTA_RESTRICT dst_taglist,
|
|
const gta_taglist_t *GTA_RESTRICT src_taglist)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Read and Write Complete Arrays
|
|
*
|
|
* These functions are intended to be used by applications that know that all the data will fit into memory.
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Read the complete data.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param read_fn The custom input function.
|
|
* \param userdata A parameter to the custom input function.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the complete data into the given buffer. The buffer must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_data(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT data, gta_read_t read_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Read the complete data from a stream.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the complete data into the given buffer. The buffer must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_data_from_stream(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT data, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Read the complete data from a file descriptor.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the complete data into the given buffer. The buffer must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_data_from_fd(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT data, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Skip the complete data.
|
|
* \param header The header.
|
|
* \param read_fn The custom input function.
|
|
* \param seek_fn The custom seek function, or NULL for non-seekable input.
|
|
* \param userdata A parameter to the custom input and seek functions.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Skips the complete data, so that the next GTA header can be read.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_skip_data(const gta_header_t *GTA_RESTRICT header, gta_read_t read_fn, gta_seek_t seek_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL2(1, 2);
|
|
|
|
/**
|
|
* \brief Skip the complete data from a stream.
|
|
* \param header The header.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Skips the complete data, so that the next GTA header can be read.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_skip_data_from_stream(const gta_header_t *GTA_RESTRICT header, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Skip the complete data from a file descriptor.
|
|
* \param header The header.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Skips the complete data, so that the next GTA header can be read.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_skip_data_from_fd(const gta_header_t *GTA_RESTRICT header, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Write the complete data.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param write_fn The custom output function.
|
|
* \param userdata A parameter to the custom output function.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the complete data.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_data(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT data, gta_write_t write_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL2(1, 3);
|
|
|
|
/**
|
|
* \brief Write the complete data to a stream.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the complete data.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_data_to_stream(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT data, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL2(1, 3) GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Write the complete data to a file descriptor.
|
|
* \param header The header.
|
|
* \param data The data buffer.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the complete data.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_data_to_fd(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT data, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL1(1) GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Copy the complete data.
|
|
* \param read_header The input header.
|
|
* \param read_fn The custom input function.
|
|
* \param read_userdata A parameter to the custom input function.
|
|
* \param write_header The ourput header.
|
|
* \param write_fn The custom output function.
|
|
* \param write_userdata A parameter to the custom output function.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Copies the complete data.
|
|
* The data encoding is altered as necessary (endianness correction, compression).
|
|
* Note that the data encoding may change even if \a read_header and \a write_header
|
|
* point to the same header!
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_copy_data(
|
|
const gta_header_t *GTA_RESTRICT read_header, gta_read_t read_fn, intptr_t read_userdata,
|
|
const gta_header_t *GTA_RESTRICT write_header, gta_write_t write_fn, intptr_t write_userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Copy the complete data between streams.
|
|
* \param read_header The input header.
|
|
* \param read_f The input stream.
|
|
* \param write_header The output header.
|
|
* \param write_f The output stream.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Copies the complete data.
|
|
* The data encoding is altered as necessary (endianness correction, compression).
|
|
* Note that the data encoding may change even if \a read_header and \a write_header
|
|
* point to the same header!
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_copy_data_stream(
|
|
const gta_header_t *GTA_RESTRICT read_header, FILE *GTA_RESTRICT read_f,
|
|
const gta_header_t *GTA_RESTRICT write_header, FILE *GTA_RESTRICT write_f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Copy the complete data between file descriptors.
|
|
* \param read_header The input header.
|
|
* \param read_fd The input file descriptor.
|
|
* \param write_header The output header.
|
|
* \param write_fd The output file descriptor.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Copies the complete data.
|
|
* The data encoding is altered as necessary (endianness correction, compression).
|
|
* Note that the data encoding may change even if \a read_header and \a write_header
|
|
* point to the same header!
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_copy_data_fd(
|
|
const gta_header_t *GTA_RESTRICT read_header, int read_fd,
|
|
const gta_header_t *GTA_RESTRICT write_header, int write_fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name In-Memory Data Access
|
|
*
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Transform a linear index to array indices.
|
|
* \param header The header.
|
|
* \param index The linear index.
|
|
* \param indices The array indices.
|
|
*/
|
|
extern GTA_EXPORT void
|
|
gta_linear_index_to_indices(const gta_header_t *GTA_RESTRICT header, uintmax_t index, uintmax_t *GTA_RESTRICT indices)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Transform array indices to a linear index.
|
|
* \param header The header.
|
|
* \param indices The array indices.
|
|
* \return The linear index.
|
|
*/
|
|
extern GTA_EXPORT uintmax_t
|
|
gta_indices_to_linear_index(const gta_header_t *GTA_RESTRICT header, const uintmax_t *GTA_RESTRICT indices)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of an array element (non-modifiable).
|
|
* \param header The header.
|
|
* \param data The data.
|
|
* \param indices The indices for each dimension of the array.
|
|
* \return A pointer to the element.
|
|
*/
|
|
extern GTA_EXPORT const void *
|
|
gta_get_element_const(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT data, const uintmax_t *GTA_RESTRICT indices)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of an array element (modifiable).
|
|
* \param header The header.
|
|
* \param data The data.
|
|
* \param indices The indices for each dimension of the array.
|
|
* \return A pointer to the element.
|
|
*/
|
|
extern GTA_EXPORT void *
|
|
gta_get_element(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT data, const uintmax_t *GTA_RESTRICT indices)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of an array element (non-modifiable).
|
|
* \param header The header.
|
|
* \param data The data.
|
|
* \param index The linear index of the element.
|
|
* \return A pointer to the element.
|
|
*/
|
|
extern GTA_EXPORT const void *
|
|
gta_get_element_linear_const(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT data, uintmax_t index)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of an array element (modifiable).
|
|
* \param header The header.
|
|
* \param data The data.
|
|
* \param index The linear index of the element.
|
|
* \return A pointer to the element.
|
|
*/
|
|
extern GTA_EXPORT void *
|
|
gta_get_element_linear(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT data, uintmax_t index)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of a component of an array element (non-modifiable).
|
|
* \param header The header.
|
|
* \param element The element.
|
|
* \param i The component index.
|
|
* \return A pointer to the component.
|
|
*/
|
|
extern GTA_EXPORT const void *
|
|
gta_get_component_const(const gta_header_t *GTA_RESTRICT header, const void *GTA_RESTRICT element, uintmax_t i)
|
|
GTA_ATTR_NONNULL1(1) GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Get the address of a component of an array element (modifiable).
|
|
* \param header The header.
|
|
* \param element The element.
|
|
* \param i The component index.
|
|
* \return A pointer to the component.
|
|
*/
|
|
extern GTA_EXPORT void *
|
|
gta_get_component(const gta_header_t *GTA_RESTRICT header, void *GTA_RESTRICT element, uintmax_t i)
|
|
GTA_ATTR_NONNULL1(1) GTA_ATTR_PURE GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Read and Write Array Elements
|
|
*
|
|
* These functions are intended to be used for filtering a complete array on a per-element basis.
|
|
* They read or write a given number of elements, and it is expected that they are used
|
|
* repeatedly until all elements of an array have been read or written.
|
|
* Theses function work for all GTAs, with or without compression, an the input and output streams
|
|
* do not need to be seekable.
|
|
*
|
|
* Element-based input/output needs a state structure. This structure must be allocated with
|
|
* gta_create_io_state() before the first element is read or written, and freed with
|
|
* gta_destroy_io_state() after the last element was read or written, or after an error occured.
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Create and initialize a new input/output state.
|
|
* \param io_state The input/output state.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Creates and initializes a state structure for element-based input/output.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_create_io_state(gta_io_state_t *GTA_RESTRICT *GTA_RESTRICT io_state)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Clone an input/output state.
|
|
* \param dst_io_state The destination state.
|
|
* \param src_io_state The source state.
|
|
* \return \a GTA_OK or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Clones \a src_io_state into \a dst_io_state.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_clone_io_state(gta_io_state_t *GTA_RESTRICT dst_io_state,
|
|
const gta_io_state_t *GTA_RESTRICT src_io_state)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Destroy input/output state and free its resources.
|
|
* \param io_state The input/output state.
|
|
*
|
|
* Destroys a state structure for element-based input/output and frees its resources.
|
|
*/
|
|
extern GTA_EXPORT void
|
|
gta_destroy_io_state(gta_io_state_t *GTA_RESTRICT io_state)
|
|
GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Read array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to read.
|
|
* \param buf The buffer for the elements.
|
|
* \param read_fn The custom input function.
|
|
* \param userdata A parameter to the custom input function.
|
|
* \return \a GTA_OK, \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given number of elements into the given buffer, which must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_elements(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, void *GTA_RESTRICT buf, gta_read_t read_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Read array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to read.
|
|
* \param buf The buffer for the elements.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given number of elements into the given buffer, which must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_elements_from_stream(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, void *GTA_RESTRICT buf, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Read array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to read.
|
|
* \param buf The buffer for the elements.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given number of elements into the given buffer, which must be large enough.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_elements_from_fd(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, void *GTA_RESTRICT buf, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Write array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to write.
|
|
* \param buf The buffer for the elements.
|
|
* \param write_fn The custom output function.
|
|
* \param userdata A parameter to the custom output function.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the given number of elements from the given buffer.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_elements(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, const void *GTA_RESTRICT buf, gta_write_t write_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Write array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to write.
|
|
* \param buf The buffer for the elements.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the given number of elements from the given buffer.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_elements_to_stream(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, const void *GTA_RESTRICT buf, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Write array elements.
|
|
* \param header The header.
|
|
* \param io_state The input/output state.
|
|
* \param n The number of elements to write.
|
|
* \param buf The buffer for the elements.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_INVALID_DATA, \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Writes the given number of elements from the given buffer.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_elements_to_fd(const gta_header_t *GTA_RESTRICT header, gta_io_state_t *GTA_RESTRICT io_state,
|
|
uintmax_t n, const void *GTA_RESTRICT buf, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
|
|
/*@}*/
|
|
|
|
|
|
/**
|
|
*
|
|
* \name Read and Write Array Blocks
|
|
*
|
|
* These functions can only be used if the data is not compression (see \a gta_get_compression())
|
|
* and the input/output is seekable.\n
|
|
* They are suitable for applications that do not want to store the complete array data in
|
|
* memory.\n
|
|
* A block is given by the lowest and highest element coordinates in each dimension.
|
|
* For example, for a 2D array from which we want a rectangle of 20x10 elements starting at
|
|
* element (5,3), we would store the values (5,3) in \a lower_coordinates and (24, 12) in
|
|
* \a higher_coordinates.
|
|
*/
|
|
|
|
/*@{*/
|
|
|
|
/**
|
|
* \brief Read an array block.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param read_fn The custom input function.
|
|
* \param seek_fn The custom seek function.
|
|
* \param userdata A parameter to the custom input function.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given array block and copies it to the given block buffer, which must be large enough.\n
|
|
* This function modifies the file position indicator of the input.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_block(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
void *GTA_RESTRICT block, gta_read_t read_fn, gta_seek_t seek_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Read an array block from a stream.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given array block and copies it to the given block buffer, which must be large enough.\n
|
|
* This function modifies the file position indicator of the input.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_block_from_stream(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
void *GTA_RESTRICT block, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Read an array block from a file descriptor.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, \a GTA_UNEXPECTED_EOF, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* Reads the given array block and copies it to the given block buffer, which must be large enough.\n
|
|
* This function modifies the file position indicator of the input.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_read_block_from_fd(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
void *GTA_RESTRICT block, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Write an array block.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param write_fn The custom output function.
|
|
* \param seek_fn The custom seek function.
|
|
* \param userdata A parameter to the custom output function.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* This function modifies the file position indicator of the output.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_block(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
const void *GTA_RESTRICT block, gta_write_t write_fn, gta_seek_t seek_fn, intptr_t userdata)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL;
|
|
|
|
/**
|
|
* \brief Write an array block to a stream.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param f The stream.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, or \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* This function modifies the file position indicator of the output.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_block_to_stream(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
const void *GTA_RESTRICT block, FILE *GTA_RESTRICT f)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/**
|
|
* \brief Write an array block to a file descriptor.
|
|
* \param header The header.
|
|
* \param data_offset Offset of the first data byte.
|
|
* \param lower_coordinates Coordinates of the lower corner element of the block.
|
|
* \param higher_coordinates Coordinates of the higher corner element of the block.
|
|
* \param block The block buffer.
|
|
* \param fd The file descriptor.
|
|
* \return \a GTA_OK, \a GTA_UNSUPPORTED_DATA (if the data is compressed), \a GTA_OVERFLOW, \a GTA_SYSTEM_ERROR.
|
|
*
|
|
* This function modifies the file position indicator of the output.
|
|
*/
|
|
extern GTA_EXPORT gta_result_t
|
|
gta_write_block_to_fd(const gta_header_t *GTA_RESTRICT header, intmax_t data_offset,
|
|
const uintmax_t *GTA_RESTRICT lower_coordinates, const uintmax_t *GTA_RESTRICT higher_coordinates,
|
|
const void *GTA_RESTRICT block, int fd)
|
|
GTA_ATTR_WARN_UNUSED_RESULT GTA_ATTR_NONNULL_ALL GTA_ATTR_NOTHROW;
|
|
|
|
/*@}*/
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|