GDAL

Public Types | Public Member Functions | List of all members
GDALAbstractMDArray Class Referenceabstract

Abstract class, implemented by GDALAttribute and GDALMDArray. More...

`#include <gdal_priv.h>`

Inheritance diagram for GDALAbstractMDArray:

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

## Public Member Functions
const std::string & | GetName () const
| Return the name of an array or attribute.
const std::string & | GetFullName () const
| Return the name of an array or attribute.
GUInt64 | GetTotalElementsCount () const
| Return the total number of values in the array.
virtual size_t | GetDimensionCount () const
| Return the number of dimensions.
virtual const std::vector< std::shared_ptr< GDALDimension > > & | GetDimensions () const =0
| Return the dimensions of an attribute/array.
virtual const GDALExtendedDataType & | GetDataType () const =0
| Return the data type of an attribute/array.
virtual std::vector< GUInt64 > | GetBlockSize () const
| Return the "natural" block size of the array along all dimensions.
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.
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.
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.
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.
virtual bool | Rename (const std::string &osNewName)
| Rename the attribute/array.

## Detailed Description

Abstract class, implemented by GDALAttribute and GDALMDArray.

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)

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
| virtual

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 virtual

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
| virtual

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 virtual

Return the dimensions of an attribute/array.

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

## ◆ GetFullName()

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

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
| inline

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
| virtual

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

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
| ) |  |
| virtual

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
| virtual

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 validity 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 validity 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.

## ◆ Rename()

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

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

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`
| ) |  |

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 validity 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 validity 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.

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

- gdal_priv.h
- gdalmultidim.cpp