AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
Public Member Functions | Friends | List of all members
axom::sidre::Group Class Reference

Group holds a collection of Views and (child) Groups. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.5.0/src/axom/sidre/core/Group.hpp>

Public Member Functions

void copyToConduitNode (Node &n) const
 Copy description of Group hierarchy rooted at this Group to given Conduit node. More...
 
bool createNativeLayout (Node &n, const Attribute *attr=nullptr) const
 Copy data Group native layout to given Conduit node. More...
 
bool createExternalLayout (Node &n, const Attribute *attr=nullptr) const
 Copy data Group external layout to given Conduit node. More...
 
bool isEquivalentTo (const Group *other, bool checkName=true) const
 Return true if this Group is equivalent to given Group; else false. More...
 
bool isUsingMap () const
 Return true if this Group holds items in map format. More...
 
bool isUsingList () const
 Return true if this Group holds items in list format. More...
 
bool rename (const std::string &new_name)
 Change the name of this Group. More...
 
bool importConduitTree (const conduit::Node &node, bool preserve_contents=false)
 Import data from a conduit Node into a Group. More...
 
bool importConduitTreeExternal (conduit::Node &node, bool preserve_contents=false)
 Import data from a conduit Node into a Group without copying arrays. More...
 
Basic query and accessor methods.
char getPathDelimiter () const
 Return the path delimiter. More...
 
IndexType getIndex () const
 Return index of Group object within parent Group. More...
 
const std::string & getName () const
 Return const reference to name of Group object. More...
 
std::string getPath () const
 Return path of Group object, not including its name. More...
 
std::string getPathName () const
 Return full path of Group object, including its name. More...
 
Group * getParent ()
 Return pointer to non-const parent Group of a Group. More...
 
const Group * getParent () const
 Return pointer to const parent Group of a Group. More...
 
IndexType getNumGroups () const
 Return number of child Groups in a Group object. More...
 
IndexType getNumViews () const
 Return number of Views owned by a Group object. More...
 
DataStore * getDataStore ()
 Return pointer to non-const DataStore object that owns this object. More...
 
const DataStore * getDataStore () const
 Return pointer to const DataStore object that owns this object. More...
 
bool isRoot () const
 Return true if this Group is the DataStore's root Group. More...
 
View query methods.
bool hasView (const std::string &path) const
 Return true if Group includes a descendant View with given name or path; else false. More...
 
bool hasChildView (const std::string &name) const
 Return true if this Group owns a View with given name (not path); else false. More...
 
bool hasView (IndexType idx) const
 Return true if this Group owns a View with given index; else false. More...
 
IndexType getViewIndex (const std::string &name) const
 Return index of View with given name owned by this Group object. More...
 
const std::string & getViewName (IndexType idx) const
 Return name of View with given index owned by Group object. More...
 
View access methods.
View * getView (const std::string &path)
 Return pointer to non-const View with given name or path. More...
 
const View * getView (const std::string &path) const
 Return pointer to const View with given name or path. More...
 
View * getView (IndexType idx)
 Return pointer to non-const View with given index. More...
 
const View * getView (IndexType idx) const
 Return pointer to const View with given index. More...
 
View iteration methods.

Using these methods, a code can get the first View index and each succeeding index. This allows View iteration using the same constructs in C++, C, and Fortran. Example: 

 sidre::IndexType idx = grp->getFirstValidViewIndex();
 while( sidre::indexIsValid(idx) )
 {
     View* view = grp->getView(idx);

     /// code here using view

     idx = grp -> getNextValidViewIndex(idx);
 }
IndexType getFirstValidViewIndex () const
 Return first valid View index in Group object (i.e., smallest index over all Views). More...
 
IndexType getNextValidViewIndex (IndexType idx) const
 Return next valid View index in Group object after given index (i.e., smallest index over all View indices larger than given one). More...
 
Methods to create a View that has no associated data.
Attention
These methods do not allocate data or associate a View with data. Thus, to do anything useful with a View created by one of these methods, the View should be allocated, attached to a Buffer or attached to externally-owned data.

Each of these methods is a no-op if the given View name is an empty string or the Group already has a View with given name or path.

Additional conditions under which a method can be a no-op are described for each method.

View * createView (const std::string &path)
 Create an undescribed (i.e., empty) View object with given name or path in this Group. More...
 
View * createView (const std::string &path, TypeID type, IndexType num_elems)
 Create View object with given name or path in this Group that has a data description with data type and number of elements. More...
 
View * createView (const std::string &path, TypeID type, int ndims, const IndexType *shape)
 Create View object with given name or path in this Group that has a data description with data type and shape. More...
 
View * createView (const std::string &path, const DataType &dtype)
 Create View object with given name or path in this Group that is described by a Conduit DataType object. More...
 
Methods to create a View with a Buffer attached.
Attention
The Buffer passed to each of these methods may or may not be allocated. Thus, to do anything useful with a View created by one of these methods, the Buffer must be allocated and it must be compatible with the View data description.

Each of these methods is a no-op if Group already has a View or child Group with the given name or path.

If this Group was created to hold items in list format, the path can be an empty string. Otherwise an empty string for the path will result in a no-op.

Also, calling one of these methods with a null Buffer pointer is similar to creating a View with no data association.

Additional conditions under which a method can be a no-op are described for each method.

View * createView (const std::string &path, Buffer *buff)
 Create an undescribed View object with given name or path in this Group and attach given Buffer to it. More...
 
View * createView (const std::string &path, TypeID type, IndexType num_elems, Buffer *buff)
 Create View object with given name or path in this Group that has a data description with data type and number of elements and attach given Buffer to it. More...
 
