# GDALAttribute C++ API

## Include file

`gdal_priv.h`

## GDALAttribute class

class GDALAttribute : public virtual GDALAbstractMDArray

  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

  Subclassed by GDALMDArrayFromRasterBand::MDIAsAttribute

  Public Functions

  std::vector<GUInt64> 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().

  GDALRawResult ReadAsRaw() const

    Return the raw value of an attribute.

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

  const char *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.

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

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

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

  CPLStringList ReadAsStringArray() const

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

    This is the same as the C function GDALAttributeReadAsStringArray()

  std::vector<int> ReadAsIntArray() const

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

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

  std::vector<int64_t> ReadAsInt64Array() const

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

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

  std::vector<double> ReadAsDoubleArray() const

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

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

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

  bool Write(const char*)

    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.

  bool WriteInt(int)

    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.

  bool WriteInt64(int64_t)

    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.

  bool Write(double)

    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.

  bool Write(CSLConstList)

    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.

  bool Write(const int*, size_t)

    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.

  bool Write(const int64_t*, size_t)

    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.

  bool Write(const double*, size_t)

    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.

  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.

    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.

## GDALIHasAttribute interface

class GDALIHasAttribute

  Interface used to get a single GDALAttribute or a set of GDALAttribute.

  Since

    GDAL 3.1

  Subclassed by GDALGroup, GDALMDArray

  Public Functions

  virtual std::shared_ptr<GDALAttribute> GetAttribute(const std::string &osName) const

    Return an attribute by its name.

    If the attribute does not exist, nullptr should be silently returned.

    Drivers known to implement it for groups and arrays: MEM, netCDF.

    This is the same as the C function GDALGroupGetAttribute() or GDALMDArrayGetAttribute().

    Note

    Driver implementation: this method will fallback to GetAttributeFromAttributes() is not explicitly implemented

    Parameters:

      osName -- Attribute name

    Returns:

      the attribute, or nullptr if it does not exist or an error occurred.

  virtual std::vector<std::shared_ptr<GDALAttribute>> GetAttributes(CSLConstList papszOptions = nullptr) const

    Return the list of attributes contained in a GDALMDArray or GDALGroup.

    If the attribute does not exist, nullptr should be silently returned.

    Drivers known to implement it for groups and arrays: MEM, netCDF.

    This is the same as the C function GDALGroupGetAttributes() or GDALMDArrayGetAttributes().

    Note

    Driver implementation: optionally implemented. If implemented, GetAttribute() should also be implemented.

    Parameters:

      papszOptions -- Driver specific options determining how attributes should be retrieved. Pass nullptr for default behavior.

    Returns:

      the attributes.

  virtual std::shared_ptr<GDALAttribute> CreateAttribute(const std::string &osName, const std::vector<GUInt64> &anDimensions, const GDALExtendedDataType &oDataType, CSLConstList papszOptions = nullptr)

    Create an attribute within a GDALMDArray or GDALGroup.

    The attribute might not be "physically" created until a value is written into it.

    Optionally implemented.

    Drivers known to implement it: MEM, netCDF

    This is the same as the C function GDALGroupCreateAttribute() or GDALMDArrayCreateAttribute()

    Parameters:

      - osName -- Attribute name.

      - anDimensions -- List of dimension sizes, ordered from the slowest varying dimension first to the fastest varying dimension last. Empty for a scalar attribute (common case)

      - oDataType -- Attribute data type.

      - papszOptions -- Driver specific options determining how the attribute. should be created.

    Returns:

      the new attribute, or nullptr if case of error

  virtual bool DeleteAttribute(const std::string &osName, CSLConstList papszOptions = nullptr)

    Delete an attribute from a GDALMDArray or GDALGroup.

    Optionally implemented.

    After this call, if a previously obtained instance of the deleted object is still alive, no method other than for freeing it should be invoked.

    Drivers known to implement it: MEM, netCDF

    This is the same as the C function GDALGroupDeleteAttribute() or GDALMDArrayDeleteAttribute()

    Since

      GDAL 3.8

    Parameters:

      - osName -- Attribute name.

      - papszOptions -- Driver specific options determining how the attribute. should be deleted.

    Returns:

      true in case of success