e57::StructureNode Class Reference

#include <E57Format.h>

Public Member Functions

void checkInvariant (bool doRecurse=true, bool doUpcast=true)
 Check whether StructureNode class invariant is true. More...
 
int64_t childCount () const
 Return number of child nodes contained by this StructureNode. More...
 
ImageFile destImageFile () const
 Get the ImageFile that was declared as the destination for the node when it was created. More...
 
void dump (int indent=0, std::ostream &os=std::cout) const
 Diagnostic function to print internal state of object to output stream in an indented format. More...
 
ustring elementName () const
 Get elementName string, that identifies the node in its parent. More...
 
Node get (const ustring &pathName) const
 Get a child by path name. More...
 
Node get (int64_t index) const
 Get a child element by positional index. More...
 
bool isAttached () const
 Has node been attached into the tree of an ImageFile. More...
 
bool isDefined (const ustring &pathName) const
 Is the given pathName defined relative to this node. More...
 
bool isRoot () const
 Is this a root node. More...
 
 operator Node () const
 Upcast a StructureNode handle to a generic Node handle. More...
 
Node parent () const
 Return parent of node, or self if a root node. More...
 
ustring pathName () const
 Get absolute pathname of node. More...
 
void set (const ustring &pathName, const Node &n)
 Add a new child at a given path. More...
 
 StructureNode ()=delete
 
 StructureNode (const Node &n)
 Downcast a generic Node handle to a StructureNode handle. More...
 
 StructureNode (ImageFile destImageFile)
 Create an empty StructureNode. More...
 

Constructor & Destructor Documentation

◆ StructureNode() [1/3]

e57::StructureNode::StructureNode ( )
delete

◆ StructureNode() [2/3]

StructureNode::StructureNode ( ImageFile  destImageFile)

Create an empty StructureNode.

Parameters
[in]destImageFileThe ImageFile where the new node will eventually be stored.

A StructureNode is a container for collections of named E57 nodes. The destImageFile indicates which ImageFile the StructureNode will eventually be attached to. A node is attached to an ImageFile by adding it underneath the predefined root of the ImageFile (gotten from ImageFile::root). It is not an error to fail to attach the StructureNode to the destImageFile. It is an error to attempt to attach the StructureNode to a different ImageFile.

Precondition
The destImageFile must be open (i.e. destImageFile.isOpen() must be true).
The destImageFile must have been opened in write mode (i.e. destImageFile.isWritable() must be true).
Returns
A smart StructureNode handle referencing the underlying object.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node

◆ StructureNode() [3/3]

StructureNode::StructureNode ( const Node n)
explicit

Downcast a generic Node handle to a StructureNode handle.

Parameters
[in]nThe generic handle to downcast.

The handle n must be for an underlying StructureNode, otherwise an exception is thrown. In designs that need to avoid the exception, use Node::type() to determine the actual type of the n before downcasting. This function must be explicitly called (c++ compiler cannot insert it automatically).

Returns
A smart StructureNode handle referencing the underlying object.
Exceptions
E57_ERROR_BAD_NODE_DOWNCAST
See also
Node::type(), StructureNode::operator Node()

Set our shared_ptr to the downcast shared_ptr

References e57::E57_ERROR_BAD_NODE_DOWNCAST, e57::E57_STRUCTURE, and e57::toString().

Member Function Documentation

◆ checkInvariant()

void StructureNode::checkInvariant ( bool  doRecurse = true,
bool  doUpcast = true 
)

Check whether StructureNode class invariant is true.

Parameters
[in]doRecurseIf true, also check invariants of all children or sub-objects recursively.
[in]doUpcastIf true, also check invariants of the generic Node class.

This function checks at least the assertions in the documented class invariant description (see class reference page for this object). Other internal invariants that are implementation-dependent may also be checked. If any invariant clause is violated, an E57Exception with errorCode of E57_ERROR_INVARIANCE_VIOLATION is thrown.

Checking the invariant recursively may be expensive if the tree is large, so should be used judiciously, in debug versions of the application.

Postcondition
No visible state is modified.
Exceptions
E57_ERROR_INVARIANCE_VIOLATIONor any other E57 ErrorCode

References e57::Node::checkInvariant(), childCount(), destImageFile(), e57::E57_ERROR_INVARIANCE_VIOLATION, e57::Node::elementName(), get(), isDefined(), and e57::Node::parent().

