#include <E57Format.h>

Public Member Functions
void	checkInvariant (bool doRecurse=true, bool doDowncast=true)
	Check whether Node class invariant is true. 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 element name of node. More...

bool	isAttached () const
	Has node been attached into the tree of an ImageFile. More...

bool	isRoot () const
	Is this a root node. More...

	Node ()=delete

bool	operator!= (Node n2) const
	Test if two node handles refer to different underlying nodes. More...

bool	operator== (Node n2) const
	Test if two node handles refer to the same underlying node. More...

Node	parent () const
	Return parent of node, or self if a root node. More...

ustring	pathName () const
	Get absolute pathname of node. More...

NodeType	type () const
	Return the NodeType of a generic Node. More...

Constructor & Destructor Documentation

◆ Node()

e57::Node::Node ( )

delete

Referenced by parent().

Member Function Documentation

◆ checkInvariant()

void Node::checkInvariant	(	bool	doRecurse = `true`,
		bool	doDowncast = `true`
	)

Check whether Node class invariant is true.

Parameters

[in]	doRecurse	If true, also check invariants of all children or sub-objects recursively.
[in]	doDowncast	If true, also check any invariants of the actual derived type in addition to the generic node invariants.

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.

Specifying doRecurse=true only makes sense if doDowncast=true is also specified (the generic Node has no way to access any children). 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_VIOLATION or any other E57 ErrorCode

See also: Class Invariant section in Node, IntegerNode::checkInvariant, ScaledIntegerNode::checkInvariant, FloatNode::checkInvariant, BlobNode::checkInvariant, StructureNode::checkInvariant, VectorNode::checkInvariant, CompressedVectorNode::checkInvariant

References e57::CompressedVectorNode::checkInvariant(), e57::ScaledIntegerNode::checkInvariant(), destImageFile(), e57::E57_BLOB, e57::E57_COMPRESSED_VECTOR, e57::E57_ERROR_INVARIANCE_VIOLATION, e57::E57_FLOAT, e57::E57_INTEGER, e57::E57_SCALED_INTEGER, e57::E57_STRING, e57::E57_STRUCTURE, e57::E57_VECTOR, elementName(), e57::StructureNode::get(), isAttached(), e57::StructureNode::isDefined(), e57::ImageFile::isOpen(), isRoot(), parent(), pathName(), e57::ImageFile::root(), and type().

Referenced by e57::StructureNode::checkInvariant(), e57::VectorNode::checkInvariant(), e57::CompressedVectorNode::checkInvariant(), e57::IntegerNode::checkInvariant(), e57::ScaledIntegerNode::checkInvariant(), e57::FloatNode::checkInvariant(), e57::StringNode::checkInvariant(), and e57::BlobNode::checkInvariant().

◆ destImageFile()

ImageFile Node::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 Node::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]	indent	Number of spaces to indent all the printed lines of this object.
[in]	os	Output 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

No	E57Exceptions

◆ elementName()

ustring Node::elementName ( ) const

Get element name of node.

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_INTERNAL	All objects in undocumented state

See also: Node::pathName, Node::parent, Node::isRoot

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

◆ isAttached()

bool Node::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_INTERNAL	All objects in undocumented state

See also: Node::destImageFile, ImageFile::root

Referenced by checkInvariant().

◆ isRoot()

bool Node::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_INTERNAL	All objects in undocumented state

See also: Node::parent, Node::isAttached, CompressedVectorNode::CompressedVectorNode

Referenced by checkInvariant().

◆ operator!=()

bool Node::operator!= ( Node n2 ) const

Test if two node handles refer to different underlying nodes.

Parameters

[in] n2 The node to compare this node with

Postcondition: No visible object state is modified.

Returns: true if node handles refer to different underlying nodes.

Exceptions

No	E57Exceptions

◆ operator==()

bool Node::operator== ( Node n2 ) const

Test if two node handles refer to the same underlying node.

Parameters

[in] n2 The node to compare this node with

Postcondition: No visible object state is modified.

Returns: true if node handles refer to the same underlying node.

Exceptions

No	E57Exceptions

◆ parent()

Node Node::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_INTERNAL	All objects in undocumented state

See also: Node::isRoot, Node::isAttached, CompressedVectorNode::CompressedVectorNode, Node::elementName

References Node().

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

◆ pathName()

ustring Node::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_INTERNAL	All objects in undocumented state

See also: Node::elementName, Node::parent, Node::isRoot

Referenced by checkInvariant().

◆ type()

NodeType Node::type ( ) const

Return the NodeType of a generic Node.

This function allows the actual node type to be interrogated before upcasting the handle to the actual node type (see Upcasting and Dowcasting section in Node).

Returns: The NodeType of a generic Node, which may be one of the following NodeType enumeration values: E57_STRUCTURE, E57_VECTOR, E57_COMPRESSED_VECTOR, E57_INTEGER, E57_SCALED_INTEGER, E57_FLOAT, E57_STRING, E57_BLOB.

Postcondition: No visible state is modified.

See also: NodeType, upcast/dowcast discussion in Node

Referenced by ArchProfile.ProfileTaskPanel::accept(), checkInvariant(), e57::ReaderImpl::ReadData3D(), ArchProfile.ProfileTaskPanel::retranslateUi(), and e57::ReaderImpl::SetUpData3DPointsData().

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

FreeCAD/src/3rdParty/libE57Format/include/E57Format.h
FreeCAD/src/3rdParty/libE57Format/src/E57Format.cpp

Public Member Functions

Constructor & Destructor Documentation

◆ Node()

Member Function Documentation

◆ checkInvariant()

◆ destImageFile()

◆ dump()

◆ elementName()

◆ isAttached()

◆ isRoot()

◆ operator!=()

◆ operator==()

◆ parent()

◆ pathName()

◆ type()