E57 Foundation API v1.1.312  Aug. 10, 2011
Public Member Functions
StructureNode Class Reference

An E57 element containing named child nodes. More...

List of all members.

Public Member Functions

 StructureNode (ImageFile destImageFile)
 Create an empty StructureNode.
int64_t childCount () const
 Return number of child nodes contained by this StructureNode.
bool isDefined (const ustring &pathName) const
 Is the given pathName defined relative to this node.
Node get (int64_t index) const
 Get a child element by positional index.
Node get (const ustring &pathName) const
 Get a child by path name.
void set (const ustring &pathName, Node n)
 Add a new child at a given path.
 operator Node () const
 Upcast a StructureNode handle to a generic Node handle.
 StructureNode (const Node &n)
 Downcast a generic Node handle to a StructureNode handle.
bool isRoot () const
 Is this a root node.
Node parent () const
 Return parent of node, or self if a root node.
ustring pathName () const
 Get absolute pathname of node.
ustring elementName () const
 Get elementName string, that identifies the node in its parent.
ImageFile destImageFile () const
 Get the ImageFile that was declared as the destination for the node when it was created.
bool isAttached () const
 Has node been attached into the tree of an ImageFile.
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.
void checkInvariant (bool doRecurse=true, bool doUpcast=true)
 Check whether StructureNode class invariant is true.

Detailed Description

An E57 element containing named child nodes.

A StructureNode is a container of named child nodes, which may be any of the eight node types. The children of a structure node must have unique elementNames. Once a child node is set with a particular elementName, it may not be modified.

See Node class discussion for discussion of the common functions that StructureNode supports.

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 consistancy and throws an exception if the invariant is violated:

void StructureNode::checkInvariant(bool doRecurse, bool doUpcast) {
    // If destImageFile not open, can't test invariant (almost every call would throw)
    if (!destImageFile().isOpen())
        return;

    // If requested, call Node::checkInvariant
    if (doUpcast)
        static_cast<Node>(*this).checkInvariant(false, false);

    // Check each child
    for (int64_t i = 0; i < childCount(); i++) {
        Node child = get(i);

        // If requested, check children recursively
        if (doRecurse)
            child.checkInvariant(doRecurse, true);

        // Child's parent must be this
        if (static_cast<Node>(*this) != child.parent())
           throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

        // Child's elementName must be defined
        if (!isDefined(child.elementName()))
           throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

        // Getting child by element name must yield same child
        Node n = get(child.elementName());
        if (n != child)
           throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
    }
} // end StructureNode::checkInvariant

See also:
Node
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines