GDAL
Public Member Functions | List of all members
GDALAttribute Class Reference

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:
GDALAbstractMDArray

Public Member Functions

std::vector< GUInt64GetDimensionsSize () 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...
 
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< 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 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 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...
 
- Public Member Functions inherited from GDALAbstractMDArray
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 GDALExtendedDataTypeGetDataType () const =0
 Return the data type of an attribute/array. More...
 
virtual std::vector< GUInt64GetBlockSize () 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 oerations, 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...
 
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...
 

Additional Inherited Members

- Public Types inherited from GDALAbstractMDArray
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...
 

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 Function Documentation

◆ 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().

◆ 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 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 be converted to integer.

This is the same as the C function GDALAttributeReadAsInt()

Returns
a integer, or INT_MIN in case of error.

◆ 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()

◆ Write() [1/6]

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
pszValuePointer to a string.
Returns
true in case of success.

◆ Write() [2/6]

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
valsArray of double.
nValsShould be equal to GetTotalElementsCount().
Returns
true in case of success.

◆ Write() [3/6]

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
arrayStartIdxValues 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.
countValues representing the number of values to write in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStepSpacing 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.
bufferStrideSpacing 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.
bufferDataTypeData type of values in pSrcBuffer.
pSrcBufferUser 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[].
pSrcBufferAllocStartOptional 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.
nSrcBufferAllocSizeOptional 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/6]

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
pabyValueBuffer of nLen bytes.
nLenSize of pabyValue in bytes. Should be equal to GetTotalElementsCount() * GetDataType().GetSize()
Returns
true in case of success.

◆ Write() [5/6]

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
valsArray of strings.
Returns
true in case of success.

◆ Write() [6/6]

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
dfValValue.
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
nValValue.
Returns
true in case of success.

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