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

Class modeling a named container of GDALAttribute, GDALMDArray or other GDALGroup. More...

#include <gdal_priv.h>

Inheritance diagram for GDALGroup:
GDALIHasAttribute

Public Member Functions

const std::string & GetName () const
 Return the name of the group. More...
 
const std::string & GetFullName () const
 Return the full name of the group. More...
 
virtual std::vector< std::string > GetMDArrayNames (CSLConstList papszOptions=nullptr) const
 Return the list of multidimensional array names contained in this group. More...
 
virtual std::shared_ptr< GDALMDArrayOpenMDArray (const std::string &osName, CSLConstList papszOptions=nullptr) const
 Open and return a multidimensional array. More...
 
virtual std::vector< std::string > GetGroupNames (CSLConstList papszOptions=nullptr) const
 Return the list of sub-groups contained in this group. More...
 
virtual std::shared_ptr< GDALGroupOpenGroup (const std::string &osName, CSLConstList papszOptions=nullptr) const
 Open and return a sub-group. More...
 
virtual std::vector< std::shared_ptr< GDALDimension > > GetDimensions (CSLConstList papszOptions=nullptr) const
 Return the list of dimensions contained in this group and used by its arrays. More...
 
virtual std::shared_ptr< GDALGroupCreateGroup (const std::string &osName, CSLConstList papszOptions=nullptr)
 Create a sub-group within a group. More...
 
virtual std::shared_ptr< GDALDimensionCreateDimension (const std::string &osName, const std::string &osType, const std::string &osDirection, GUInt64 nSize, CSLConstList papszOptions=nullptr)
 Create a dimension within a group. More...
 
virtual std::shared_ptr< GDALMDArrayCreateMDArray (const std::string &osName, const std::vector< std::shared_ptr< GDALDimension >> &aoDimensions, const GDALExtendedDataType &oDataType, CSLConstList papszOptions=nullptr)
 Create a multidimensional array within a group. More...
 
GUInt64 GetTotalCopyCost () const
 Return a total "cost" to copy the group. More...
 
virtual bool CopyFrom (const std::shared_ptr< GDALGroup > &poDstRootGroup, GDALDataset *poSrcDS, const std::shared_ptr< GDALGroup > &poSrcGroup, bool bStrict, GUInt64 &nCurCost, const GUInt64 nTotalCost, GDALProgressFunc pfnProgress, void *pProgressData)
 Copy the content of a group into a new (generally empty) group. More...
 
virtual CSLConstList GetStructuralInfo () const
 Return structural information on the group. More...
 
std::shared_ptr< GDALMDArrayOpenMDArrayFromFullname (const std::string &osFullName, CSLConstList papszOptions=nullptr) const
 Get an array from its fully qualified name.
 
std::shared_ptr< GDALMDArrayResolveMDArray (const std::string &osName, const std::string &osStartingPath, CSLConstList papszOptions=nullptr) const
 Locate an array in a group and its subgroups by name. More...
 
std::shared_ptr< GDALGroupOpenGroupFromFullname (const std::string &osFullName, CSLConstList papszOptions=nullptr) const
 Get a group from its fully qualified name. More...
 
std::shared_ptr< GDALDimensionOpenDimensionFromFullname (const std::string &osFullName) const
 Get a dimension from its fully qualified name.
 
- Public Member Functions inherited from GDALIHasAttribute
virtual std::shared_ptr< GDALAttributeGetAttribute (const std::string &osName) const
 Return an attribute by its name. More...
 
virtual std::vector< std::shared_ptr< GDALAttribute > > GetAttributes (CSLConstList papszOptions=nullptr) const
 Return the list of attributes contained in a GDALMDArray or GDALGroup. More...
 
virtual std::shared_ptr< GDALAttributeCreateAttribute (const std::string &osName, const std::vector< GUInt64 > &anDimensions, const GDALExtendedDataType &oDataType, CSLConstList papszOptions=nullptr)
 Create an attribute within a GDALMDArray or GDALGroup. More...
 

