Class modeling an attribute that has a name, a value and a type, and is typically used to describe a metadata item. More...

#include <gdal_priv.h>

Inheritance diagram for GDALAttribute:

Public Types
typedef bool(*	FuncProcessPerChunkType) (GDALAbstractMDArray array, const GUInt64 chunkArrayStartIdx, const size_t chunkCount, GUInt64 iCurChunk, GUInt64 nChunkCount, void pUserData)
	Type of pfnFunc argument of ProcessPerChunk(). More...

Public Member Functions
std::vector< GUInt64 >	GetDimensionsSize () const
	Return the size of the dimensions of the attribute. More...

GDALRawResult	ReadAsRaw () const
	Return the raw value of an attribute. More...

const char *	ReadAsString () const
	Return the value of an attribute as a string. More...

int	ReadAsInt () const
	Return the value of an attribute as a integer. More...

int64_t	ReadAsInt64 () const
	Return the value of an attribute as an int64_t. More...

double	ReadAsDouble () const
	Return the value of an attribute as a double. More...

CPLStringList	ReadAsStringArray () const
	Return the value of an attribute as an array of strings. More...

std::vector< int >	ReadAsIntArray () const
	Return the value of an attribute as an array of integers. More...

std::vector< int64_t >	ReadAsInt64Array () const
	Return the value of an attribute as an array of int64_t. More...

std::vector< double >	ReadAsDoubleArray () const
	Return the value of an attribute as an array of double. More...

bool	Write (const void *pabyValue, size_t nLen)
	Write an attribute from raw values expressed in GetDataType() More...

bool	Write (const char *)
	Write an attribute from a string value. More...

bool	WriteInt (int)
	Write an attribute from a integer value. More...

bool	WriteInt64 (int64_t)
	Write an attribute from an int64_t value. More...

bool	Write (double)
	Write an attribute from a double value. More...

bool	Write (CSLConstList)
	Write an attribute from an array of strings. More...

bool	Write (const int *, size_t)
	Write an attribute from an array of int. More...

bool	Write (const int64_t *, size_t)
	Write an attribute from an array of int64_t. More...

bool	Write (const double *, size_t)
	Write an attribute from an array of double. More...

bool	Write (const GUInt64 arrayStartIdx, const size_t count, const GInt64 arrayStep, const GPtrDiff_t bufferStride, const GDALExtendedDataType &bufferDataType, const void pSrcBuffer, const void pSrcBufferAllocStart=nullptr, size_t nSrcBufferAllocSize=0)
	Write part or totality of a multidimensional array or attribute. More...

const std::string &	GetName () const
	Return the name of an array or attribute. More...

const std::string &	GetFullName () const
	Return the name of an array or attribute. More...

GUInt64	GetTotalElementsCount () const
	Return the total number of values in the array. More...

virtual size_t	GetDimensionCount () const
	Return the number of dimensions. More...

virtual const std::vector< std::shared_ptr< GDALDimension > > &	GetDimensions () const =0
	Return the dimensions of an attribute/array. More...

virtual const GDALExtendedDataType &	GetDataType () const =0
	Return the data type of an attribute/array. More...

virtual std::vector< GUInt64 >	GetBlockSize () const
	Return the "natural" block size of the array along all dimensions. More...

virtual std::vector< size_t >	GetProcessingChunkSize (size_t nMaxChunkMemory) const
	Return an optimal chunk size for read/write operations, given the natural block size and memory constraints specified. More...

virtual bool	ProcessPerChunk (const GUInt64 arrayStartIdx, const GUInt64 count, const size_t chunkSize, FuncProcessPerChunkType pfnFunc, void pUserData)
	Call a user-provided function to operate on an array chunk by chunk. More...

virtual bool	Read (const GUInt64 arrayStartIdx, const size_t count, const GInt64 arrayStep, const GPtrDiff_t bufferStride, const GDALExtendedDataType &bufferDataType, void pDstBuffer, const void pDstBufferAllocStart=nullptr, size_t nDstBufferAllocSize=0) const
	Read part or totality of a multidimensional array or attribute. More...

bool	Write (const GUInt64 arrayStartIdx, const size_t count, const GInt64 arrayStep, const GPtrDiff_t bufferStride, const GDALExtendedDataType &bufferDataType, const void pSrcBuffer, const void pSrcBufferAllocStart=nullptr, size_t nSrcBufferAllocSize=0)
	Write part or totality of a multidimensional array or attribute. More...

virtual bool	Rename (const std::string &osNewName)
	Rename the attribute/array. More...

Detailed Description

Class modeling an attribute that has a name, a value and a type, and is typically used to describe a metadata item.

The value can be (for the HDF5 format) in the general case a multidimensional array of "any" type (in most cases, this will be a single value of string or numeric type)

This is based on the HDF5 attribute concept

Since: GDAL 3.1

Member Typedef Documentation

◆ FuncProcessPerChunkType

typedef bool(* GDALAbstractMDArray::FuncProcessPerChunkType) (GDALAbstractMDArray *array, const GUInt64 *chunkArrayStartIdx, const size_t *chunkCount, GUInt64 iCurChunk, GUInt64 nChunkCount, void *pUserData)

inherited

Type of pfnFunc argument of ProcessPerChunk().

Parameters

array	Array on which ProcessPerChunk was called.
chunkArrayStartIdx	Values representing the starting index to use in each dimension (in [0, aoDims[i].GetSize()-1] range) for the current chunk. Will be nullptr for a zero-dimensional array.
chunkCount	Values representing the number of values to use in each dimension for the current chunk. Will be nullptr for a zero-dimensional array.
iCurChunk	Number of current chunk being processed. In [1, nChunkCount] range.
nChunkCount	Total number of chunks to process.
pUserData	User data.

Returns: return true in case of success.

Member Function Documentation

◆ GetBlockSize()

std::vector< GUInt64 > GDALAbstractMDArray::GetBlockSize ( ) const

virtualinherited

Return the "natural" block size of the array along all dimensions.

Some drivers might organize the array in tiles/blocks and reading/writing aligned on those tile/block boundaries will be more efficient.

The returned number of elements in the vector is the same as GetDimensionCount(). A value of 0 should be interpreted as no hint regarding the natural block size along the considered dimension. "Flat" arrays will typically return a vector of values set to 0.

The default implementation will return a vector of values set to 0.

This method is used by GetProcessingChunkSize().

Pedantic note: the returned type is GUInt64, so in the highly unlikeley theoretical case of a 32-bit platform, this might exceed its size_t allocation capabilities.

This is the same as the C function GDALMDArrayGetBlockSize().

Returns: the block size, in number of elements along each dimension.

◆ GetDataType()

GDALAbstractMDArray::GetDataType ( ) const

pure virtualinherited

Return the data type of an attribute/array.

This is the same as the C functions GDALMDArrayGetDataType() and GDALAttributeGetDataType()

◆ GetDimensionCount()

size_t GDALAbstractMDArray::GetDimensionCount ( ) const

virtualinherited

Return the number of dimensions.

Default implementation is GetDimensions().size(), and may be overridden by drivers if they have a faster / less expensive implementations.

This is the same as the C function GDALMDArrayGetDimensionCount() or GDALAttributeGetDimensionCount().

◆ GetDimensions()

GDALAbstractMDArray::GetDimensions ( ) const

pure virtualinherited

Return the dimensions of an attribute/array.

This is the same as the C functions GDALMDArrayGetDimensions() and similar to GDALAttributeGetDimensionsSize().

◆ GetDimensionsSize()

std::vector< GUInt64 > GDALAttribute::GetDimensionsSize ( ) const

Return the size of the dimensions of the attribute.

This will be an empty array for a scalar (single value) attribute.

This is the same as the C function GDALAttributeGetDimensionsSize().

◆ GetFullName()

const std::string& GDALAbstractMDArray::GetFullName ( ) const

inlineinherited

Return the name of an array or attribute.

This is the same as the C function GDALMDArrayGetFullName() or GDALAttributeGetFullName().

◆ GetName()

const std::string& GDALAbstractMDArray::GetName ( ) const

inlineinherited

Return the name of an array or attribute.

This is the same as the C function GDALMDArrayGetName() or GDALAttributeGetName().

◆ GetProcessingChunkSize()

std::vector< size_t > GDALAbstractMDArray::GetProcessingChunkSize ( size_t nMaxChunkMemory ) const

virtualinherited

Return an optimal chunk size for read/write operations, given the natural block size and memory constraints specified.

This method will use GetBlockSize() to define a chunk whose dimensions are multiple of those returned by GetBlockSize() (unless the block define by GetBlockSize() is larger than nMaxChunkMemory, in which case it will be returned by this method).

This is the same as the C function GDALMDArrayGetProcessingChunkSize().

Parameters

nMaxChunkMemory Maximum amount of memory, in bytes, to use for the chunk.

Returns: the chunk size, in number of elements along each dimension.

◆ GetTotalElementsCount()

GUInt64 GDALAbstractMDArray::GetTotalElementsCount ( ) const

inherited

Return the total number of values in the array.

This is the same as the C functions GDALMDArrayGetTotalElementsCount() and GDALAttributeGetTotalElementsCount().

◆ ProcessPerChunk()

bool GDALAbstractMDArray::ProcessPerChunk	(	const GUInt64 *	arrayStartIdx,
		const GUInt64 *	count,
		const size_t *	chunkSize,
		FuncProcessPerChunkType	pfnFunc,
		void *	pUserData
	)

virtualinherited

Call a user-provided function to operate on an array chunk by chunk.

This method is to be used when doing operations on an array, or a subset of it, in a chunk by chunk way.

Parameters