Referenced by e57::ImageFile::checkInvariant().

◆ childCount()

int64_t StructureNode::childCount ( ) const

Return number of child nodes contained by this StructureNode.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
Number of child nodes contained by this StructureNode.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
StructureNode::get(int64_t) const, StructureNode::set, VectorNode::childCount

Referenced by checkInvariant(), e57::ReaderImpl::ReadData3DGroupsData(), and e57::ReaderImpl::SetUpData3DPointsData().

◆ destImageFile()

ImageFile StructureNode::destImageFile ( ) const

Get the ImageFile that was declared as the destination for the node when it was created.

The first argument of the constructors of each of the 8 types of nodes is an ImageFile that indicates which ImageFile the node will eventually be attached to. This function returns that constructor argument. It is an error to attempt to attach the node to a different ImageFile. However it is not an error to not attach the node to any ImageFile (it's just wasteful). Use Node::isAttached to check if the node actually did get attached.

Postcondition
No visible object state is modified.
Returns
The ImageFile that was declared as the destination for the node when it was created.
See also
Node::isAttached, StructureNode::StructureNode(), VectorNode::VectorNode(), CompressedVectorNode::CompressedVectorNode(), IntegerNode::IntegerNode(), ScaledIntegerNode::ScaledIntegerNode(), FloatNode::FloatNode(), StringNode::StringNode(), BlobNode::BlobNode()

Referenced by checkInvariant().

◆ dump()

void StructureNode::dump ( int  indent = 0,
std::ostream &  os = std::cout 
) const

Diagnostic function to print internal state of object to output stream in an indented format.

Parameters
[in]indentNumber of spaces to indent all the printed lines of this object.
[in]osOutput stream to print on.

All objects in the E57 Foundation API (with exception of E57Exception) support a dump() function. These functions print out to the console a detailed listing of the internal state of objects. The content of these printouts is not documented, and is really of interest only to implementation developers/maintainers or the really adventurous users. In implementations of the API other than the Reference Implementation, the dump() functions may produce no output (although the functions should still be defined). The output format may change from version to version.

Postcondition
No visible object state is modified.
Exceptions
NoE57Exceptions

◆ elementName()

ustring StructureNode::elementName ( ) const

Get elementName string, that identifies the node in its parent.

The elementName is a string associated with each parent-child link between nodes. For a given parent, the elementName uniquely identifies each of its children. Thus, any node in a tree can be identified by a sequence of elementNames that form a path from the tree's root node (see Node::pathName for more details).

Three types of nodes (the container node types) can be parents: StructureNode, VectorNode, and CompressedVectorNode. The children of a StructureNode are explicitly given unique elementNames when they are attached to the parent (using StructureNode::set). The children of VectorNode and CompressedVectorNode are implicitly given elementNames based on their position in the list (starting at "0"). In a CompressedVectorNode, the elementName can become quite large: "1000000000" or more. However in a CompressedVectorNode, the elementName string is not stored in the file and is deduced by the position of the child.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
The element name of the node, or "" if a root node.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node::pathName, Node::parent, Node::isRoot

◆ get() [1/2]

Node StructureNode::get ( const ustring pathName) const

Get a child by path name.

Parameters
[in]pathNameThe absolute pathname, or pathname relative to this object, of the object to get. The pathName may be relative to this node, or absolute (starting with a "/"). The origin of the absolute path name is the root of the tree that contains this StructureNode. If this StructureNode is not attached to an ImageFile, the pathName origin root will not the root node of an ImageFile.
Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
The pathName must be defined (i.e. isDefined(pathName)).
Postcondition
No visible state is modified.
Returns
A smart Node handle referencing the child node.
Exceptions
E57_ERROR_BAD_PATH_NAME
E57_ERROR_PATH_UNDEFINED
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
StructureNode::get(int64_t) const

References pathName().

Referenced by draftguitools.gui_trackers.editTracker::move().

◆ get() [2/2]

Node StructureNode::get ( int64_t  index) const

Get a child element by positional index.

Parameters
[in]indexThe index of child element to get, starting at 0.

The order of children is not specified, and may be different than order the children were added to the StructureNode. The order of children may change if more children are added to the StructureNode.

Precondition
0 <= index < childCount()
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
A smart Node handle referencing the child node.
Exceptions
E57_ERROR_CHILD_INDEX_OUT_OF_BOUNDS
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
StructureNode::childCount, StructureNode::get(const ustring&) const, VectorNode::get

Referenced by e57::Node::checkInvariant(), checkInvariant(), e57::ReaderImpl::GetData3DSizes(), e57::ReaderImpl::GetE57Root(), draftguitools.gui_trackers.editTracker::move(), e57::WriterImpl::NewData3D(), Points::E57Reader::read(), e57::ReaderImpl::ReadData3D(), e57::ReaderImpl::ReadData3DGroupsData(), e57::ReaderImpl::ReadImage2D(), e57::WriterImpl::SetUpData3DPointsData(), e57::ReaderImpl::SetUpData3DPointsData(), and e57::WriterImpl::WriteData3DGroupsData().

◆ isAttached()

bool StructureNode::isAttached ( ) const

Has node been attached into the tree of an ImageFile.

Nodes are attached into an ImageFile tree by inserting them as children (directly or indirectly) of the ImageFile's root node. Nodes can also be attached to an ImageFile if they are used in the codecs or prototype trees of an CompressedVectorNode that is attached. Attached nodes will be saved to disk when the ImageFile is closed, and restored when the ImageFile is read back in from disk. Unattached nodes will not be saved to disk. It is not recommended to create nodes that are not eventually attached to the ImageFile.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible object state is modified.
Returns
true if node is child of (or in codecs or prototype of a child CompressedVectorNode of) the root node of an ImageFile.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node::destImageFile, ImageFile::root

◆ isDefined()

bool StructureNode::isDefined ( const ustring pathName) const

Is the given pathName defined relative to this node.

Parameters
[in]pathNameThe absolute pathname, or pathname relative to this object, to check.

The pathName may be relative to this node, or absolute (starting with a "/"). The origin of the absolute path name is the root of the tree that contains this StructureNode. If this StructureNode is not attached to an ImageFile, the pathName origin root will not the root node of an ImageFile.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
true if pathName is currently defined.
Exceptions
E57_ERROR_BAD_PATH_NAME
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
ImageFile::root, VectorNode::isDefined

References pathName().

Referenced by e57::Node::checkInvariant(), checkInvariant(), e57::ReaderImpl::GetData3DSizes(), e57::ReaderImpl::GetE57Root(), Points::E57Reader::read(), e57::ReaderImpl::ReadData3D(), e57::ReaderImpl::ReadData3DGroupsData(), e57::ReaderImpl::ReadImage2D(), e57::WriterImpl::SetUpData3DPointsData(), e57::ReaderImpl::SetUpData3DPointsData(), and e57::WriterImpl::WriteData3DGroupsData().

◆ isRoot()

bool StructureNode::isRoot ( ) const

Is this a root node.

A root node has itself as a parent (it is not a child of any node). Newly constructed nodes (before they are inserted into an ImageFile tree) start out as root nodes. It is possible to temporarily create small trees that are unattached to any ImageFile. In these temporary trees, the top-most node will be a root node. After the tree is attached to the ImageFile tree, the only root node will be the pre-created one of the ImageTree (the one returned by ImageFile::root). The concept of attachment is slightly larger than that of the parent-child relationship (see Node::isAttached and CompressedVectorNode::CompressedVectorNode for more details).

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
true if this node is a root node.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node::parent, Node::isAttached, CompressedVectorNode::CompressedVectorNode

◆ operator Node()

StructureNode::operator Node ( ) const

Upcast a StructureNode handle to a generic Node handle.

An upcast is always safe, and the compiler can automatically insert it for initializations of Node variables and Node function arguments.

Returns
A smart Node handle referencing the underlying object.
Exceptions
NoE57Exceptions.
See also
explanation in Node, Node::type(), StructureNode(const Node&)

Implicitly upcast from shared_ptr<StructureNodeImpl> to SharedNodeImplPtr and construct a Node object

◆ parent()

Node StructureNode::parent ( ) const

Return parent of node, or self if a root node.

Nodes are organized into trees (acyclic graphs) with a distinguished node (the "top-most" node) called the root node. A parent-child relationship is established between nodes to form a tree. Nodes can have zero or one parent. Nodes with zero parents are called root nodes. In the API, if a node has zero parents it is represented by having itself as a parent. Due to the set-once design of the API, a parent-child relationship cannot be modified once established. A child node can be any of the 8 node types, but a parent node can only be one of the 3 container node types (E57_STRUCTURE, E57_VECTOR, and E57_COMPRESSED_VECTOR). Each parent-child link has a string name (the elementName) associated with it (See Node::elementName for more details). More than one tree can be formed at any given time. Typically small trees are temporarily constructed before attachment to an ImageFile so that they will be written to the disk.

Warning: user algorithms that use this function to walk the tree must take care to handle the case where a node is its own parent (it is a root node). Use Node::isRoot to avoid infinite loops or infinite recursion.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
A smart Node handle referencing the parent node or this node if is a root node.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node::isRoot, Node::isAttached, CompressedVectorNode::CompressedVectorNode, Node::elementName

Referenced by PathScripts.PathSimulatorGui.CAMSimTaskUi::accept(), Mod.PartDesign.WizardShaft.Shaft.Shaft::equilibrium(), PathScripts.PathSimulatorGui.CAMSimTaskUi::reject(), and PathScripts.PathOpGui.TaskPanelPage::setParent().

◆ pathName()

ustring StructureNode::pathName ( ) const

Get absolute pathname of node.

Nodes are organized into trees (acyclic graphs) by a parent-child relationship between nodes. Each parent-child relationship has an associated elementName string that is unique for a given parent. Any node in a given tree can be identified by a sequence of elementNames of how to get to the node from the root of the tree. An absolute pathname string that is formed by arranging this sequence of elementNames separated by the "/" character with a leading "/" prepended.

Some example absolute pathNames: "/data3D/0/points/153/cartesianX", "/data3D/0/points", "/cameraImages/1/pose/rotation/w", and "/". These examples have probably been attached to an ImageFile. Here is an example absolute pathName of a node in a pose tree that has not yet been attached to an ImageFile: "/pose/rotation/w".

A technical aside: the elementName of a root node does not appear in absolute pathnames, since the "path" is between the staring node (the root) and the ending node. By convention, in this API, a root node has the empty string ("") as its elementName.

Precondition
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
Postcondition
No visible state is modified.
Returns
The absolute path name of the node.
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNALAll objects in undocumented state
See also
Node::elementName, Node::parent, Node::isRoot

Referenced by get(), isDefined(), and set().

◆ set()

void StructureNode::set ( const ustring pathName,
const Node n 
)

Add a new child at a given path.

Parameters
[in]pathNameThe absolute pathname, or pathname relative to this object, that the child object n will be given.
[in]nThe node to be added to the tree with given pathName.

The pathName may be relative to this node, or absolute (starting with a "/"). The origin of the absolute path name is the root of the tree that contains this StructureNode. If this StructureNode is not attached to an ImageFile, the pathName origin root will not the root node of an ImageFile.

The path name formed from all element names in pathName except the last must exist. If the pathName identifies the child of a VectorNode, then the last element name in pathName must be numeric, and be equal to the childCount of that VectorNode (the request is equivalent to VectorNode::append). The StructureNode must not be a descendent of a homogeneous VectorNode with more than one child.

The element naming grammar specified by the ASTM E57 format standard are not enforced in this function. This would be very difficult to do dynamically, as some of the naming rules involve combinations of names.

Precondition
The new child node n must be a root node (i.e. n.isRoot()).
The destination ImageFile must be open (i.e. destImageFile().isOpen()).
The associated destImageFile must have been opened in write mode (i.e. destImageFile().isWritable()).
The pathName must not already be defined (i.e. !isDefined(pathName)).
The associated destImageFile of this StructureNode and of n must be same (i.e. destImageFile() == n.destImageFile()).
Postcondition
The pathName will be defined (i.e. isDefined(pathName)).
Exceptions
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_BAD_PATH_NAME
E57_ERROR_PATH_UNDEFINED
E57_ERROR_SET_TWICE
E57_ERROR_ALREADY_HAS_PARENT
E57_ERROR_DIFFERENT_DEST_IMAGEFILE
E57_ERROR_HOMOGENEOUS_VIOLATION
E57_ERROR_FILE_IS_READ_ONLY
E57_ERROR_INTERNALAll objects in undocumented state
See also
VectorNode::append

References pathName().

Referenced by draftguitools.gui_trackers.editTracker::move(), e57::WriterImpl::NewData3D(), e57::WriterImpl::NewImage2D(), and e57::WriterImpl::WriterImpl().


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