Additional Inherited Members

- Protected Member Functions inherited from GDALIHasAttribute
std::shared_ptr< GDALAttributeGetAttributeFromAttributes (const std::string &osName) const
 Possible fallback implementation for GetAttribute() using GetAttributes().
 

Detailed Description

Class modeling a named container of GDALAttribute, GDALMDArray or other GDALGroup.

Hence GDALGroup can describe a hierarchy of objects.

This is based on the HDF5 group concept

Since
GDAL 3.1

Member Function Documentation

◆ CopyFrom()

bool GDALGroup::CopyFrom ( const std::shared_ptr< GDALGroup > &  poDstRootGroup,
GDALDataset poSrcDS,
const std::shared_ptr< GDALGroup > &  poSrcGroup,
bool  bStrict,
GUInt64 nCurCost,
const GUInt64  nTotalCost,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
)
virtual

Copy the content of a group into a new (generally empty) group.

Parameters
poDstRootGroupDestination root group. Must NOT be nullptr.
poSrcDSSource dataset. Migt be nullptr (but for correct behavior of some output drivers this is not recommended)
poSrcGroupSource group. Must NOT be nullptr.
bStrictWhether to enable stict mode. In strict mode, any error will stop the copy. In relaxed mode, the copy will be attempted to be pursued.
nCurCostShould be provided as a variable initially set to 0.
nTotalCostTotal cost from GetTotalCopyCost().
pfnProgressProgress callback, or nullptr.
pProgressDataProgress user data, or nulptr.
Returns
true in case of success (or partial success if bStrict == false).

◆ CreateDimension()

std::shared_ptr< GDALDimension > GDALGroup::CreateDimension ( const std::string &  osName,
const std::string &  osType,
const std::string &  osDirection,
GUInt64  nSize,
CSLConstList  papszOptions = nullptr 
)
virtual

Create a dimension within a group.

Note
Driver implementation: drivers supporting CreateDimension() should implement this method, but do not have necessarily to implement GDALGroup::GetDimensions().

Drivers known to implement it: MEM, netCDF

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

Parameters
osNameDimension name.
osTypeDimension type (might be empty, and ignored by drivers)
osDirectionDimension direction (might be empty, and ignored by drivers)
nSizeNumber of values indexed by this dimension. Should be > 0.
papszOptionsDriver specific options determining how the dimension should be created.
Returns
the new dimension, or nullptr if case of error

◆ CreateGroup()

std::shared_ptr< GDALGroup > GDALGroup::CreateGroup ( const std::string &  osName,
CSLConstList  papszOptions = nullptr 
)
virtual

Create a sub-group within a group.

Optionally implemented by drivers.

Drivers known to implement it: MEM, netCDF

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

Parameters
osNameSub-group name.
papszOptionsDriver specific options determining how the sub-group should be created.
Returns
the new sub-group, or nullptr in case of error.

◆ CreateMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::CreateMDArray ( const std::string &  osName,
const std::vector< std::shared_ptr< GDALDimension >> &  aoDimensions,
const GDALExtendedDataType oDataType,
CSLConstList  papszOptions = nullptr 
)
virtual

Create a multidimensional array within a group.

It is recommended that the GDALDimension objects passed in aoDimensions belong to this group, either by retrieving them with GetDimensions() or creating a new one with CreateDimension().

Optionally implemented.

Drivers known to implement it: MEM, netCDF

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

Note
Driver implementation: drivers should take into account the possibility that GDALDimension object passed in aoDimensions might belong to a different group / dataset / driver and act accordingly.
Parameters
osNameArray name.
aoDimensionsList of dimensions, ordered from the slowest varying dimension first to the fastest varying dimension last. Might be empty for a scalar array (if supported by driver)
oDataTypeArray data type.
papszOptionsDriver specific options determining how the array should be created.
Returns
the new array, or nullptr if case of error

