# GDALAttribute C++ API

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

    Return

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

    This is the same as the C function GDALAttributeReadAsInt()

    Return

      a integer, or INT_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 be converted to double.

    This is the same as the C function GDALAttributeReadAsInt()

    Return

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

    Return

      true in case of success.

    Parameters

      - `pabyValue`: Buffer of nLen bytes.

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

  bool `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().

    Return

      true in case of success.

    Parameters

      - `pszValue`: Pointer to a string.

  bool `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().

    Return

      true in case of success.

    Parameters

      - `nVal`: Value.

  bool `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().

    Return

      true in case of success.

    Parameters

      - `dfVal`: Value.

  bool `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().

    Return

      true in case of success.

    Parameters

      - `vals`: Array of strings.

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

    Return

      true in case of success.

    Parameters

      - `vals`: Array of double.

      - `nVals`: Should be equal to GetTotalElementsCount().

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

  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.

    Note

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

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

    Return

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

    Parameters

      - `osName`: Attribute name

  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.

    Note

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

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

    Return

      the attributes.

    Parameters

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

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

    Return

      the new attribute, or nullptr if case of error

    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.