#include <nodepath.h>
A NodePath identifies a graph node (a true node, port or port list) within a node graph. It consists of a list of identifiers (one for each hierarchy level) just like the path of a file in a file system. In the textual notation of a path we use /
as separator character (except around <
or >
, see below).
The root node has an empty path, and port lists use the special identifiers <
(input port list) and >
(output port list). For example in the graph @graph +---------------------------------------------------------—+ | | o object +-x----------------------------—+ | o geometry | +-n-------—+ | | o bounds --> o bounds --> o in out o --> c o --> center o | | +---------—+ | | | +------------------------------—+ | +---------------------------------------------------------—+ @endgraph there are the following paths:
<
is the path of the input port list of the root node (containing the object port), >
of the output port list (containing the center port).<object
, <object/geometry
, <object/bounds
are the paths of the input ports of the root node.>center
is the path of the output port of the root node.x
is the path of the child node x.x<bounds
and the output port x>c
.x/n
with ports x/n<in
and x/n>out
.A path cannot contain more than one of the port list identifiers <
or >
. All methods which initialize or modify a path return an error if the result was such an invalid path.
To make the string representation shorter and more readable, the separator character /
is only used between regular identifiers, but not around the port list identifiers <
or >
. Therefore we write e.g. x/n>out
instead of x/n/>/out
.
Public Types | |
using | ConstIterator = BaseIterator< const PathBlock, false > |
using | Iterator = ConstIterator |
Static Public Attributes | |
static InternedId | INPUTS |
static InternedId | OUTPUTS |
static InternedId | TEMPLATE |
static constexpr Char | SEPARATOR |
Private Member Functions | |
MAXON_INTERFACE_NONVIRTUAL (NodePathInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.graph.interface.nodepath") | |
Static Private Member Functions | |
static MAXON_METHOD Result< void > | DescribeIO (const DataSerializeInterface &stream) |
using ConstIterator = BaseIterator<const PathBlock, false> |
Iterator to iterate over path elements.
using Iterator = ConstIterator |
Iterator to iterate over path elements.
|
private |
|
static |
Constructs a new node path from the given #path.
[in] | path | The path to use. |
|
static |
Constructs a new node path from the given #path.
[in] | path | The path to use. |
|
static |
Parses a node path given as a character block into a NodePath object. The given #path has to match the format returned by ToCString, otherwise an error is returned.
[in] | path | The path to parse. |
|
static |
Converts a node path into its textual notation. The identifiers of the path are concatenated with the separator character /
between identifiers as in node/child
(with a special handling of the port list identifiers <
or >
, see NodePath). Within an identifier the special characters /
and \\
are escaped by a \\
, so for example if the path is {"a/b", "\u"}, its textual notation is a\\/b/\\\\u
.
[in] | path | The path to parse. |
MAXON_FUNCTION Result<CString> ToCString | ( | ) | const |
Converts this node path into its textual notation. The identifiers of the path are concatenated with the separator character /
between identifiers as in node/child
(with a special handling of the port list identifiers <
or >
, see NodePath). Within an identifier the special characters /
, \\
, <
, >
are escaped by a \\
, so for example if the path is {"a/b", "\u"}, its textual notation is a\\/b/\\\\u
.
MAXON_METHOD Result<void> AppendToCString | ( | CString & | str | ) | const |
|
static |
Converts a node path given as an initializer list into a NodePath object.
[in] | path | The path to use. |
|
static |
Converts a node path given as an initializer list into a NodePath object. NodePathInterface::INPUTS will automatically be prepended, making this a root node input path.
[in] | path | The path to use. |
|
static |
Converts a node path given as an initializer list into a NodePath object. NodePathInterface::OUTPUTS will automatically be prepended, making this a root node output path.
[in] | path | The path to use. |
|
static |
Parses a node path given as a character block into a BaseArray. The given #path has to match the format returned by ToCString, otherwise an error is returned.
[in] | path | The path to parse. |
[in] | out | Parsed path elements are appended to this array. |
MAXON_METHOD PathBlock ToBlock | ( | ) | const |
MAXON_METHOD PathBlock Slice | ( | Int | start | ) | const |
MAXON_METHOD PathBlock Slice | ( | Int | start, |
Int | end | ||
) | const |
MAXON_FUNCTION operator PathBlock | ( | ) | const |
MAXON_METHOD const InternedId& GetLastId | ( | ) | const |
Returns the last element of this path.
MAXON_METHOD Int GetCount | ( | ) | const |
Returns the length of this path. The path elements have indices from 0 up to length-1.
MAXON_FUNCTION Bool IsEmpty | ( | ) | const |
Checks if this path is an empty path. The root node of a node system is identified by an empty path.
MAXON_FUNCTION Bool IsPopulated | ( | void | ) | const |
Checks if this path contains anything.
MAXON_METHOD const InternedId& operator[] | ( | Int | index | ) | const |
MAXON_METHOD Result<NodePath> operator+ | ( | const InternedId & | node | ) | const |
Appends a single identifier at the end of this path.
[in] | node | The identifier to append. |
MAXON_METHOD Result<NodePath> operator+ | ( | const PathBlock & | suffix | ) | const |
Appends a node subpath at the end of this path.
[in] | suffix | The subpath to append. |
MAXON_METHOD Result<NodePath> operator+ | ( | const NodePath & | suffix | ) | const |
Appends a node subpath at the end of this path.
[in] | suffix | The subpath to append. |
MAXON_METHOD Result<NodePath> Prepend | ( | const PathBlock & | prefix | ) | const |
Prepends a node prefix at the beginning of this path.
[in] | prefix | The prefix to insert. |
MAXON_METHOD Result<NodePath> GetPart | ( | StringPosition | start, |
StringCount | count | ||
) | const |
Returns a part of this node path as a new NodePath.
[in] | start | Position where the new partial path will start. This has to be within the bounds, otherwise an error is returned. |
[in] | count | Number of identifiers for the partial path. If it is larger than the number of available identifiers an error is returned. |
MAXON_METHOD Result<NodePath> GetPortPart | ( | ) | const |
Returns the port part of this path as a new NodePath. The port parts starts at the input/output list identifier.
MAXON_METHOD Result<InternedId> GetPortPartAsId | ( | ) | const |
Returns the port part of this path in a single identifier. I.e. the resulting identifier could contain numerous ids with separators if the port is nested. For example if the full path is node>port/nested, then the returned identifier is "port/nested". Special characters are escaped, see NodePathInterface::ToCString.
|
static |
Returns the port part of #path in a single identifier. I.e. the resulting identifier could contain numerous ids with separators if the port is nested. For example if the full path is node>port/nested, then the returned identifier is "port/nested". Special characters are escaped, see NodePathInterface::ToCString.
MAXON_FUNCTION Result<NodePath> GetParent | ( | ) | const |
Returns the path of the parent of this path.
MAXON_METHOD Result<NodePath> Replace | ( | Int | index, |
const InternedId & | id | ||
) | const |
Replaces the identifier at the given index.
[in] | index | The index within this path. |
[in] | id | The new identifier to use. |
MAXON_METHOD Result<Tuple<NodePath, Bool> > Translate | ( | Int | index, |
const HashMap< InternedId, InternedId > & | translation | ||
) | const |
Replaces the identifier at the given index using the translation. This method is useful in conjunction with the translations which are returned by GraphModelInterface::Merge.
[in] | index | The index within this path. |
[in] | translation | A mapping from old identifiers to new identifiers. |
MAXON_METHOD Bool StartsWith | ( | const PathBlock & | other | ) | const |
Checks whether this path starts with other.
[in] | other | Another path. |
MAXON_METHOD Bool EndsWith | ( | const PathBlock & | other | ) | const |
Checks whether this path ends with other.
[in] | other | Another path. |
MAXON_METHOD NODE_KIND GetKind | ( | ) | const |
Returns the node kind of the graph node which is identified by this path:
<
or >
is a true node (NODE_KIND::NODE), for example node/child
.<
or >
is a port list (NODE_KIND::INPUTS or NODE_KIND::OUTPUTS), for example node/child/<
.<
or >
, but does not end with such an identifier is a port (NODE_KIND::INPORT or NODE_KIND::OUTPORT), for example node/child/</in
. MAXON_METHOD NODE_KIND PrivateGetKind | ( | Bool | existing | ) | const |
@MAXON_ANNOTATION{refclass=false}
MAXON_METHOD Int GetNodeDepth | ( | ) | const |
Returns the hierarchy depth of the true node which is identified by this path. If this path identifies a true node directly, the depth is the number of path elements. Otherwise, if this path identifies a port or port list, the depth is the depth of the innermost enclosing true node, i.e., the number of path elements up to but excluding the port list identifier. For example all of the paths node/child
, node/child/<
and node/child/</in
have a node depth of 2 because for all those paths node/child
is the innermost true node.
MAXON_METHOD Result<NodePath> GetTopLevelPort | ( | ) | const |
Returns the path to the top-level port of this path. The top-level port of a port is the outermost enclosing port, i.e., an enclosing port which is a direct child of a port list, or the port itself if this is already a direct child of a port list. For example in the node @graph +------—+ o x | o a | o b | o c | +------—+ @endgraph all of the ports x, a, b, c have x as their top-level port.
MAXON_METHOD Result<NodePath> GetNode | ( | ) | const |
GetNode returns only the path of the node without ports.
MAXON_FUNCTION PathBlock GetPortPath | ( | ) | const |
GetPortPath returns only the relative port path without the node path.
MAXON_METHOD Bool IsTopLevelPort | ( | ) | const |
Checks if this path identifies a top-level port. A top-level port is a port which is not nested within another port, but a direct child of the input or output port list of a node.
MAXON_METHOD Bool IsPortOfRoot | ( | ) | const |
Checks if this path identifies a port of the root node of a node system. This includes not only top-level ports, but also nested ports.
MAXON_METHOD String ToString | ( | const FormatStatement * | fs = nullptr | ) | const |
MAXON_METHOD Bool IsEqual | ( | const NodePathInterface * | other | ) | const |
MAXON_METHOD COMPARERESULT Compare | ( | const NodePathInterface * | other | ) | const |
Compares this node path with the other one. This uses the same comparison as e.g. Block<InternedId>, namely the lexicographic order. It compares path elements of both paths until it finds the first difference (or the end of a path is reached), and then it returns the result of the comparison of the first difference. If the end of one path has been reached, the shorter path is less than the longer path.
[in] | other | Another path. |
MAXON_METHOD HashInt GetHashCode | ( | ) | const |
Returns the hash code of this @CLASS.
MAXON_METHOD UniqueHash GetUniqueHashCode | ( | ) | const |
Returns the 128-bit hash value of this @CLASS. The implementation ensures uniform distribution, so for practical purposes you can safely assume that two objects are equal if their hash values are equal.
MAXON_METHOD const UniqueHash& GetFastUniqueHashCode | ( | ) | const |
Returns a hash value for the node path which has been pre-computed on construction of the path. The hash value is not stable across different runs of the application as it is based on pointers.
MAXON_METHOD HashInt GetFastHashCode | ( | ) | const |
Returns a hash code for the node path which has been pre-computed on construction of the path. The hash code is not stable across different runs of the application as it is based on pointers.
|
static |
Returns a hash code for the path block which is compatible with GetFastHashCode.
[in] | block | A node path. |
|
static |
Returns a hash value for the path block which is compatible with GetFastHashCode.
[in] | block | A node path. |
MAXON_METHOD Bool IsEqual | ( | const PathBlock & | prefix, |
const PathBlock & | suffix, | ||
Bool | ignorePrefixWhenEmpty | ||
) | const |
Checks if this node path is equal to the concatenation {prefix + suffix}.
[in] | prefix | The first path block for the concatenation. |
[in] | suffix | The second path block for the concatenation. |
[in] | ignorePrefixWhenEmpty | If true, a special mode is used when this node path is empty: prefix is ignored in that case, so it's tested if suffix is empty as well. |
{prefix + suffix}, false otherwise. MAXON_METHOD Bool LessThan | ( | const PathBlock & | other | ) | const |
Compares this node path with the other one. This uses lexicographic order, see Compare.
[in] | other | Another path given as a PathBlock. |
MAXON_METHOD Bool LessThanOrEqual | ( | const PathBlock & | other | ) | const |
Compares this node path with the other one. This uses lexicographic order, see Compare.
[in] | other | Another path given as a PathBlock. |
MAXON_FUNCTION ConstIterator Begin | ( | ) | const |
Returns an iterator pointing to the first identifier of this path.
MAXON_FUNCTION ConstIterator End | ( | ) | const |
Returns an iterator pointing behind the last identifier of this path.
|
staticprivate |
|
static |
Checks if the identifier i stands for the input or output port list of a node, so if it is either '<' or '>'.
[in] | i | An identifier for a general node. |
|
static |
The identifier '<', this is used for the input port list of a node.
|
static |
The identifier '>', this is used for the output port list of a node.
|
static |
The identifier '#', this is used for the template port of a variadic port.
|
staticconstexpr |
'/' This is used as a separator for each node depth in a NodePath.