Node Class Reference
Generic handle to any of the 8 types of E57 element objects. More...
Detailed Description
Generic handle to any of the 8 types of E57 element objects.
A Node is a generic handle to an underlying object that is any of the eight type of E57 element objects. Each of the eight node types support the all the functions of the Node class. A Node is a vertex in a tree (acyclic graph), which is a hierarchical organization of nodes. At the top of the hierarchy is a single root Node. If a Node is a container type (StructureNode, VectorNode, CompressedVectorNode) it may have child nodes. The following are non-container type nodes (also known as terminal nodes): IntegerNode, ScaledIntegerNode, FloatNode, StringNode, BlobNode. Terminal nodes store various types of values and cannot have children. Each Node has an elementName, which is a string that uniquely identifies it within the children of its parent. Children of a StructureNode have elementNames that are explicitly given by the API user. Children of a VectorNode or CompressedVectorNode have element names that are string reorientations of the Node's positional index, starting at "0". A path name is a sequence elementNames (divided by "/") that must be traversed to get from a Node to one of its descendents.
Data is organized in an E57 format file (an ImageFile) hierarchically. Each ImageFile has a predefined root node that other nodes can be attached to as children (either directly or indirectly). A Node can exist temporarily without being attached to an ImageFile, however the state will not be saved in the associated file, and the state will be lost if the program exits.
A handle to a generic Node may be safely be converted to and from a handle to the Node's true underlying type. Since an attempt to convert a generic Node to a incorrect handle type will fail with an exception, the true type should be interrogated beforehand.
Due to the set-once design of the Foundation API, terminal nodes are immutable (i.e. their values and attributes can't change after creation). Once a parent-child relationship has been established, it cannot be changed.
Only generic operations are available for a Node, to access more specific operations (e.g. StructureNode::childCount) the generic handle must be converted to the node type of the underlying object. This conversion is done in a type-safe way using "downcasting" (see discussion below).
Downcasting
The conversion from a general handle type to a specific handle type is called "downcasting". Each of the 8 specific node types have a downcast function (see IntegerNode::IntegerNode(const Node&) for example). If a downcast is requested to an incorrect type (e.g. taking a Node handle that is actually a FloatNode and trying to downcast it to a IntegerNode), an E57Exception is thrown with an ErrorCode of E57_ERROR_BAD_NODE_DOWNCAST. Depending on the program design, throwing a bad downcast exception might be acceptable, if an element must be a specific type and no recovery is possible. If a standard requires an element be one several types, then Node::type() should be used to interrogate the type in an if or switch statement. Downcasting is "dangerous" (can fail with an exception) so the API requires the programmer to explicitly call the downcast functions rather than have the c++ compiler insert them automatically.
Upcasting
The conversion of a specific node handle (e.g. IntegerNode) to a general Node handle is called "upcasting". Each of the 8 specific node types have an upcast function (see IntegerNode::operator Node() for example). Upcasting is "safe" (can't cause an exception) so the API allows the c++ compiler to insert them automatically. Upcasting is useful if you have a specific node handle and want to call a function that takes a generic Node handle argument. In this case, the function can be called with the specific handle and the compiler will automatically insert the upcast conversion. This implicit conversion allows one function, with an argument of type Node, to handle operations that apply to all 8 types of nodes (e.g. StructureNode::set()).
Class Invariant
A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:
The documentation for this class was generated from the following file:
- FreeCAD/src/3rdParty/libE57Format/src/E57Format.cpp