arrayStartIdx	Values representing the starting index to use in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to use in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
chunkSize	Values representing the chunk size in each dimension. Might typically the output of GetProcessingChunkSize(). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
pfnFunc	User-provided function of type FuncProcessPerChunkType. Must NOT be nullptr.
pUserData	Pointer to pass as the value of the pUserData argument of FuncProcessPerChunkType. Might be nullptr (depends on pfnFunc.

Returns: true in case of success.

◆ Read()

bool GDALAbstractMDArray::Read	(	const GUInt64 *	arrayStartIdx,
		const size_t *	count,
		const GInt64 *	arrayStep,
		const GPtrDiff_t *	bufferStride,
		const GDALExtendedDataType &	bufferDataType,
		void *	pDstBuffer,
		const void *	pDstBufferAllocStart = `nullptr`,
		size_t	nDstBufferAllocSize = `0`
	)		const

virtualinherited

Read part or totality of a multidimensional array or attribute.

This will extract the content of a hyper-rectangle from the array into a user supplied buffer.

If bufferDataType is of type string, the values written in pDstBuffer will be char* pointers and the strings should be freed with CPLFree().

This is the same as the C function GDALMDArrayRead().

Parameters

arrayStartIdx	Values representing the starting index to read in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to extract in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStep	Spacing between values to extract in each dimension. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. If set to nullptr, [1, 1, ... 1] will be used as a default to indicate consecutive elements.
bufferStride	Spacing between values to store in pDstBuffer. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. Negative values are possible (for example to reorder from bottom-to-top to top-to-bottom). If set to nullptr, will be set so that pDstBuffer is written in a compact way, with elements of the last / fastest varying dimension being consecutive.
bufferDataType	Data type of values in pDstBuffer.
pDstBuffer	User buffer to store the values read. Should be big enough to store the number of values indicated by count[] and with the spacing of bufferStride[].
pDstBufferAllocStart	Optional pointer that can be used to validate the validty of pDstBuffer. pDstBufferAllocStart should be the pointer returned by the malloc() or equivalent call used to allocate the buffer. It will generally be equal to pDstBuffer (when bufferStride[] values are all positive), but not necessarily. If specified, nDstBufferAllocSize should be also set to the appropriate value. If no validation is needed, nullptr can be passed.
nDstBufferAllocSize	Optional buffer size, that can be used to validate the validty of pDstBuffer. This is the size of the buffer starting at pDstBufferAllocStart. If specified, pDstBufferAllocStart should be also set to the appropriate value. If no validation is needed, 0 can be passed.

Returns: true in case of success.

Reimplemented in GDALMDArray.

◆ ReadAsDouble()

double GDALAttribute::ReadAsDouble ( ) const

Return the value of an attribute as a double.

This function will only return the first element if there are several.

It can fail if its value can not be converted to double.

This is the same as the C function GDALAttributeReadAsInt()

Returns: a double value.

◆ ReadAsDoubleArray()

std::vector< double > GDALAttribute::ReadAsDoubleArray ( ) const

Return the value of an attribute as an array of double.

This is the same as the C function GDALAttributeReadAsDoubleArray().

◆ ReadAsInt()

int GDALAttribute::ReadAsInt ( ) const

Return the value of an attribute as a integer.

This function will only return the first element if there are several.

It can fail if its value can not be converted to integer.

This is the same as the C function GDALAttributeReadAsInt()

Returns: a integer, or INT_MIN in case of error.

◆ ReadAsInt64()

int64_t GDALAttribute::ReadAsInt64 ( ) const

Return the value of an attribute as an int64_t.

This function will only return the first element if there are several.

It can fail if its value can not be converted to long.

This is the same as the C function GDALAttributeReadAsInt64()

Returns: an int64_t, or INT64_MIN in case of error.

◆ ReadAsInt64Array()

std::vector< int64_t > GDALAttribute::ReadAsInt64Array ( ) const

Return the value of an attribute as an array of int64_t.

This is the same as the C function GDALAttributeReadAsInt64Array().

◆ ReadAsIntArray()

std::vector< int > GDALAttribute::ReadAsIntArray ( ) const

Return the value of an attribute as an array of integers.

This is the same as the C function GDALAttributeReadAsIntArray().

◆ ReadAsRaw()

GDALRawResult GDALAttribute::ReadAsRaw ( ) const

Return the raw value of an attribute.

This is the same as the C function GDALAttributeReadAsRaw().

◆ ReadAsString()

const char * GDALAttribute::ReadAsString ( ) const

Return the value of an attribute as a string.

The returned string should not be freed, and its lifetime does not excess a next call to ReadAsString() on the same object, or the deletion of the object itself.

This function will only return the first element if there are several.

This is the same as the C function GDALAttributeReadAsString()

Returns: a string, or nullptr.

◆ ReadAsStringArray()

CPLStringList GDALAttribute::ReadAsStringArray ( ) const

Return the value of an attribute as an array of strings.

This is the same as the C function GDALAttributeReadAsStringArray()

◆ Rename()

bool GDALAbstractMDArray::Rename ( const std::string & osNewName )

virtualinherited

Rename the attribute/array.

This is not implemented by all drivers.

Drivers known to implement it: MEM, netCDF, Zarr.

This is the same as the C functions GDALMDArrayRename() or GDALAttributeRename().

Parameters

osNewName New name.

Returns: true in case of success

Since: GDAL 3.8

◆ Write() [1/9]

bool GDALAttribute::Write ( const char * pszValue )

Write an attribute from a string value.

Type conversion will be performed if needed. If the attribute contains multiple values, only the first one will be updated.

This is the same as the C function GDALAttributeWriteString().

Parameters

pszValue Pointer to a string.

Returns: true in case of success.

◆ Write() [2/9]

bool GDALAttribute::Write	(	const double *	vals,
		size_t	nVals
	)

Write an attribute from an array of double.

Type conversion will be performed if needed.

Exactly GetTotalElementsCount() strings must be provided

This is the same as the C function GDALAttributeWriteDoubleArray()

Parameters

vals	Array of double.
nVals	Should be equal to GetTotalElementsCount().

Returns: true in case of success.

◆ Write() [3/9]

bool GDALAbstractMDArray::Write	(	const GUInt64 *	arrayStartIdx,
		const size_t *	count,
		const GInt64 *	arrayStep,
		const GPtrDiff_t *	bufferStride,
		const GDALExtendedDataType &	bufferDataType,
		const void *	pSrcBuffer,
		const void *	pSrcBufferAllocStart = `nullptr`,
		size_t	nSrcBufferAllocSize = `0`
	)

inherited

Write part or totality of a multidimensional array or attribute.

This will set the content of a hyper-rectangle into the array from a user supplied buffer.

If bufferDataType is of type string, the values read from pSrcBuffer will be char* pointers.

This is the same as the C function GDALMDArrayWrite().

Parameters

arrayStartIdx	Values representing the starting index to write in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to write in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStep	Spacing between values to write in each dimension. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. If set to nullptr, [1, 1, ... 1] will be used as a default to indicate consecutive elements.
bufferStride	Spacing between values to read from pSrcBuffer. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. Negative values are possible (for example to reorder from bottom-to-top to top-to-bottom). If set to nullptr, will be set so that pSrcBuffer is written in a compact way, with elements of the last / fastest varying dimension being consecutive.
bufferDataType	Data type of values in pSrcBuffer.
pSrcBuffer	User buffer to read the values from. Should be big enough to store the number of values indicated by count[] and with the spacing of bufferStride[].
pSrcBufferAllocStart	Optional pointer that can be used to validate the validty of pSrcBuffer. pSrcBufferAllocStart should be the pointer returned by the malloc() or equivalent call used to allocate the buffer. It will generally be equal to pSrcBuffer (when bufferStride[] values are all positive), but not necessarily. If specified, nSrcBufferAllocSize should be also set to the appropriate value. If no validation is needed, nullptr can be passed.
nSrcBufferAllocSize	Optional buffer size, that can be used to validate the validty of pSrcBuffer. This is the size of the buffer starting at pSrcBufferAllocStart. If specified, pDstBufferAllocStart should be also set to the appropriate value. If no validation is needed, 0 can be passed.

Returns: true in case of success.

◆ Write() [4/9]

bool GDALAbstractMDArray::Write

Write part or totality of a multidimensional array or attribute.

This will set the content of a hyper-rectangle into the array from a user supplied buffer.

If bufferDataType is of type string, the values read from pSrcBuffer will be char* pointers.

This is the same as the C function GDALMDArrayWrite().

Parameters

arrayStartIdx	Values representing the starting index to write in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to write in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStep	Spacing between values to write in each dimension. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. If set to nullptr, [1, 1, ... 1] will be used as a default to indicate consecutive elements.
bufferStride	Spacing between values to read from pSrcBuffer. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. Negative values are possible (for example to reorder from bottom-to-top to top-to-bottom). If set to nullptr, will be set so that pSrcBuffer is written in a compact way, with elements of the last / fastest varying dimension being consecutive.
bufferDataType	Data type of values in pSrcBuffer.
pSrcBuffer	User buffer to read the values from. Should be big enough to store the number of values indicated by count[] and with the spacing of bufferStride[].
pSrcBufferAllocStart	Optional pointer that can be used to validate the validty of pSrcBuffer. pSrcBufferAllocStart should be the pointer returned by the malloc() or equivalent call used to allocate the buffer. It will generally be equal to pSrcBuffer (when bufferStride[] values are all positive), but not necessarily. If specified, nSrcBufferAllocSize should be also set to the appropriate value. If no validation is needed, nullptr can be passed.
nSrcBufferAllocSize	Optional buffer size, that can be used to validate the validty of pSrcBuffer. This is the size of the buffer starting at pSrcBufferAllocStart. If specified, pDstBufferAllocStart should be also set to the appropriate value. If no validation is needed, 0 can be passed.

Returns: true in case of success.

◆ Write() [5/9]

bool GDALAttribute::Write	(	const int *	vals,
		size_t	nVals
	)

Write an attribute from an array of int.

Type conversion will be performed if needed.

Exactly GetTotalElementsCount() strings must be provided

This is the same as the C function GDALAttributeWriteIntArray()

Parameters

vals	Array of int.
nVals	Should be equal to GetTotalElementsCount().

Returns: true in case of success.

◆ Write() [6/9]

bool GDALAttribute::Write	(	const int64_t *	vals,
		size_t	nVals
	)

Write an attribute from an array of int64_t.

Type conversion will be performed if needed.

Exactly GetTotalElementsCount() strings must be provided

This is the same as the C function GDALAttributeWriteLongArray()

Parameters

vals	Array of int64_t.
nVals	Should be equal to GetTotalElementsCount().

Returns: true in case of success.

◆ Write() [7/9]

bool GDALAttribute::Write	(	const void *	pabyValue,
		size_t	nLen
	)

Write an attribute from raw values expressed in GetDataType()

The values should be provided in the type of GetDataType() and there should be exactly GetTotalElementsCount() of them. If GetDataType() is a string, each value should be a char* pointer.

This is the same as the C function GDALAttributeWriteRaw().

Parameters

pabyValue	Buffer of nLen bytes.
nLen	Size of pabyValue in bytes. Should be equal to GetTotalElementsCount() * GetDataType().GetSize()

Returns: true in case of success.

◆ Write() [8/9]

bool GDALAttribute::Write ( CSLConstList vals )

Write an attribute from an array of strings.

Type conversion will be performed if needed.

Exactly GetTotalElementsCount() strings must be provided

This is the same as the C function GDALAttributeWriteStringArray().

Parameters

vals	Array of strings.

Returns: true in case of success.

◆ Write() [9/9]

bool GDALAttribute::Write ( double dfVal )

Write an attribute from a double value.

Type conversion will be performed if needed. If the attribute contains multiple values, only the first one will be updated.

This is the same as the C function GDALAttributeWriteDouble().

Parameters

dfVal Value.

Returns: true in case of success.

◆ WriteInt()

bool GDALAttribute::WriteInt ( int nVal )

Write an attribute from a integer value.

Type conversion will be performed if needed. If the attribute contains multiple values, only the first one will be updated.

This is the same as the C function GDALAttributeWriteInt().

Parameters

nVal Value.

Returns: true in case of success.

◆ WriteInt64()

bool GDALAttribute::WriteInt64 ( int64_t nVal )

Write an attribute from an int64_t value.

Type conversion will be performed if needed. If the attribute contains multiple values, only the first one will be updated.

This is the same as the C function GDALAttributeWriteInt().

Parameters

nVal Value.

Returns: true in case of success.

The documentation for this class was generated from the following files:

gdal_priv.h
gdalmultidim.cpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ FuncProcessPerChunkType

Member Function Documentation

◆ GetBlockSize()

◆ GetDataType()

◆ GetDimensionCount()

◆ GetDimensions()

◆ GetDimensionsSize()

◆ GetFullName()

◆ GetName()

◆ GetProcessingChunkSize()

◆ GetTotalElementsCount()

◆ ProcessPerChunk()

◆ Read()

◆ ReadAsDouble()

◆ ReadAsDoubleArray()

◆ ReadAsInt()

◆ ReadAsInt64()

◆ ReadAsInt64Array()

◆ ReadAsIntArray()

◆ ReadAsRaw()

◆ ReadAsString()

◆ ReadAsStringArray()

◆ Rename()

◆ Write() [1/9]

◆ Write() [2/9]

◆ Write() [3/9]

◆ Write() [4/9]

◆ Write() [5/9]

◆ Write() [6/9]

◆ Write() [7/9]

◆ Write() [8/9]

◆ Write() [9/9]

◆ WriteInt()

◆ WriteInt64()