void set	(	const ustring &	pathName,
		Node	n
	)

Add a new child at a given path.

Parameters:

[in]	pathName	The absolute pathname, or pathname relative to this object, that the child object n will be given.
[in]	n	The 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_INTERNAL	All objects in undocumented state

See also:: StructureCreate.cpp example, VectorNode::append