View * createView (const std::string &path, TypeID type, int ndims, const IndexType *shape, Buffer *buff)
 Create View object with given name or path in this Group that has a data description with data type and shape and attach given Buffer to it. More...
 
View * createView (const std::string &path, const DataType &dtype, Buffer *buff)
 Create View object with given name or path in this Group that is described by a Conduit DataType object and attach given Buffer to it. More...
 
Methods to create a View with externally-owned data attached.
Attention
To do anything useful with a View created by one of these methods, the external data must be allocated and compatible with the View description.

Each of these methods is a no-op if the given View name is an empty string or the Group already has a View with given name or path.

Additional conditions under which a method can be a no-op are described for each method.

View * createView (const std::string &path, void *external_ptr)
 Create View object with given name with given name or path in this Group and attach external data ptr to it. More...
 
View * createView (const std::string &path, TypeID type, IndexType num_elems, void *external_ptr)
 Create View object with given name or path in this Group that has a data description with data type and number of elements and attach externally-owned data to it. More...
 
View * createView (const std::string &path, TypeID type, int ndims, const IndexType *shape, void *external_ptr)
 Create View object with given name or path in this Group that has a data description with data type and shape and attach externally-owned data to it. More...
 
View * createView (const std::string &path, const DataType &dtype, void *external_ptr)
 Create View object with given name or path in this Group that is described by a Conduit DataType object and attach externally-owned data to it. More...
 
Methods to create a View and allocate data for it.

Each of these methods is a no-op if the given View name is an empty string or the Group already has a View with given name or path.

Additional conditions under which a method can be a no-op are described for each method.

View * createViewAndAllocate (const std::string &path, TypeID type, IndexType num_elems, int allocID=INVALID_ALLOCATOR_ID)
 Create View object with given name or path in this Group that has a data description with data type and number of elements and allocate data for it. More...
 
View * createViewAndAllocate (const std::string &path, TypeID type, int ndims, const IndexType *shape, int allocID=INVALID_ALLOCATOR_ID)
 Create View object with given name or path in this Group that has a data description with data type and shape and allocate data for it. More...
 
View * createViewAndAllocate (const std::string &path, const DataType &dtype, int allocID=INVALID_ALLOCATOR_ID)
 Create View object with given name or path in this Group that is described by a Conduit DataType object and allocate data for it. More...
 
template<typename ScalarType >
View * createViewScalar (const std::string &path, ScalarType value)
 Create View object with given name or path in this Group set its data to given scalar value. More...
 
View * createViewString (const std::string &path, const std::string &value)
 Create View object with given name or path in this Group set its data to given string. More...
 
View destruction methods.

Each of these methods is a no-op if the specified View does not exist.

void destroyView (const std::string &path)
 Destroy View with given name or path owned by this Group, but leave its data intect. More...
 
void destroyView (IndexType idx)
 Destroy View with given index owned by this Group, but leave its data intect. More...
 
void destroyViews ()
 Destroy all Views owned by this Group, but leave all their data intact. More...
 
void destroyViewAndData (const std::string &path)
 Destroy View with given name or path owned by this Group and deallocate its data if it's the only View associated with that data. More...
 
void destroyViewAndData (IndexType idx)
 Destroy View with given index owned by this Group and deallocate its data if it's the only View associated with that data. More...
 
void destroyViewsAndData ()
 Destroy all Views owned by this Group and deallocate data for each View when it's the only View associated with that data. More...
 
View move and copy methods.
View * moveView (View *view)
 Remove given View object from its owning Group and move it to this Group. More...
 
View * copyView (View *view)
 Create a copy of given View object and add it to this Group. More...
 
Child Group query methods.
bool hasGroup (const std::string &path) const
 Return true if this Group has a descendant Group with given name or path; else false. More...
 
bool hasChildGroup (const std::string &name) const
 Return true if this Group has a child Group with given name; else false. More...
 
bool hasGroup (IndexType idx) const
 Return true if Group has an immediate child Group with given index; else false. More...
 
IndexType getGroupIndex (const std::string &name) const
 Return the index of immediate child Group with given name. More...
 
const std::string & getGroupName (IndexType idx) const
 Return the name of immediate child Group with given index. More...
 
Group access and iteration methods.
Group * getGroup (const std::string &path)
 Return pointer to non-const child Group with given name or path. More...
 
Group const * getGroup (const std::string &path) const
 Return pointer to const child Group with given name or path. More...
 
Group * getGroup (IndexType idx)
 Return pointer to non-const immediate child Group with given index. More...
 
const Group * getGroup (IndexType idx) const
 Return pointer to const immediate child Group with given index. More...
 
Group iteration methods.

