/*
* gta.hpp
*
* This file is part of libgta, a library that implements the Generic Tagged
* Array (GTA) file format.
*
* Copyright (C) 2010, 2011, 2012
* 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.hpp
* \brief The libgta C++ interface.
*
* This document describes the C++ language interface of libgta.
*/
#ifndef GTA_HPP
#define GTA_HPP
#include <exception>
#include <istream>
#include <ostream>
#include <vector>
#include <limits>
#include <cerrno>
#include <cstring>
#include <cstdio>
#include <gta/gta.h>
#ifdef _MSC_VER
# pragma warning (push)
# pragma warning (disable: 4996) // strerror and _snprintf
# pragma warning (disable: 4244) // conversion from uintmax_t to unsigned int
#endif
/**
* \brief The gta namespace.
*/
namespace gta
{
/**
* \brief GTA result
*
* This is equivalent to \a gta_result_t from the C interface.
*/
enum result
{
ok = GTA_OK,
/**<
* \brief Success / no error
*/
overflow = GTA_OVERFLOW,
/**<
* \brief Size overflow
*/
unsupported_data = GTA_UNSUPPORTED_DATA,
/**<
* \brief Unsupported data
*
* The input seems to require features that are not available in this version
* of the library.
*/
unexpected_eof = GTA_UNEXPECTED_EOF,
/**<
* \brief Unexpected end of file
*
* The GTA library intended to read more data, but the input did not provide it.
*/
invalid_data = GTA_INVALID_DATA,
/**<
* \brief Invalid data
*
* Some data was invalid. For example, an input file is not in GTA format,
* or decompression of the data failed.
*/
system_error = GTA_SYSTEM_ERROR
/**<
* \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).
*/
};
/**
* \brief GTA data types
*
* This is equivalent to \a gta_type_t from the C interface.
*
* 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.
*/
enum type
{
int8 = GTA_INT8, /**< \brief int8_t */
uint8 = GTA_UINT8, /**< \brief uint8_t */
int16 = GTA_INT16, /**< \brief int16_t */
uint16 = GTA_UINT16, /**< \brief uint16_t */
int32 = GTA_INT32, /**< \brief int32_t */
uint32 = GTA_UINT32, /**< \brief uint32_t */
int64 = GTA_INT64, /**< \brief int64_t */
uint64 = GTA_UINT64, /**< \brief uint64_t */
int128 = GTA_INT128, /**< \brief int128_t (unavailable on many platforms) */
uint128 = GTA_UINT128, /**< \brief uint128_t (unavailable on many platforms) */
float32 = GTA_FLOAT32, /**< \brief IEEE 754 single precision floating point (on many platforms: float) */
float64 = GTA_FLOAT64, /**< \brief IEEE 754 double precision floating point (on many platforms: double) */
float128 = GTA_FLOAT128, /**< \brief IEEE 754 quadrupel precision floating point (unavailable on many platforms, even if long double exists) */
cfloat32 = GTA_CFLOAT32, /**< \brief complex (re,im) based on two \a gta::float32 */
cfloat64 = GTA_CFLOAT64, /**< \brief complex (re,im) based on two \a gta::float64 */
cfloat128 = GTA_CFLOAT128, /**< \brief complex (re,im) based on two \a gta::float128 */
blob = GTA_BLOB /**< \brief Data blob; must be endianness-independent; user must specify the size */
};
/**
* \brief GTA compression methods
*
* This is equivalent to \a gta_compression_t from the C interface.
*
* 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.
*/
enum compression
{
none = GTA_NONE, /**< \brief No compression */
zlib = GTA_ZLIB, /**< \brief ZLIB compression (fast, moderate compression rate) */
zlib1 = GTA_ZLIB1, /**< \brief ZLIB compression with level 1 */
zlib2 = GTA_ZLIB2, /**< \brief ZLIB compression with level 2 */
zlib3 = GTA_ZLIB3, /**< \brief ZLIB compression with level 3 */
zlib4 = GTA_ZLIB4, /**< \brief ZLIB compression with level 4 */
zlib5 = GTA_ZLIB5, /**< \brief ZLIB compression with level 5 */
zlib6 = GTA_ZLIB6, /**< \brief ZLIB compression with level 6 */
zlib7 = GTA_ZLIB7, /**< \brief ZLIB compression with level 7 */
zlib8 = GTA_ZLIB8, /**< \brief ZLIB compression with level 8 */
zlib9 = GTA_ZLIB9, /**< \brief ZLIB compression with level 9 */
bzip2 = GTA_BZIP2, /**< \brief BZIP2 compression (moderate speed, good compression rates) */
xz = GTA_XZ /**< \brief XZ compression (low/moderate speed, good/very good compression rates) */
};
/**
* \brief The exception class.
*
* The GTA C++ interface reports errors by throwing exceptions. You can use
* them just like std::exceptions, but you can also query the original
* \a gta::result that caused the exception.
*/
class exception : public std::exception
{
private:
static const int _whatsize = 96;
gta::result _r;
int _sys_errno;
char _what[_whatsize];
public:
/**
* \brief Constructor.
* \param s The action that failed.
* \param r The GTA result.
*/
exception(const char *s, gta::result r)
: _r(r), _sys_errno(r == system_error ? errno : 0)
{
const char *w = "";
switch (r)
{
case ok:
w = "success";
break;
case overflow:
w = "value too large for data type";
break;
case unsupported_data:
w = "unsupported data";
break;
case unexpected_eof:
w = "unexpected end of input";
break;
case invalid_data:
w = "invalid data";
break;
case system_error:
w = strerror(_sys_errno);
break;
}
#if defined _MSC_VER
_snprintf(_what, _whatsize, "%s: %s", s, w);
#else
snprintf(_what, _whatsize, "%s: %s", s, w);
#endif
}
/**
* \brief Get the original GTA result.
* \return The original GTA result.
*/
gta::result result() const
{
return _r;
}
/**
* \brief Get the original errno.
* \return The original errno.
*
* The original errno value is relevant if the original GTA result was
* \a gta::system_error.
*/
int sys_errno() const
{
return _sys_errno;
}
/**
* \brief Get a description.
* \return A description of the exception.
*/
virtual const char* what() const throw ()
{
return _what;
}
};
/**
* \brief Tag Lists.
*
* GTA stores meta information in tags.
* 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.
*/
class taglist
{
private:
gta_taglist_t *_taglist;
/** \cond INTERNAL */
void set(gta_taglist_t *taglist)
{
_taglist = taglist;
}
taglist()
{
}
/** \endcond */
public:
/**
* \brief Get the number of tags.
* \return The number of tags.
*/
uintmax_t tags() const
{
return gta_get_tags(_taglist);
}
/**
* \brief Get a tag name.
* \param i The tag index.
* \return The name of the tag.
*/
const char *name(uintmax_t i) const
{
return gta_get_tag_name(_taglist, i);
}
/**
* \brief Get a tag value.
* \param i The tag index.
* \return The value of the tag.
*/
const char *value(uintmax_t i) const
{
return gta_get_tag_value(_taglist, i);
}
/**
* \brief Get a tag value by its name.
* \param name The tag name.
* \return The tag value, or NULL if the tag name is not found.
*/
const char *get(const char *name) const
{
return gta_get_tag(_taglist, name);
}
/**
* \brief Set a tag.
* \param name The tag name.
* \param value The tag value.
*
* 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.
*/
void set(const char *name, const char *value)
{
gta_result_t r = gta_set_tag(_taglist, name, value);
if (r != GTA_OK)
{
throw exception("Cannot set GTA tag", static_cast<gta::result>(r));
}
}
/**
* \brief Unset a tag.
* \param name The tag name.
*
* Removes the tag with the given name, if it exists.
*/
void unset(const char *name)
{
gta_result_t r = gta_unset_tag(_taglist, name);
if (r != GTA_OK)
{
throw exception("Cannot unset GTA tag", static_cast<gta::result>(r));
}
}
/**
* \brief Unset all tags.
*
* Removes all tags.
*/
void unset_all()
{
gta_unset_all_tags(_taglist);
}
/**
* \brief Assignment operator.
* \param tl The tag list to copy.
*/
const taglist &operator=(const taglist &tl)
{
gta_result_t r = gta_clone_taglist(_taglist, tl._taglist);
if (r != GTA_OK)
{
throw exception("Cannot clone GTA taglist", static_cast<gta::result>(r));
}
return *this;
}
friend class header;
};
/**
* \brief Class for custom input/output.
*
* You can define your own custom input/output media by implementing this interface.
* The seek function is only required if you want to use the out-of-core data access
* funtions \a header::read_block() or \a header::write_block().
*/
class custom_io
{
public:
/**
* \brief Custom read function.
* \param buffer The destionation buffer.
* \param size The number of bytes to read.
* \param error The error flag.
*
* This function 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.
* The function must set errno to indicate the type of error. If the
* error type is unknown, errno should be set to EIO.
*/
virtual size_t read(void *buffer GTA_ATTR_UNUSED, size_t size GTA_ATTR_UNUSED, bool *error)
{
errno = ENOSYS;
*error = true;
return 0;
}
/**
* \brief Custom write function.
* \param buffer The source buffer.
* \param size The number of bytes to write.
* \param error The error flag.
*
* This function 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.
* The function must set errno to indicate the type of error. If the
* error type is unknown, errno should be set to EIO.
*/
virtual size_t write(const void *buffer GTA_ATTR_UNUSED, size_t size GTA_ATTR_UNUSED, bool *error)
{
errno = ENOSYS;
*error = true;
return 0;
}
/**
* \brief Tell if this object is seekable.
* \return Whether this object is seekable.
*
* This function must return true if the object is seekable, i.e. if the
* \a seek function can be used. Otherwise, it must return false.
*/
virtual bool seekable()
{
return false;
}
/**
* \brief Custom seek function.
* \param offset The position offset.
* \param whence SEEK_SET or SEEK_CUR.
* \param error The error flag.
*
* This function must change the 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.
* The function must set errno to indicate the type of error. If the
* error type is unknown, errno should be set to EIO.
*/
virtual void seek(intmax_t offset GTA_ATTR_UNUSED, int whence GTA_ATTR_UNUSED, bool *error)
{
errno = ENOSYS;
*error = true;
}
};
/** \cond INTERNAL */
class istream_io : public custom_io
{
private:
std::istream &_is;
public:
istream_io(std::istream &is)
: _is(is)
{
}
virtual size_t read(void *buffer, size_t size, bool *error)
{
try
{
_is.read(static_cast<char *>(buffer), size);
}
catch (...)
{
_is.setstate(std::ios::failbit);
}
if (!_is.good())
{
errno = EIO;
*error = true;
}
return size;
}
virtual bool seekable()
{
return (_is.tellg() != static_cast<std::streampos>(-1));
}
virtual void seek(intmax_t offset, int whence, bool *error)
{
if (offset > std::numeric_limits<std::streamoff>::max())
{
#ifdef EOVERFLOW
errno = EOVERFLOW;
#else
errno = EFBIG;
#endif
*error = true;
return;
}
try
{
_is.seekg(offset, whence == SEEK_SET ? std::ios_base::beg : std::ios_base::cur);
}
catch (...)
{
_is.setstate(std::ios::failbit);
}
if (!_is.good())
{
errno = EIO;
*error = true;
}
}
};
/** \endcond */
/** \cond INTERNAL */
class ostream_io : public custom_io
{
private:
std::ostream &_os;
public:
ostream_io(std::ostream &os)
: _os(os)
{
}
virtual size_t write(const void *buffer, size_t size, bool *error)
{
try
{
_os.write(static_cast<const char *>(buffer), size);
}
catch (...)
{
_os.setstate(std::ios::failbit);
}
if (!_os.good())
{
errno = EIO;
*error = true;
}
return size;
}
virtual bool seekable()
{
return (_os.tellp() != static_cast<std::streampos>(-1));
}
virtual void seek(intmax_t offset, int whence, bool *error)
{
if (offset > std::numeric_limits<std::streamoff>::max())
{
#ifdef EOVERFLOW
errno = EOVERFLOW;
#else
errno = EFBIG;
#endif
*error = true;
return;
}
try
{
_os.seekp(offset, whence == SEEK_SET ? std::ios_base::beg : std::ios_base::cur);
}
catch (...)
{
_os.setstate(std::ios::failbit);
}
if (!_os.good())
{
errno = EIO;
*error = true;
}
}
};
/** \endcond */
/** \cond INTERNAL */
inline size_t read_custom_io(intptr_t userdata, void *buffer, size_t size, int *error)
{
custom_io *io = reinterpret_cast<custom_io *>(userdata);
bool tmp_error = false;
size_t r = io->read(buffer, size, &tmp_error);
if (tmp_error)
{
*error = 1;
}
return r;
}
/** \endcond */
/** \cond INTERNAL */
inline size_t write_custom_io(intptr_t userdata, const void *buffer, size_t size, int *error)
{
custom_io *io = reinterpret_cast<custom_io *>(userdata);
bool tmp_error = false;
size_t r = io->write(buffer, size, &tmp_error);
if (tmp_error)
{
*error = 1;
}
return r;
}
/** \endcond */
/** \cond INTERNAL */
inline void seek_custom_io(intptr_t userdata, intmax_t offset, int whence, int *error)
{
custom_io *io = reinterpret_cast<custom_io *>(userdata);
bool tmp_error = false;
io->seek(offset, whence, &tmp_error);
if (tmp_error)
{
*error = 1;
}
}
/** \endcond */
/**
* \brief State for element-based input and output.
*
* See gta::header::read_elements() and gta::header::write_elements().
*/
class io_state
{
private:
gta_io_state_t *_state;
public:
io_state()
{
gta_result_t r = gta_create_io_state(&_state);
if (r != GTA_OK)
{
throw exception("Cannot initialize GTA i/o state", static_cast<gta::result>(r));
}
}
/** \cond INTERNAL */
io_state(const io_state &s)
{
gta_result_t r = gta_create_io_state(&_state);
if (r != GTA_OK)
{
throw exception("Cannot initialize GTA i/o state", static_cast<gta::result>(r));
}
r = gta_clone_io_state(_state, s._state);
if (r != GTA_OK)
{
throw exception("Cannot clone GTA i/o state", static_cast<gta::result>(r));
}
}
/** \endcond */
~io_state()
{
if (_state)
{
gta_destroy_io_state(_state);
}
}
/** \cond INTERNAL */
io_state &operator=(const io_state &s)
{
gta_result_t r = gta_clone_io_state(_state, s._state);
if (r != GTA_OK)
{
throw exception("Cannot clone GTA i/o state", static_cast<gta::result>(r));
}
return *this;
}
/** \endcond */
friend class header;
};
/**
* \brief The GTA header.
*
* Each GTA file is described by its header. It stores information about the
* array elements and the dimensions, and the various tag lists.
* Using the header, one can access the data in a GTA file, either by
* managaing the complete data in memory (if it fits), or by using
* out-of-core data read/write functions. There are also functions that help
* the application to implement its own data access scheme, if that is necessary.
*/
class header
{
private:
gta_header_t *_header;
taglist _global_taglist;
std::vector<taglist> _dimension_taglists;
std::vector<taglist> _component_taglists;
void reset_global_taglist()
{
_global_taglist.set(gta_get_global_taglist(_header));
}
void reset_component_taglists()
{
_component_taglists.resize(gta_get_components(_header), taglist());
for (uintmax_t i = 0; i < _component_taglists.size(); i++)
{
_component_taglists[i].set(gta_get_component_taglist(_header, i));
}
}
void reset_dimension_taglists()
{
_dimension_taglists.resize(gta_get_dimensions(_header), taglist());
for (size_t i = 0; i < _dimension_taglists.size(); i++)
{
_dimension_taglists[i].set(gta_get_dimension_taglist(_header, i));
}
}
void reset_taglists()
{
reset_global_taglist();
reset_component_taglists();
reset_dimension_taglists();
}
public:
/**
* \name Constructor / Destructor & Co.
*/
/*@{*/
/**
* \brief Constructor.
*/
header()
{
gta_result_t r = gta_create_header(&_header);
if (r != GTA_OK)
{
throw exception("Cannot initialize GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Copy constructor.
* \param hdr The header to copy.
*/
header(const header &hdr)
{
gta_result_t r;
r = gta_create_header(&_header);
if (r != GTA_OK)
{
throw exception("Cannot initialize GTA header", static_cast<gta::result>(r));
}
r = gta_clone_header(_header, hdr._header);
if (r != GTA_OK)
{
throw exception("Cannot clone GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Destructor.
*/
~header()
{
if (_header)
{
gta_destroy_header(_header);
}
}
/**
* \brief Assignment operator.
* \param hdr The header to copy.
*/
const header &operator=(const header &hdr)
{
gta_result_t r = gta_clone_header(_header, hdr._header);
if (r != GTA_OK)
{
throw exception("Cannot clone GTA header", static_cast<gta::result>(r));
}
reset_taglists();
return *this;
}
/*@}*/
/**
* \name Read and Write a Header
*/
/*@{*/
/**
* \brief Read a header.
* \param io Custom input object.
*/
void read_from(custom_io &io)
{
gta_result_t r = gta_read_header(_header, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Read a header.
* \param is Input stream.
*/
void read_from(std::istream &is)
{
istream_io io(is);
gta_result_t r = gta_read_header(_header, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Read a header.
* \param f Input C stream.
*/
void read_from(FILE *f)
{
gta_result_t r = gta_read_header_from_stream(_header, f);
if (r != GTA_OK)
{
throw exception("Cannot read GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Read a header.
* \param fd Input file descriptor.
*/
void read_from(int fd)
{
gta_result_t r = gta_read_header_from_fd(_header, fd);
if (r != GTA_OK)
{
throw exception("Cannot read GTA header", static_cast<gta::result>(r));
}
reset_taglists();
}
/**
* \brief Write a header.
* \param io Custom output object.
*/
void write_to(custom_io &io) const
{
gta_result_t r = gta_write_header(_header, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA header", static_cast<gta::result>(r));
}
}
/**
* \brief Write a header.
* \param os Output stream.
*/
void write_to(std::ostream &os) const
{
ostream_io io(os);
gta_result_t r = gta_write_header(_header, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA header", static_cast<gta::result>(r));
}
}
/**
* \brief Write a header.
* \param f Output C stream.
*/
void write_to(FILE *f) const
{
gta_result_t r = gta_write_header_to_stream(_header, f);
if (r != GTA_OK)
{
throw exception("Cannot write GTA header", static_cast<gta::result>(r));
}
}
/**
* \brief Write a header.
* \param fd Output file descriptor.
*/
void write_to(int fd) const
{
gta_result_t r = gta_write_header_to_fd(_header, fd);
if (r != GTA_OK)
{
throw exception("Cannot write GTA header", static_cast<gta::result>(r));
}
}
/*@}*/
/**
* \name Access Header Information
*/
/*@{*/
/**
* \brief Get the global tag list.
* \return The global tag list.
*/
const taglist &global_taglist() const
{
return _global_taglist;
}
/**
* \brief Get the global tag list.
* \return The global tag list.
*/
taglist &global_taglist()
{
return _global_taglist;
}
/**
* \brief Get the element size.
* \return The size of an array element.
*/
uintmax_t element_size() const
{
return gta_get_element_size(_header);
}
/**
* \brief Get the number of components.
* \return The number of components.
*/
uintmax_t components() const
{
return gta_get_components(_header);
}
/**
* \brief Get the component type.
* \param i The component index.
* \return The type of the component.
*/
type component_type(uintmax_t i) const
{
return static_cast<type>(gta_get_component_type(_header, i));
}
/**
* \brief Get the component size.
* \param i The component index.
* \return The size of the component.
*/
uintmax_t component_size(uintmax_t i) const
{
return gta_get_component_size(_header, i);
}
/**
* \brief Get the component tag list.
* \param i The component index.
* \return The tag list of the component.
*/
const taglist &component_taglist(uintmax_t i) const
{
return _component_taglists[i];
}
/**
* \brief Get the component tag list.
* \param i The component index.
* \return The tag list of the component.
*/
taglist &component_taglist(uintmax_t i)
{
return _component_taglists[i];
}
/**
* \brief Get the number of dimensions.
* \return The number of dimensions.
*/
uintmax_t dimensions() const
{
return gta_get_dimensions(_header);
}
/**
* \brief Get the size in a dimension.
* \param i The dimension index.
* \return The size in the dimension.
*/
uintmax_t dimension_size(uintmax_t i) const
{
return gta_get_dimension_size(_header, i);
}
/**
* \brief Get the dimension tag list.
* \param i The dimension index.
* \return The tag list of the dimension.
*/
const taglist &dimension_taglist(uintmax_t i) const
{
return _dimension_taglists[i];
}
/**
* \brief Get the dimension tag list.
* \param i The dimension index.
* \return The tag list of the dimension.
*/
taglist &dimension_taglist(uintmax_t i)
{
return _dimension_taglists[i];
}
/**
* \brief Get the total number of elements in the array.
* \return The total number of elements in the array.
*/
uintmax_t elements() const
{
return gta_get_elements(_header);
}
/**
* \brief Get the total size of the array.
* \return The size (in bytes) of the complete array.
*/
uintmax_t data_size() const
{
return gta_get_data_size(_header);
}
/**
* \brief Get the compression.
* \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.
*/
gta::compression compression() const
{
return static_cast<gta::compression>(gta_get_compression(_header));
}
/**
* \brief Set the compression.
* \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.
*/
void set_compression(gta::compression compression)
{
gta_set_compression(_header, static_cast<gta_compression_t>(compression));
}
/*@}*/
/**
* \name Define an Array
*/
/*@{*/
/**
* \brief Set the components of an array element.
* \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.
*
* 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
*/
void set_components(uintmax_t n, const type *types, const uintmax_t *sizes = NULL)
{
gta_result_t r = gta_set_components(_header, n, reinterpret_cast<const gta_type_t *>(types), sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA components", static_cast<gta::result>(r));
}
reset_component_taglists();
}
/**
* \brief Set the components of an array element (variant for elements with a single component).
* \param type The type of the component.
* \param size The size of the component, in case the type is \a gta::blob.
*/
void set_components(type type, uintmax_t size = 0)
{
gta::type types[] = { type };
uintmax_t sizes[] = { size };
gta_result_t r = gta_set_components(_header, 1, reinterpret_cast<gta_type_t *>(types), sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA components", static_cast<gta::result>(r));
}
reset_component_taglists();
}
/**
* \brief Set the components of an array element (variant for elements with two components).
* \param type0 The type of the first component.
* \param type1 The type of the second component.
* \param size0 The size of the first component, in case its type is \a gta::blob.
* \param size1 The size of the second component, in case its type is \a gta::blob.
*/
void set_components(type type0, type type1,
uintmax_t size0 = 0, uintmax_t size1 = 0)
{
type types[] = { type0, type1 };
uintmax_t sizes[] = { size0, size1 };
gta_result_t r = gta_set_components(_header, 2, reinterpret_cast<gta_type_t *>(types), sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA components", static_cast<gta::result>(r));
}
reset_component_taglists();
}
/**
* \brief Set the components of an array element (variant for elements with three components).
* \param type0 The type of the first component.
* \param type1 The type of the second component.
* \param type2 The type of the third component.
* \param size0 The size of the first component, in case its type is \a gta::blob.
* \param size1 The size of the second component, in case its type is \a gta::blob.
* \param size2 The size of the third component, in case its type is \a gta::blob.
*/
void set_components(type type0, type type1, type type2,
uintmax_t size0 = 0, uintmax_t size1 = 0, uintmax_t size2 = 0)
{
type types[] = { type0, type1, type2 };
uintmax_t sizes[] = { size0, size1, size2 };
gta_result_t r = gta_set_components(_header, 3, reinterpret_cast<gta_type_t *>(types), sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA components", static_cast<gta::result>(r));
}
reset_component_taglists();
}
/**
* \brief Set the components of an array element (variant for elements with four components).
* \param type0 The type of the first component.
* \param type1 The type of the second component.
* \param type2 The type of the third component.
* \param type3 The type of the fourth component.
* \param size0 The size of the first component, in case its type is \a gta::blob.
* \param size1 The size of the second component, in case its type is \a gta::blob.
* \param size2 The size of the third component, in case its type is \a gta::blob.
* \param size3 The size of the fourth component, in case its type is \a gta::blob.
*/
void set_components(type type0, type type1, type type2, type type3,
uintmax_t size0 = 0, uintmax_t size1 = 0, uintmax_t size2 = 0, uintmax_t size3 = 0)
{
type types[] = { type0, type1, type2, type3 };
uintmax_t sizes[] = { size0, size1, size2, size3 };
gta_result_t r = gta_set_components(_header, 4, reinterpret_cast<gta_type_t *>(types), sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA components", static_cast<gta::result>(r));
}
reset_component_taglists();
}
/**
* \brief Set the dimensions.
* \param n The number of dimensions.
* \param sizes The array sizes in each of the \n dimensions.
*
* Sets the array dimensions.\n
* All dimensions will initially have an empty tag list.
*/
void set_dimensions(uintmax_t n, const uintmax_t *sizes)
{
gta_result_t r = gta_set_dimensions(_header, n, sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA dimensions", static_cast<gta::result>(r));
}
reset_dimension_taglists();
}
/**
* \brief Set the dimensions (variant for one-dimensional arrays).
* \param size The size in the single dimension.
*/
void set_dimensions(uintmax_t size)
{
uintmax_t sizes[] = { size };
gta_result_t r = gta_set_dimensions(_header, 1, sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA dimensions", static_cast<gta::result>(r));
}
reset_dimension_taglists();
}
/**
* \brief Set the dimensions (variant for two-dimensional arrays).
* \param size0 The size in the first dimension.
* \param size1 The size in the second dimension.
*/
void set_dimensions(uintmax_t size0, uintmax_t size1)
{
uintmax_t sizes[] = { size0, size1 };
gta_result_t r = gta_set_dimensions(_header, 2, sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA dimensions", static_cast<gta::result>(r));
}
reset_dimension_taglists();
}
/**
* \brief Set the dimensions (variant for three-dimensional arrays).
* \param size0 The size in the first dimension.
* \param size1 The size in the second dimension.
* \param size2 The size in the third dimension.
*/
void set_dimensions(uintmax_t size0, uintmax_t size1, uintmax_t size2)
{
uintmax_t sizes[] = { size0, size1, size2 };
gta_result_t r = gta_set_dimensions(_header, 3, sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA dimensions", static_cast<gta::result>(r));
}
reset_dimension_taglists();
}
/**
* \brief Set the dimensions (variant for four-dimensional arrays).
* \param size0 The size in the first dimension.
* \param size1 The size in the second dimension.
* \param size2 The size in the third dimension.
* \param size3 The size in the fourth dimension.
*/
void set_dimensions(uintmax_t size0, uintmax_t size1, uintmax_t size2, uintmax_t size3)
{
uintmax_t sizes[] = { size0, size1, size2, size3 };
gta_result_t r = gta_set_dimensions(_header, 4, sizes);
if (r != GTA_OK)
{
throw exception("Cannot set GTA dimensions", static_cast<gta::result>(r));
}
reset_dimension_taglists();
}
/*@}*/
/**
* \name Read and Write Complete Arrays
*/
/*@{*/
/**
* \brief Read the complete data.
* \param io Custom input object.
* \param data Data buffer.
*
* Reads the complete data into the given buffer. The buffer must be large enough.
*/
void read_data(custom_io &io, void *data) const
{
gta_result_t r = gta_read_data(_header, data, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Read the complete data.
* \param is Input stream.
* \param data Data buffer.
*
* Reads the complete data into the given buffer. The buffer must be large enough.
*/
void read_data(std::istream &is, void *data) const
{
istream_io io(is);
gta_result_t r = gta_read_data(_header, data, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Read the complete data.
* \param f Input C stream.
* \param data Data buffer.
*
* Reads the complete data into the given buffer. The buffer must be large enough.
*/
void read_data(FILE *f, void *data) const
{
gta_result_t r = gta_read_data_from_stream(_header, data, f);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Read the complete data.
* \param fd Input file descriptor.
* \param data Data buffer.
*
* Reads the complete data into the given buffer. The buffer must be large enough.
*/
void read_data(int fd, void *data) const
{
gta_result_t r = gta_read_data_from_fd(_header, data, fd);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Skip the complete data.
* \param io Custom input object.
*
* Skips the complete data, so that the next GTA header can be read.
*/
void skip_data(custom_io &io) const
{
gta_result_t r = gta_skip_data(_header, read_custom_io,
(io.seekable() ? seek_custom_io : NULL),
reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot skip GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Skip the complete data.
* \param is Input stream.
*
* Skips the complete data, so that the next GTA header can be read.
*/
void skip_data(std::istream &is) const
{
istream_io io(is);
gta_result_t r = gta_skip_data(_header, read_custom_io,
(io.seekable() ? seek_custom_io : NULL),
reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot skip GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Skip the complete data.
* \param f Input C stream.
*
* Skips the complete data, so that the next GTA header can be read.
*/
void skip_data(FILE *f) const
{
gta_result_t r = gta_skip_data_from_stream(_header, f);
if (r != GTA_OK)
{
throw exception("Cannot skip GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Skip the complete data.
* \param fd Input file descriptor.
*
* Skips the complete data, so that the next GTA header can be read.
*/
void skip_data(int fd) const
{
gta_result_t r = gta_skip_data_from_fd(_header, fd);
if (r != GTA_OK)
{
throw exception("Cannot skip GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Write the complete data.
* \param io Custom output object.
* \param data Data buffer.
*/
void write_data(custom_io &io, const void *data) const
{
gta_result_t r = gta_write_data(_header, data, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Write the complete data.
* \param os Output stream.
* \param data Data buffer.
*/
void write_data(std::ostream &os, const void *data) const
{
ostream_io io(os);
gta_result_t r = gta_write_data(_header, data, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Write the complete data.
* \param f Output C stream.
* \param data Data buffer.
*/
void write_data(FILE *f, const void *data) const
{
gta_result_t r = gta_write_data_to_stream(_header, data, f);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Write the complete data.
* \param fd Output file descriptor.
* \param data Data buffer.
*/
void write_data(int fd, const void *data) const
{
gta_result_t r = gta_write_data_to_fd(_header, data, fd);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Copy the complete data.
* \param read_io Custom input object.
* \param write_header Output header.
* \param write_io Custom output object.
*/
void copy_data(custom_io &read_io, const header &write_header, custom_io &write_io) const
{
gta_result_t r = gta_copy_data(_header,
read_custom_io, reinterpret_cast<intptr_t>(&read_io),
write_header._header,
write_custom_io, reinterpret_cast<intptr_t>(&write_io));
if (r != GTA_OK)
{
throw exception("Cannot copy GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Copy the complete data.
* \param is Input stream.
* \param write_header Output header.
* \param os Output stream.
*/
void copy_data(std::istream &is, const header &write_header, std::ostream &os) const
{
istream_io read_io(is);
ostream_io write_io(os);
gta_result_t r = gta_copy_data(_header,
read_custom_io, reinterpret_cast<intptr_t>(&read_io),
write_header._header,
write_custom_io, reinterpret_cast<intptr_t>(&write_io));
if (r != GTA_OK)
{
throw exception("Cannot copy GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Copy the complete data.
* \param fi Input C stream.
* \param write_header Output header.
* \param fo Output C stream.
*/
void copy_data(FILE *fi, const header &write_header, FILE *fo) const
{
gta_result_t r = gta_copy_data_stream(_header, fi, write_header._header, fo);
if (r != GTA_OK)
{
throw exception("Cannot copy GTA data", static_cast<gta::result>(r));
}
}
/**
* \brief Copy the complete data.
* \param fdi Input file descriptor.
* \param write_header Output header.
* \param fdo Output file descriptor.
*/
void copy_data(int fdi, const header &write_header, int fdo) const
{
gta_result_t r = gta_copy_data_fd(_header, fdi, write_header._header, fdo);
if (r != GTA_OK)
{
throw exception("Cannot copy GTA data", static_cast<gta::result>(r));
}
}
/*@}*/
/**
* \name In-Memory Data Access
*/
/*@{*/
/**
* \brief Transform a linear index to array indices.
* \param index The linear index.
* \param indices The array indices.
*/
void linear_index_to_indices(uintmax_t index, uintmax_t *indices) const
{
gta_linear_index_to_indices(_header, index, indices);
}
/**
* \brief Transform array indices to a linear index.
* \param indices The array indices.
* \return The linear index.
*/
uintmax_t indices_to_linear_index(const uintmax_t *indices) const
{
return gta_indices_to_linear_index(_header, indices);
}
/**
* \brief Get an array element.
* \param data Data Buffer.
* \param indices Indices for each dimension of the array.
* \return A pointer to the element.
*/
const void *element(const void *data, const uintmax_t *indices) const
{
return gta_get_element_const(_header, data, indices);
}
/**
* \brief Get an array element.
* \param data Data Buffer.
* \param indices Indices for each dimension of the array.
* \return A pointer to the element.
*/
void *element(void *data, const uintmax_t *indices) const
{
return gta_get_element(_header, data, indices);
}
/**
* \brief Get an array element via a linear index.
* \param data Data Buffer.
* \param index Index of the element.
* \return A pointer to the element.
*
* This function not only works for one-dimensional arrays in the obvious way,
* but also for multidimensional arrays by using \a index as a linear index to
* the array data.
*/
const void *element(const void *data, uintmax_t index) const
{
return gta_get_element_linear_const(_header, data, index);
}
/**
* \brief Get an array element via a linear index.
* \param data Data Buffer.
* \param index Index of the element.
* \return A pointer to the element.
*
* This function not only works for one-dimensional arrays in the obvious way,
* but also for multidimensional arrays by using \a index as a linear index to
* the array data.
*/
void *element(void *data, uintmax_t index) const
{
return gta_get_element_linear(_header, data, index);
}
/**
* \brief Get an array element (variant for two-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \return A pointer to the element.
*/
const void *element(const void *data, uintmax_t index0, uintmax_t index1) const
{
uintmax_t indices[] = { index0, index1 };
return gta_get_element_const(_header, data, indices);
}
/**
* \brief Get an array element (variant for two-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \return A pointer to the element.
*/
void *element(void *data, uintmax_t index0, uintmax_t index1) const
{
uintmax_t indices[] = { index0, index1 };
return gta_get_element(_header, data, indices);
}
/**
* \brief Get an array element (variant for three-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \param index2 Index of the element in the third dimension.
* \return A pointer to the element.
*/
const void *element(const void *data, uintmax_t index0, uintmax_t index1, uintmax_t index2) const
{
uintmax_t indices[] = { index0, index1, index2 };
return gta_get_element_const(_header, data, indices);
}
/**
* \brief Get an array element (variant for three-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \param index2 Index of the element in the third dimension.
* \return A pointer to the element.
*/
void *element(void *data, uintmax_t index0, uintmax_t index1, uintmax_t index2) const
{
uintmax_t indices[] = { index0, index1, index2 };
return gta_get_element(_header, data, indices);
}
/**
* \brief Get an array element (variant for four-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \param index2 Index of the element in the third dimension.
* \param index3 Index of the element in the fourth dimension.
* \return A pointer to the element.
*/
const void *element(const void *data, uintmax_t index0, uintmax_t index1, uintmax_t index2, uintmax_t index3) const
{
uintmax_t indices[] = { index0, index1, index2, index3 };
return gta_get_element_const(_header, data, indices);
}
/**
* \brief Get an array element (variant for four-dimensional arrays).
* \param data Data Buffer.
* \param index0 Index of the element in the first dimension.
* \param index1 Index of the element in the second dimension.
* \param index2 Index of the element in the third dimension.
* \param index3 Index of the element in the fourth dimension.
* \return A pointer to the element.
*/
void *element(void *data, uintmax_t index0, uintmax_t index1, uintmax_t index2, uintmax_t index3) const
{
uintmax_t indices[] = { index0, index1, index2, index3 };
return gta_get_element(_header, data, indices);
}
/**
* \brief Get a component of an array element.
* \param element Element.
* \param i Component index.
* \return A pointer to the component.
*/
const void *component(const void *element, uintmax_t i) const
{
return gta_get_component_const(_header, element, i);
}
/**
* \brief Get a component of an array element.
* \param element Element.
* \param i Component index.
* \return A pointer to the component.
*/
void *component(void *element, uintmax_t i) const
{
return gta_get_component(_header, element, i);
}
/*@}*/
/**
* \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 object gta::io_state. The same state object must be
* used until all elements are read or written, or until an error occurs.
*/
/*@{*/
/**
* \brief Read array elements.
* \param state The input/output state.
* \param io Custom input object.
* \param n The number of elements to read.
* \param buf The buffer for the elements.
*
* Reads the given number of elements into the given buffer, which must be large enough.
*/
void read_elements(io_state &state, custom_io &io, uintmax_t n, void *buf) const
{
gta_result_t r = gta_read_elements(_header, state._state, n, buf, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Read array elements.
* \param state The input/output state.
* \param is Input stream.
* \param n The number of elements to read.
* \param buf The buffer for the elements.
*
* Reads the given number of elements into the given buffer, which must be large enough.
*/
void read_elements(io_state &state, std::istream &is, uintmax_t n, void *buf) const
{
istream_io io(is);
gta_result_t r = gta_read_elements(_header, state._state, n, buf, read_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Read array elements.
* \param state The input/output state.
* \param f Input stream.
* \param n The number of elements to read.
* \param buf The buffer for the elements.
*
* Reads the given number of elements into the given buffer, which must be large enough.
*/
void read_elements(io_state &state, FILE *f, uintmax_t n, void *buf) const
{
gta_result_t r = gta_read_elements_from_stream(_header, state._state, n, buf, f);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Read array elements.
* \param state The input/output state.
* \param fd Input file descriptor.
* \param n The number of elements to read.
* \param buf The buffer for the elements.
*
* Reads the given number of elements into the given buffer, which must be large enough.
*/
void read_elements(io_state &state, int fd, uintmax_t n, void *buf) const
{
gta_result_t r = gta_read_elements_from_fd(_header, state._state, n, buf, fd);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Write array elements.
* \param state The input/output state.
* \param io Custom output object.
* \param n The number of elements to write.
* \param buf The buffer for the elements.
*
* Writes the given number of elements from the given buffer.
*/
void write_elements(io_state &state, custom_io &io, uintmax_t n, const void *buf) const
{
gta_result_t r = gta_write_elements(_header, state._state, n, buf, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Write array elements.
* \param state The input/output state.
* \param os Output stream.
* \param n The number of elements to write.
* \param buf The buffer for the elements.
*
* Writes the given number of elements from the given buffer.
*/
void write_elements(io_state &state, std::ostream &os, uintmax_t n, const void *buf) const
{
ostream_io io(os);
gta_result_t r = gta_write_elements(_header, state._state, n, buf, write_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Write array elements.
* \param state The input/output state.
* \param f Output stream.
* \param n The number of elements to write.
* \param buf The buffer for the elements.
*
* Writes the given number of elements from the given buffer.
*/
void write_elements(io_state &state, FILE *f, uintmax_t n, const void *buf) const
{
gta_result_t r = gta_write_elements_to_stream(_header, state._state, n, buf, f);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data elements", static_cast<gta::result>(r));
}
}
/**
* \brief Write array elements.
* \param state The input/output state.
* \param fd Output file descriptor.
* \param n The number of elements to write.
* \param buf The buffer for the elements.
*
* Writes the given number of elements from the given buffer.
*/
void write_elements(io_state &state, int fd, uintmax_t n, const void *buf) const
{
gta_result_t r = gta_write_elements_to_fd(_header, state._state, n, buf, fd);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data elements", static_cast<gta::result>(r));
}
}
/*@}*/
/**
* \name Read and Write Array Blocks
*
* These functions can only be used if the data is not compressed (see \a header::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 io Custom input object.
* \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 Block buffer.
*
* 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.
*/
void read_block(custom_io &io, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
void *block) const
{
gta_result_t r = gta_read_block(_header, data_offset,
lower_coordinates, higher_coordinates, block,
read_custom_io, seek_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Read an array block.
* \param is Input stream.
* \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 Block buffer.
*
* 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.
*/
void read_block(std::istream &is, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
void *block) const
{
istream_io io(is);
gta_result_t r = gta_read_block(_header, data_offset,
lower_coordinates, higher_coordinates, block,
read_custom_io, seek_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot read GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Read an array block.
* \param f Input C stream.
* \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 Block buffer.
*
* 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.
*/
void read_block(FILE *f, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
void *block) const
{
gta_result_t r = gta_read_block_from_stream(_header, data_offset,
lower_coordinates, higher_coordinates, block, f);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Read an array block.
* \param fd Input file descriptor.
* \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 Block buffer.
*
* 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.
*/
void read_block(int fd, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
void *block) const
{
gta_result_t r = gta_read_block_from_fd(_header, data_offset,
lower_coordinates, higher_coordinates, block, fd);
if (r != GTA_OK)
{
throw exception("Cannot read GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Write an array block.
* \param io Custom output object.
* \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 Block buffer.
*
* This function modifies the file position indicator of the output.
*/
void write_block(custom_io &io, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
const void *block) const
{
gta_result_t r = gta_write_block(_header, data_offset,
lower_coordinates, higher_coordinates, block,
write_custom_io, seek_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Write an array block.
* \param os Output stream.
* \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 Block buffer.
*
* This function modifies the file position indicator of the output.
*/
void write_block(std::ostream &os, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
const void *block) const
{
ostream_io io(os);
gta_result_t r = gta_write_block(_header, data_offset,
lower_coordinates, higher_coordinates, block,
write_custom_io, seek_custom_io, reinterpret_cast<intptr_t>(&io));
if (r != GTA_OK)
{
throw exception("Cannot write GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Write an array block.
* \param f Output C stream.
* \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 Block buffer.
*
* This function modifies the file position indicator of the output.
*/
void write_block(FILE *f, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
const void *block) const
{
gta_result_t r = gta_write_block_to_stream(_header, data_offset,
lower_coordinates, higher_coordinates, block, f);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data block", static_cast<gta::result>(r));
}
}
/**
* \brief Write an array block.
* \param fd Output file descriptor.
* \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 Block buffer.
*
* This function modifies the file position indicator of the output.
*/
void write_block(int fd, uintmax_t data_offset,
const uintmax_t *lower_coordinates, const uintmax_t *higher_coordinates,
const void *block) const
{
gta_result_t r = gta_write_block_to_fd(_header, data_offset,
lower_coordinates, higher_coordinates, block, fd);
if (r != GTA_OK)
{
throw exception("Cannot write GTA data block", static_cast<gta::result>(r));
}
}
/*@}*/
};
/**
* \name Version information
*/
/*@{*/
/**
* \brief Get the version string.
* \return The version string "MAJOR.MINOR.PATCH"
*/
inline const char *version()
{
return gta_version(NULL, NULL, NULL);
}
/**
* \brief Get the major version number.
* \return The major version number.
*/
inline int version_major()
{
int major;
gta_version(&major, NULL, NULL);
return major;
}
/**
* \brief Get the minor version number.
* \return The minor version number.
*/
inline int version_minor()
{
int minor;
gta_version(NULL, &minor, NULL);
return minor;
}
/**
* \brief Get the patch version number.
* \return The patch version number.
*/
inline int version_patch()
{
int patch;
gta_version(NULL, NULL, &patch);
return patch;
}
/*@}*/
}
#ifdef _MSC_VER
# pragma warning (pop)
#endif
#endif