◆ GetDimensions()

std::vector< std::shared_ptr< GDALDimension > > GDALGroup::GetDimensions ( CSLConstList  papszOptions = nullptr) const
virtual

Return the list of dimensions contained in this group and used by its arrays.

This is for dimensions that can potentially be used by several arrays. Not all drivers might implement this. To retrieve the dimensions used by a specific array, use GDALMDArray::GetDimensions().

Drivers known to implement it: MEM, netCDF

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

Parameters
papszOptionsDriver specific options determining how groups should be retrieved. Pass nullptr for default behavior.
Returns
the dimensions.

◆ GetFullName()

const std::string& GDALGroup::GetFullName ( ) const
inline

Return the full name of the group.

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

◆ GetGroupNames()

std::vector< std::string > GDALGroup::GetGroupNames ( CSLConstList  papszOptions = nullptr) const
virtual

Return the list of sub-groups contained in this group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters
papszOptionsDriver specific options determining how groups should be retrieved. Pass nullptr for default behavior.
Returns
the group names.

◆ GetMDArrayNames()

std::vector< std::string > GDALGroup::GetMDArrayNames ( CSLConstList  papszOptions = nullptr) const
virtual

Return the list of multidimensional array names contained in this group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters
papszOptionsDriver specific options determining how arrays should be retrieved. Pass nullptr for default behavior.
Returns
the array names.

◆ GetName()

const std::string& GDALGroup::GetName ( ) const
inline

Return the name of the group.

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

◆ GetStructuralInfo()

CSLConstList GDALGroup::GetStructuralInfo ( ) const
virtual

Return structural information on the group.

This may be the compression, etc..

The return value should not be freed and is valid until GDALGroup is released or this function called again.

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

◆ GetTotalCopyCost()

GUInt64 GDALGroup::GetTotalCopyCost ( ) const

Return a total "cost" to copy the group.

Used as a parameter for CopFrom()

◆ OpenGroup()

std::shared_ptr< GDALGroup > GDALGroup::OpenGroup ( const std::string &  osName,
CSLConstList  papszOptions = nullptr 
) const
virtual

Open and return a sub-group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters
osNameSub-group name.
papszOptionsDriver specific options determining how the sub-group should be opened. Pass nullptr for default behavior.
Returns
the group, or nullptr.

◆ OpenGroupFromFullname()

std::shared_ptr< GDALGroup > GDALGroup::OpenGroupFromFullname ( const std::string &  osFullName,
CSLConstList  papszOptions = nullptr 
) const

Get a group from its fully qualified name.

Since
GDAL 3.2

◆ OpenMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::OpenMDArray ( const std::string &  osName,
CSLConstList  papszOptions = nullptr 
) const
virtual

Open and return a multidimensional array.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters
osNameArray name.
papszOptionsDriver specific options determining how the array should be opened. Pass nullptr for default behavior.
Returns
the array, or nullptr.

◆ ResolveMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::ResolveMDArray ( const std::string &  osName,
const std::string &  osStartingPath,
CSLConstList  papszOptions = nullptr 
) const

Locate an array in a group and its subgroups by name.

If osName is a fully qualified name, then OpenMDArrayFromFullname() is first used Otherwise the search will start from the group identified by osStartingPath, and an array whose name is osName will be looked for in this group (if osStartingPath is empty or "/", then the current group is used). If there is no match, then a recursive descendent search will be made in its subgroups. If there is no match in the subgroups, then the parent (if existing) of the group pointed by osStartingPath will be used as the new starting point for the search.

Parameters
osNamename, qualified or not
osStartingPathfully qualified name of the (sub-)group from which the search should be started. If this is a non-empty string, the group on which this method is called should nominally be the root group (otherwise the path will be interpretated as from the current group)
papszOptionsoptions to pass to OpenMDArray()
Since
GDAL 3.2

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