Using these methods, a code can get the first Group index and each succeeding index. This allows Group iteration using the same constructs in C++, C, and Fortran. Example: for (sidre::IndexType idx = grp->getFirstValidGroupIndex(); sidre::indexIsValid(idx); idx = grp->getNextValidGroupIndex(idx)) { Group * group = grp->getGroup(idx);

/// code here using group }

IndexType getFirstValidGroupIndex () const
 Return first valid child Group index (i.e., smallest index over all child Groups). More...
 
IndexType getNextValidGroupIndex (IndexType idx) const
 Return next valid child Group index after given index (i.e., smallest index over all child Group indices larger than given one). More...
 
Child Group creation and destruction methods.
Group * createGroup (const std::string &path, bool is_list=false)
 Create a child Group within this Group with given name or path. More...
 
Group * createUnnamedGroup (bool is_list=false)
 
void destroyGroup (const std::string &path)
 Destroy child Group in this Group with given name or path. More...
 
void destroyGroup (IndexType idx)
 Destroy child Group within this Group with given index. More...
 
void destroyGroups ()
 Destroy all child Groups in this Group. More...
 
Group move and copy methods.
Group * moveGroup (Group *group)
 Remove given Group object from its parent Group and make it a child of this Group. More...
 
Group * copyGroup (Group *group)
 Create a copy of Group hierarchy rooted at given Group and make it a child of this Group. More...
 
Group print methods.
void print () const
 Print JSON description of data Group to stdout. More...
 
void print (std::ostream &os) const
 Print JSON description of data Group to an ostream. More...
 
void printTree (const int nlevels, std::ostream &os) const
 Print given number of levels of Group sub-tree starting at this Group object to an output stream. More...
 
Group I/O methods

These methods save and load Group trees to and from files. This includes the views and buffers used in by groups in the tree. We provide several "protocol" options:

protocols: sidre_hdf5 (default when Axom is configured with hdf5) sidre_conduit_json (default otherwise) sidre_json

conduit_hdf5 conduit_bin conduit_json json

Note
The sidre_hdf5 and conduit_hdf5 protocols are only available when Axom is configured with hdf5.

There are two overloaded versions for each of save, load, and loadExternalData. The first of each takes a file path and is intended for use in a serial context and can be called directly using any of the supported protocols. The second takes an hdf5 handle that has previously been created by the calling code. These mainly exist to handle parallel I/O calls from the SPIO component. They can only take the sidre_hdf5 or conduit_hdf5 protocols.

Note
The hdf5 overloads are only available when Axom is configured with hdf5.
void save (const std::string &path, const std::string &protocol="sidre_conduit_json", const Attribute *attr=nullptr) const
 Save the Group to a file. More...
 
void load (const std::string &path, const std::string &protocol="sidre_conduit_json", bool preserve_contents=false)
 Load a Group hierarchy from a file into this Group. More...
 
void load (const std::string &path, const std::string &protocol, bool preserve_contents, std::string &name_from_file)
 Load a Group hierarchy from a file into this Group, reporting the Group name stored in the file. More...
 
Group * createGroupAndLoad (std::string &group_name, const std::string &path, const std::string &protocol, bool &load_success)
 Create a child Group and load a Group hierarchy from file into the new Group. More...
 
void loadExternalData (const std::string &path)
 Load data into the Group's external views from a file. More...
 

Friends

class DataStore
 
class View
 

Detailed Description

Group holds a collection of Views and (child) Groups.

The Group class has the following properties:

  • Groups can be organized into a (tree) hierarchy by creating child Groups from the root Group owned by a DataStore object.
  • A Group object can only be created by another Group; the Group ctor is not visible externally. A Group is owned by the Group that creates it (its parent) and becomes a (direct) child Group of the parent. Groups in the subtree rooted at an ancestor Group are that Group's descendants.
  • A Group object has a unique name (string) within its parent Group.
  • A Group object maintains a pointer to its parent Group.
  • A Group object can be moved or copied to another Group.
  • Group objects can create View objects within them. The Group that creates a View owns it.
  • A View object has a unique name (string) within the Group that owns it.
  • A View object can be moved or copied to another Group.

Note that Views and child Groups within a Group can be accessed by name or index.

Note that certain methods for querying, creating, retrieving, and deleting Groups and Views take a string with path syntax, while others take the name of a direct child of the current Group. Methods that require the name of a direct child are marked with "Child", for example hasChildView() and hasChildGroup(). When a path string is passed to a method that accepts path syntax, the last item in the path indicates the item to be created, accessed, etc. For example, 

 View* view = group->createView("foo/bar/baz");

is equivalent to 

 View* view =
   group->createGroup("foo")->createGroup("bar")->createView("baz");

In particular, intermediate Groups "foo" and "bar" will be created in this case if they don't already exist.

Methods that access Views or Groups by index work with the direct children of the current Group because an index has no meaning outside of the indexed group. None of these methods is marked with "Child".

A Group can optionally be created to hold items in a "list format". In this format, any number of child Group or View items can be created with empty strings for their names, and none of the methods that access child items by name or path will return a valid pointer.

Attention
when Views or Groups are created, destroyed, copied, or moved, indices of other Views and Groups in associated Group objects may become invalid. This is analogous to iterator invalidation for STL containers when the container contents change.

Member Function Documentation

◆ getPathDelimiter()

char axom::sidre::Group::getPathDelimiter ( ) const
inline

Return the path delimiter.

Referenced by getPathName().

◆ getIndex()

IndexType axom::sidre::Group::getIndex ( ) const
inline

Return index of Group object within parent Group.

◆ getName()

const std::string& axom::sidre::Group::getName ( ) const
inline

Return const reference to name of Group object.

See also
getPath(), getPathName()

References getPath().

Referenced by getPathName().

◆ getPath()

std::string axom::sidre::Group::getPath ( ) const

Return path of Group object, not including its name.

See also
getName(), getPathName()

Referenced by getName(), and getPathName().

◆ getPathName()

std::string axom::sidre::Group::getPathName ( ) const
inline

Return full path of Group object, including its name.

If a DataStore contains a Group tree structure a/b/c/d/e, the following results are expected:

Method Call Result
e->getName() e
e->getPath() a/b/c/d
e->getPathName() a/b/c/d/e
See also
getName(), getPath(), View::getPathName()

References getName(), getPath(), and getPathDelimiter().

◆ getParent() [1/2]

Group* axom::sidre::Group::getParent ( )
inline

Return pointer to non-const parent Group of a Group.

Note that if this method is called on the root Group in a DataStore, a pointer to itself is returned. This allows root->getParent()->getParent() to always work similar to how the filesystem's cd /; cd ../.. works.

◆ getParent() [2/2]

const Group* axom::sidre::Group::getParent ( ) const
inline

Return pointer to const parent Group of a Group.

Note that if this method is called on the root Group in a DataStore, a pointer to itself is returned. This allows root->getParent()->getParent() to always work similar to how the filesystem's cd /; cd ../.. works.

References getNumGroups(), and getNumViews().

◆ getNumGroups()

IndexType axom::sidre::Group::getNumGroups ( ) const

Return number of child Groups in a Group object.

Referenced by getParent().

◆ getNumViews()

IndexType axom::sidre::Group::getNumViews ( ) const

Return number of Views owned by a Group object.

Referenced by getParent().

◆ getDataStore() [1/2]

DataStore* axom::sidre::Group::getDataStore ( )
inline

Return pointer to non-const DataStore object that owns this object.

◆ getDataStore() [2/2]

const DataStore* axom::sidre::Group::getDataStore ( ) const
inline

Return pointer to const DataStore object that owns this object.

◆ isRoot()

bool axom::sidre::Group::isRoot ( ) const
inline

Return true if this Group is the DataStore's root Group.

References createView(), createViewAndAllocate(), axom::getDefaultAllocatorID(), getFirstValidViewIndex(), getNextValidViewIndex(), getView(), getViewIndex(), getViewName(), hasChildView(), hasView(), axom::INVALID_ALLOCATOR_ID, and axom::setDefaultAllocator().

◆ hasView() [1/2]

bool axom::sidre::Group::hasView ( const std::string &  path) const

Return true if Group includes a descendant View with given name or path; else false.

Referenced by isRoot().

◆ hasChildView()

bool axom::sidre::Group::hasChildView ( const std::string &  name) const

Return true if this Group owns a View with given name (not path); else false.

Referenced by isRoot().

◆ hasView() [2/2]

bool axom::sidre::Group::hasView ( IndexType  idx) const

Return true if this Group owns a View with given index; else false.

◆ getViewIndex()

IndexType axom::sidre::Group::getViewIndex ( const std::string &  name) const

Return index of View with given name owned by this Group object.

If no such View exists, return sidre::InvalidIndex;

Referenced by isRoot().

◆ getViewName()

const std::string& axom::sidre::Group::getViewName ( IndexType  idx) const

Return name of View with given index owned by Group object.

If no such View exists, return sidre::InvalidName.

Referenced by isRoot().

◆ getView() [1/4]

View* axom::sidre::Group::getView ( const std::string &  path)

Return pointer to non-const View with given name or path.

This method requires that all groups in the path exist if a path is given.

If no such View exists, nullptr is returned.

Referenced by axom::mint::ConnectivityArray< TYPE >::ConnectivityArray(), and isRoot().

◆ getView() [2/4]

const View* axom::sidre::Group::getView ( const std::string &  path) const

Return pointer to const View with given name or path.

This method requires that all Groups in the path exist if a path is given.

If no such View exists, nullptr is returned.

◆ getView() [3/4]

View* axom::sidre::Group::getView ( IndexType  idx)

Return pointer to non-const View with given index.

If no such View exists, nullptr is returned.

◆ getView() [4/4]

const View* axom::sidre::Group::getView ( IndexType  idx) const

Return pointer to const View with given index.

If no such View exists, nullptr is returned.

◆ getFirstValidViewIndex()

IndexType axom::sidre::Group::getFirstValidViewIndex ( ) const

Return first valid View index in Group object (i.e., smallest index over all Views).

sidre::InvalidIndex is returned if Group has no Views.

See also
sidre::IndexType
sidre::indexIsValid()

Referenced by isRoot().

◆ getNextValidViewIndex()

IndexType axom::sidre::Group::getNextValidViewIndex ( IndexType  idx) const

Return next valid View index in Group object after given index (i.e., smallest index over all View indices larger than given one).

sidre::InvalidIndex is returned if there is no valid index greater than given one.

See also
sidre::IndexType
sidre::indexIsValid()

Referenced by isRoot().

◆ createView() [1/12]

View* axom::sidre::Group::createView ( const std::string &  path)

Create an undescribed (i.e., empty) View object with given name or path in this Group.

If path is an empty string, an unnamed view can be created only if this Group was created to hold items in a list format. Otherwise an empty string will result in a nullptr being returned.

Returns
pointer to new View object or nullptr if one is not created.

Referenced by axom::mint::FieldData::createField(), createViewScalar(), and isRoot().

◆ createView() [2/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
IndexType  num_elems 
)

Create View object with given name or path in this Group that has a data description with data type and number of elements.

If given data type is undefined, or given number of elements is < 0, method is a no-op.

Returns
pointer to new View object or nullptr if one is not created.

◆ createView() [3/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
int  ndims,
const IndexType *  shape 
)

Create View object with given name or path in this Group that has a data description with data type and shape.

If given data type is undefined, or given number of dimensions is < 0, or given shape ptr is null, method is a no-op.

Returns
pointer to new View object or nullptr if one is not created.

◆ createView() [4/12]

View* axom::sidre::Group::createView ( const std::string &  path,
const DataType &  dtype 
)

Create View object with given name or path in this Group that is described by a Conduit DataType object.

Returns
pointer to new View object or nullptr if one is not created.

◆ createView() [5/12]

View* axom::sidre::Group::createView ( const std::string &  path,
Buffer *  buff 
)

Create an undescribed View object with given name or path in this Group and attach given Buffer to it.

Attention
The View cannot be used to access data in Buffer until it is described by calling a View::apply() method.

This method is equivalent to: group->createView(name)->attachBuffer(buff).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::attachBuffer()

◆ createView() [6/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
IndexType  num_elems,
Buffer *  buff 
)

Create View object with given name or path in this Group that has a data description with data type and number of elements and attach given Buffer to it.

If given data type is undefined, or given number of elements is < 0, method is a no-op.

This method is equivalent to: group->createView(name, type, num_elems)->attachBuffer(buff), or group->createView(name)->attachBuffer(buff)->apply(type, num_elems).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::attachBuffer()

◆ createView() [7/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
int  ndims,
const IndexType *  shape,
Buffer *  buff 
)

Create View object with given name or path in this Group that has a data description with data type and shape and attach given Buffer to it.

If given data type is undefined, or given number of dimensions is < 0, or given shape ptr is null, method is a no-op.

This method is equivalent to: group->createView(name, type, ndims, shape)->attachBuffer(buff), or group->createView(name)->attachBuffer(buff)->apply(type, ndims, shape).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::attachBuffer()

◆ createView() [8/12]

View* axom::sidre::Group::createView ( const std::string &  path,
const DataType &  dtype,
Buffer *  buff 
)

Create View object with given name or path in this Group that is described by a Conduit DataType object and attach given Buffer to it.

This method is equivalent to: group->createView(name, dtype)->attachBuffer(buff), or group->createView(name)->attachBuffer(buff)->apply(dtype).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::attachBuffer()

◆ createView() [9/12]

View* axom::sidre::Group::createView ( const std::string &  path,
void *  external_ptr 
)

Create View object with given name with given name or path in this Group and attach external data ptr to it.

Attention
Note that the View is "opaque" (it has no knowledge of the type or structure of the data) until a View::apply() method is called.

This method is equivalent to: group->createView(name)->setExternalDataPtr(external_ptr).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::setExternalDataPtr()

◆ createView() [10/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
IndexType  num_elems,
void *  external_ptr 
)

Create View object with given name or path in this Group that has a data description with data type and number of elements and attach externally-owned data to it.

If given data type is undefined, or given number of elements is < 0, method is a no-op.

This method is equivalent to: group->createView(name, type, num_elems)->setExternalDataPtr(external_ptr), or group->createView(name)->setExternalDataPtr(external_ptr)-> apply(type, num_elems).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::setExternalDataPtr()

◆ createView() [11/12]

View* axom::sidre::Group::createView ( const std::string &  path,
TypeID  type,
int  ndims,
const IndexType *  shape,
void *  external_ptr 
)

Create View object with given name or path in this Group that has a data description with data type and shape and attach externally-owned data to it.

If given data type is undefined, or given number of dimensions is < 0, or given shape ptr is null, method is a no-op.

This method is equivalent to: group->createView(name, type, ndims, shape)-> setExternalDataPtr(external_ptr), or group->createView(name)->setExternalDataPtr(external_ptr)-> apply(type, ndims, shape).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::setExternalDataPtr()

◆ createView() [12/12]

View* axom::sidre::Group::createView ( const std::string &  path,
const DataType &  dtype,
void *  external_ptr 
)

Create View object with given name or path in this Group that is described by a Conduit DataType object and attach externally-owned data to it.

This method is equivalent to: group->createView(name, dtype)->setExternalDataPtr(external_ptr), or group->createView(name)->setExternalDataPtr(external_ptr)->apply(dtype).

Returns
pointer to new View object or nullptr if one is not created.
See also
View::attachBuffer()

◆ createViewAndAllocate() [1/3]

View* axom::sidre::Group::createViewAndAllocate ( const std::string &  path,
TypeID  type,
IndexType  num_elems,
int  allocID = INVALID_ALLOCATOR_ID 
)

Create View object with given name or path in this Group that has a data description with data type and number of elements and allocate data for it.

If given data type is undefined, or given number of elements is < 0, method is a no-op.

This is equivalent to: createView(name)->allocate(type, num_elems), or createView(name, type, num_elems)->allocate()

Returns
pointer to new View object or nullptr if one is not created.
See also
View::allocate()

Referenced by isRoot().

◆ createViewAndAllocate() [2/3]

View* axom::sidre::Group::createViewAndAllocate ( const std::string &  path,
TypeID  type,
int  ndims,
const IndexType *  shape,
int  allocID = INVALID_ALLOCATOR_ID 
)

Create View object with given name or path in this Group that has a data description with data type and shape and allocate data for it.

If given data type is undefined, or given number of dimensions is < 0, or given shape ptr is null, method is a no-op.

This method is equivalent to: group->createView(name)->allocate(type, ndims, shape), or createView(name, type, ndims, shape)->allocate().

Returns
pointer to new View object or nullptr if one is not created.
See also
View::allocate()

◆ createViewAndAllocate() [3/3]

View* axom::sidre::Group::createViewAndAllocate ( const std::string &  path,
const DataType &  dtype,
int  allocID = INVALID_ALLOCATOR_ID 
)

Create View object with given name or path in this Group that is described by a Conduit DataType object and allocate data for it.

This method is equivalent to: group->createView(name)->allocate(dtype), or group->createView(name, dtype)->allocate().

If given data type object is empty, data will not be allocated.

Returns
pointer to new View object or nullptr if one is not created.
See also
View::allocate()

◆ createViewScalar()

template<typename ScalarType >
View* axom::sidre::Group::createViewScalar ( const std::string &  path,
ScalarType  value 
)
inline

Create View object with given name or path in this Group set its data to given scalar value.

This is equivalent to: createView(name)->setScalar(value);

If given data type object is empty, data will not be allocated.

Returns
pointer to new View object or nullptr if one is not created.
See also
View::setScalar()

References copyGroup(), copyToConduitNode(), copyView(), createExternalLayout(), createGroup(), createNativeLayout(), createUnnamedGroup(), createView(), createViewString(), destroyGroup(), destroyGroups(), destroyView(), destroyViewAndData(), destroyViews(), destroyViewsAndData(), getFirstValidGroupIndex(), getGroup(), getGroupIndex(), getGroupName(), getNextValidGroupIndex(), hasChildGroup(), hasGroup(), isEquivalentTo(), moveGroup(), moveView(), print(), printTree(), and axom::sidre::View::setScalar().

◆ createViewString()

View* axom::sidre::Group::createViewString ( const std::string &  path,
const std::string &  value 
)

Create View object with given name or path in this Group set its data to given string.

This is equivalent to: createView(name)->setString(value);

If given data type object is empty, data will not be allocated.

Returns
pointer to new View object or nullptr if one is not created.
See also
View::setString()

Referenced by createViewScalar().

◆ destroyView() [1/2]

void axom::sidre::Group::destroyView ( const std::string &  path)

Destroy View with given name or path owned by this Group, but leave its data intect.

Referenced by createViewScalar().

◆ destroyView() [2/2]

void axom::sidre::Group::destroyView ( IndexType  idx)

Destroy View with given index owned by this Group, but leave its data intect.

◆ destroyViews()

void axom::sidre::Group::destroyViews ( )

Destroy all Views owned by this Group, but leave all their data intact.

Referenced by createViewScalar().

◆ destroyViewAndData() [1/2]

void axom::sidre::Group::destroyViewAndData ( const std::string &  path)

Destroy View with given name or path owned by this Group and deallocate its data if it's the only View associated with that data.

Referenced by createViewScalar(), and isUsingList().

◆ destroyViewAndData() [2/2]

void axom::sidre::Group::destroyViewAndData ( IndexType  idx)

Destroy View with given index owned by this Group and deallocate its data if it's the only View associated with that data.

◆ destroyViewsAndData()

void axom::sidre::Group::destroyViewsAndData ( )

Destroy all Views owned by this Group and deallocate data for each View when it's the only View associated with that data.

Referenced by createViewScalar().

◆ moveView()

View* axom::sidre::Group::moveView ( View *  view)

Remove given View object from its owning Group and move it to this Group.

If given View pointer is null or Group already has a View with same name as given View, method is a no-op.

Returns
pointer to given argument View object or nullptr if View is not moved into this Group.

Referenced by createViewScalar().

◆ copyView()

View* axom::sidre::Group::copyView ( View *  view)

Create a copy of given View object and add it to this Group.

Note that View copying is a "shallow" copy; the data associated with the View is not copied. The new View object is associated with the same data as the original.

If given Group pointer is null or Group already has a child Group with same name as given Group, method is a no-op.

Returns
pointer to given argument Group object or nullptr if Group is not moved into this Group.

Referenced by createViewScalar().

◆ hasGroup() [1/2]

bool axom::sidre::Group::hasGroup ( const std::string &  path) const

Return true if this Group has a descendant Group with given name or path; else false.

Referenced by createViewScalar().

◆ hasChildGroup()

bool axom::sidre::Group::hasChildGroup ( const std::string &  name) const

Return true if this Group has a child Group with given name; else false.

Referenced by createViewScalar().

◆ hasGroup() [2/2]

bool axom::sidre::Group::hasGroup ( IndexType  idx) const

Return true if Group has an immediate child Group with given index; else false.

◆ getGroupIndex()

IndexType axom::sidre::Group::getGroupIndex ( const std::string &  name) const

Return the index of immediate child Group with given name.

If no such child Group exists, return sidre::InvalidIndex;

Referenced by createViewScalar().

◆ getGroupName()

const std::string& axom::sidre::Group::getGroupName ( IndexType  idx) const

Return the name of immediate child Group with given index.

If no such child Group exists, return sidre::InvalidName.

Referenced by createViewScalar().

◆ getGroup() [1/4]

Group* axom::sidre::Group::getGroup ( const std::string &  path)

Return pointer to non-const child Group with given name or path.

This method requires that all Groups in the path exist if a path is given.

If no such Group exists, nullptr is returned.

Referenced by axom::mint::ConnectivityArray< TYPE >::ConnectivityArray(), and createViewScalar().

◆ getGroup() [2/4]

Group const* axom::sidre::Group::getGroup ( const std::string &  path) const

Return pointer to const child Group with given name or path.

This method requires that all Groups in the path exist if a path is given.

If no such Group exists, nullptr is returned.

◆ getGroup() [3/4]

Group* axom::sidre::Group::getGroup ( IndexType  idx)

Return pointer to non-const immediate child Group with given index.

If no such Group exists, nullptr is returned.

◆ getGroup() [4/4]

const Group* axom::sidre::Group::getGroup ( IndexType  idx) const

Return pointer to const immediate child Group with given index.

If no such Group exists, nullptr is returned.

◆ getFirstValidGroupIndex()

IndexType axom::sidre::Group::getFirstValidGroupIndex ( ) const

Return first valid child Group index (i.e., smallest index over all child Groups).

sidre::InvalidIndex is returned if Group has no child Groups.

See also
axom::sidre::indexIsValid()

Referenced by createViewScalar().

◆ getNextValidGroupIndex()

IndexType axom::sidre::Group::getNextValidGroupIndex ( IndexType  idx) const

Return next valid child Group index after given index (i.e., smallest index over all child Group indices larger than given one).

sidre::InvalidIndex is returned if there is no valid index greater than given one.

See also
axom::sidre::indexIsValid()

Referenced by createViewScalar().

◆ createGroup()

Group* axom::sidre::Group::createGroup ( const std::string &  path,
bool  is_list = false 
)

Create a child Group within this Group with given name or path.

If name is an empty string or Group already has a child Group with given name or path, method is a no-op.

The optional is_list argument is used to determine if the created child Group will hold items in list format.

Returns
pointer to created Group object or nullptr if new Group is not created.

Referenced by axom::mint::FieldData::createField(), and createViewScalar().

◆ createUnnamedGroup()

Group* axom::sidre::Group::createUnnamedGroup ( bool  is_list = false)

Referenced by createViewScalar().

◆ destroyGroup() [1/2]

void axom::sidre::Group::destroyGroup ( const std::string &  path)

Destroy child Group in this Group with given name or path.

If no such Group exists, method is a no-op.

Referenced by createViewScalar().

◆ destroyGroup() [2/2]

void axom::sidre::Group::destroyGroup ( IndexType  idx)

Destroy child Group within this Group with given index.

If no such Group exists, method is a no-op.

◆ destroyGroups()

void axom::sidre::Group::destroyGroups ( )

Destroy all child Groups in this Group.

Note that this will recursively destroy entire Group sub-tree below this Group.

Referenced by createViewScalar().

◆ moveGroup()

Group* axom::sidre::Group::moveGroup ( Group *  group)

Remove given Group object from its parent Group and make it a child of this Group.

If given Group pointer is null or Group already has a child Group with same name as given Group, method is a no-op.

Returns
pointer to given argument Group object or nullptr if Group is not moved into this Group.

Referenced by createViewScalar().

◆ copyGroup()

Group* axom::sidre::Group::copyGroup ( Group *  group)

Create a copy of Group hierarchy rooted at given Group and make it a child of this Group.

Note that all Views in the Group hierarchy are copied as well.

Note that Group copying is a "shallow" copy; the data associated with Views in a Group are not copied. In particular, the new Group hierarchy and all its Views is associated with the same data as the given Group.

If given Group pointer is null or Group already has a child Group with same name as given Group, method is a no-op.

Returns
pointer to given argument Group object or nullptr if Group is not moved into this Group.

Referenced by createViewScalar().

◆ print() [1/2]

void axom::sidre::Group::print ( ) const

Print JSON description of data Group to stdout.

Note that this will recursively print entire Group sub-tree starting at this Group object.

Referenced by createViewScalar().

◆ print() [2/2]

void axom::sidre::Group::print ( std::ostream &  os) const

Print JSON description of data Group to an ostream.

Note that this will recursively print entire Group sub-tree starting at this Group object.

◆ printTree()

void axom::sidre::Group::printTree ( const int  nlevels,
std::ostream &  os 
) const

Print given number of levels of Group sub-tree starting at this Group object to an output stream.

Referenced by createViewScalar().

◆ copyToConduitNode()

void axom::sidre::Group::copyToConduitNode ( Node &  n) const

Copy description of Group hierarchy rooted at this Group to given Conduit node.

The description includes Views of this Group and all of its children recursively.

Referenced by createViewScalar().

◆ createNativeLayout()

bool axom::sidre::Group::createNativeLayout ( Node &  n,
const Attribute *  attr = nullptr 
) const

Copy data Group native layout to given Conduit node.

The native layout is a Conduit Node hierarchy that maps the Conduit Node data externally to the Sidre View data so that it can be filled in from the data in the file (independent of file format) and can be accessed as a Conduit tree.

Returns
True if the Group or any of its children were added to the Node, false otherwise.

Referenced by createViewScalar().

◆ createExternalLayout()

bool axom::sidre::Group::createExternalLayout ( Node &  n,
const Attribute *  attr = nullptr 
) const

Copy data Group external layout to given Conduit node.

The external layout is a Conduit Node hierarchy that maps the Conduit Node data externally to the Sidre View data so that it can be filled in from the data in the file (independent of file format) and can be accessed as a Conduit tree.

Only the Views which have external data are added to the node.

Returns
True if the Group or any of its children have an external View, false otherwise.

Referenced by createViewScalar().

◆ isEquivalentTo()

bool axom::sidre::Group::isEquivalentTo ( const Group *  other,
bool  checkName = true 
) const

Return true if this Group is equivalent to given Group; else false.

Two Groups are equivalent if they are the root Groups of identical Group hierarchy structures with the same names for all Views and Groups in the hierarchy, and the Views are also equivalent.

Parameters
otherThe group to compare with
checkNameIf true (default), groups must have the same name to be equivalent. If false, disregard the name.
See also
View::isEquivalentTo()

Referenced by createViewScalar().

◆ isUsingMap()

bool axom::sidre::Group::isUsingMap ( ) const
inline

Return true if this Group holds items in map format.

◆ isUsingList()

bool axom::sidre::Group::isUsingList ( ) const
inline

Return true if this Group holds items in list format.

References createGroupAndLoad(), destroyViewAndData(), DISABLE_COPY_AND_ASSIGNMENT, DISABLE_DEFAULT_CTOR, DISABLE_MOVE_AND_ASSIGNMENT, axom::sidre::View::getName(), importConduitTree(), importConduitTreeExternal(), load(), loadExternalData(), rename(), save(), and SIDRE_DEFAULT_PROTOCOL.

◆ save()

void axom::sidre::Group::save ( const std::string &  path,
const std::string &  protocol = "sidre_conduit_json",
const Attribute *  attr = nullptr 
) const

Save the Group to a file.

Saves the tree starting at this Group and the Buffers used by the Views in this tree.

If attr is a null pointer, dump all Views. Otherwise, only dump Views which have the Attribute set.

Parameters
pathfile path
protocolI/O protocol
attrSave Views that have Attribute set.

Referenced by isUsingList().

◆ load() [1/2]

void axom::sidre::Group::load ( const std::string &  path,
const std::string &  protocol = "sidre_conduit_json",
bool  preserve_contents = false 
)

Load a Group hierarchy from a file into this Group.

This method instantiates the Group hierarchy and its Views stored in the file under this Group. The name of this Group is not changed.

If preserve_contents is true, then the names of the children held by the Node cannot be the same as the names of the children already held by this Group. If there is a naming conflict, an error will occur.

Parameters
pathfile path
protocolI/O protocol
preserve_contentsIf true, any child Groups and Views held by this Group remain in place. If false, all child Groups and Views are destroyed before loading data from the file.

Referenced by isUsingList().

◆ load() [2/2]

void axom::sidre::Group::load ( const std::string &  path,
const std::string &  protocol,
bool  preserve_contents,
std::string &  name_from_file 
)

Load a Group hierarchy from a file into this Group, reporting the Group name stored in the file.

This method instantiates the Group hierarchy and its Views stored in the file under this Group. The name of this Group is not changed. The name of the group stored in the file is returned in the output parameter name_from_file. This can be used to rename the group in a subsequent call.

If preserve_contents is true, then the names of the children held by the Node cannot be the same as the names of the children already held by this Group. If there is a naming conflict, an error will occur.

Parameters
[in]pathfile path to load
[in]protocolI/O protocol to use
[in]preserve_contentsIf true, any child Groups and Views held by this Group remain in place. If false, all child Groups and Views are destroyed before loading data from the file.
[out]name_from_fileGroup name stored in the file

◆ createGroupAndLoad()

Group* axom::sidre::Group::createGroupAndLoad ( std::string &  group_name,
const std::string &  path,
const std::string &  protocol,
bool &  load_success 
)

Create a child Group and load a Group hierarchy from file into the new Group.

This is a convenience routine for the following sequence:

  • create a group with name or path group_name
  • load a Group hierarchy from a file into the newly-created Group
  • return the newly created Group, or nullptr if creation failed
  • out-parameters return:
    • the group name from the file
    • a flag indicating success reading the file

As with the createGroup() method, if group_name is empty or there already exists a child Group with that name or path, the child Group will not be created and this method will return nullptr.

As with the load() method, after calling createGroupAndLoad() a host code may choose to rename the newly-created Group with the string returned in group_name.

Parameters
[in,out]group_nameIn: name for the new group. Out: the group name stored in the file.
[in]pathfile path
[in]protocolI/O protocol
[out]load_successReport success of the load operation
Returns
pointer to created Group object or nullptr if new Group is not created.

Referenced by isUsingList().

◆ loadExternalData()

void axom::sidre::Group::loadExternalData ( const std::string &  path)

Load data into the Group's external views from a file.

No protocol argument is needed, as this only is used with the sidre_hdf5 protocol.

Parameters
pathfile path

Referenced by isUsingList().

◆ rename()

bool axom::sidre::Group::rename ( const std::string &  new_name)

Change the name of this Group.

The name of this group is changed to the new name. If this group has a parent group, the name for this group held by the parent is also changed.

Warnings will occur and the name will not be changed under these conditions: If the new name is an empty string, if the new name contains a path delimiter (usually '/'), or if the new name is identical to a name that is already held by the parent for another Group or View object.

It is possible to rename the root Group, but a code cannot subsequently rename root Group back to its original empty string name.

Parameters
new_nameThe new name for this group.
Returns
Success or failure of rename.

Referenced by isUsingList().

◆ importConduitTree()

bool axom::sidre::Group::importConduitTree ( const conduit::Node &  node,
bool  preserve_contents = false 
)

Import data from a conduit Node into a Group.

This imports the hierarchy from the Node into a Sidre Group with the same tree structure.

This does not support conduit's list datatype. If the Node contains a list any where in its tree, the list and any child Nodes descending from the list will not be imported. A warning will occur and an unsuccessful return value will be returned.

If preserve_contents is true, then the names of the children held by the Node cannot be the same as the names of the children already held by this Group. If there is a naming conflict, an error will occur.

Parameters
nodeA conduit Node containing hierarchical data.
preserve_contentsIf true, any child Groups and Views held by this Group remain in place. If false, all child Groups and Views are destroyed before importing data from the Node.
Returns
true for success, false if the full conduit tree is not succesfully imported.

Referenced by isUsingList().

◆ importConduitTreeExternal()

bool axom::sidre::Group::importConduitTreeExternal ( conduit::Node &  node,
bool  preserve_contents = false 
)

Import data from a conduit Node into a Group without copying arrays.

This differs from the importConduitTree in that it does not copy any data held by the Node as an array. Instead it imports the existing pointer to the array as an external pointer.

This imports the hierarchy from the Node into a Sidre Group with the same tree structure.

This does not support conduit's list datatype. If the Node contains a list any where in its tree, the list and any child Nodes descending from the list will not be imported. A warning will occur and an unsuccessful return value will be returned.

If preserve_contents is true, then the names of the children held by the Node cannot be the same as the names of the children already held by this Group. If there is a naming conflict, an error will occur.

Parameters
nodeA conduit Node containing hierarchical data.
preserve_contentsIf true, any child Groups and Views held by this Group remain in place. If false, all child Groups and Views are destroyed before importing data from the Node.
Returns
true for success, false if the full conduit tree is not succesfully imported.

Referenced by isUsingList().

Friends And Related Function Documentation

◆ DataStore

friend class DataStore
friend

◆ View

friend class View
friend
The documentation for this class was generated from the following file: