NodePathInterface Class Reference

#include <nodepath.h>

Detailed Description

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:

  • The empty path identifies the root node.
  • < 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 has the input port x<bounds and the output port x>c.
  • x has the inner node 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.

See also
$ref usernodes_nodes @MAXON_ANNOTATION{implementationClassMacro=NODE_PATH_IMPL}

Public Types

using ConstIterator = BaseIterator< const PathBlock, false >
 
using Iterator = ConstIterator
 

Public Member Functions

MAXON_FUNCTION Result< CStringToCString () const
 
MAXON_METHOD Result< void > AppendToCString (CString &str) const
 
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 InternedIdGetLastId () const
 
MAXON_METHOD Int GetCount () const
 
MAXON_FUNCTION Bool IsEmpty () const
 
MAXON_FUNCTION Bool IsPopulated () const
 
MAXON_METHOD const InternedIdoperator[] (Int index) const
 
MAXON_METHOD Result< NodePath > operator+ (const InternedId &node) const
 
MAXON_METHOD Result< NodePath > operator+ (const PathBlock &suffix) const
 
MAXON_METHOD Result< NodePath > operator+ (const NodePath &suffix) const
 
MAXON_METHOD Result< NodePath > Prepend (const PathBlock &prefix) const
 
MAXON_METHOD Result< NodePath > GetPart (StringPosition start, StringCount count) const
 
MAXON_METHOD Result< NodePath > GetPortPart () const
 
MAXON_METHOD Result< InternedIdGetPortPartAsId () const
 
MAXON_FUNCTION Result< NodePath > GetParent () const
 
MAXON_METHOD Result< NodePath > Replace (Int index, const InternedId &id) const
 
MAXON_METHOD Result< Tuple< NodePath, Bool > > Translate (Int index, const HashMap< InternedId, InternedId > &translation) const
 
MAXON_METHOD Bool StartsWith (const PathBlock &other) const
 
MAXON_METHOD Bool EndsWith (const PathBlock &other) const
 
MAXON_METHOD NODE_KIND GetKind () const
 
MAXON_METHOD NODE_KIND PrivateGetKind (Bool existing) const
 
MAXON_METHOD Int GetNodeDepth () const
 
MAXON_METHOD Result< NodePath > GetTopLevelPort () const
 
MAXON_METHOD Result< NodePath > GetNode () const
 
MAXON_FUNCTION PathBlock GetPortPath () const
 
MAXON_METHOD Bool IsTopLevelPort () const
 
MAXON_METHOD Bool IsPortOfRoot () const
 
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
 
MAXON_METHOD HashInt GetHashCode () const
 
MAXON_METHOD UniqueHash GetUniqueHashCode () const
 
MAXON_METHOD const UniqueHashGetFastUniqueHashCode () const
 
MAXON_METHOD HashInt GetFastHashCode () const
 
MAXON_METHOD Bool IsEqual (const PathBlock &prefix, const PathBlock &suffix, Bool ignorePrefixWhenEmpty) const
 
MAXON_METHOD Bool LessThan (const PathBlock &other) const
 
MAXON_METHOD Bool LessThanOrEqual (const PathBlock &other) const
 
MAXON_FUNCTION ConstIterator Begin () const
 
MAXON_FUNCTION ConstIterator End () const
 

Static Public Member Functions

static MAXON_METHOD Result< NodePathInterface * > Alloc (MAXON_SOURCE_LOCATION_DECLARATION, const PathBlock &path)
 
static MAXON_METHOD Result< NodePathInterface * > Alloc (MAXON_SOURCE_LOCATION_DECLARATION, BaseArray< InternedId > &&path)
 
static MAXON_METHOD Result< NodePath > FromCString (const Block< const Char > &path)
 
static MAXON_METHOD Result< CStringToCString (const PathBlock &path)
 
static MAXON_METHOD Result< NodePath > FromPathBlock (const PathBlock &path)
 
static MAXON_METHOD Result< NodePath > FromInPathBlock (const PathBlock &path)
 
static MAXON_METHOD Result< NodePath > FromOutPathBlock (const PathBlock &path)
 
static MAXON_METHOD Result< void > ParsePath (const Block< const Char > &path, BaseArray< InternedId > &out)
 
static MAXON_METHOD Result< InternedIdGetPortPartAsId (const PathBlock &path)
 
static MAXON_METHOD HashInt GetFastHashCodeOfPathBlock (const PathBlock &block)
 
static MAXON_METHOD UniqueHash GetFastUniqueHashCodeOfPathBlock (const PathBlock &block)
 
static Bool IsInputsOrOutputs (const InternedId &i)
 

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)
 

Member Typedef Documentation

◆ ConstIterator

using ConstIterator = BaseIterator<const PathBlock, false>

Iterator to iterate over path elements.

◆ Iterator

Iterator to iterate over path elements.

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( NodePathInterface  ,
MAXON_REFERENCE_COPY_ON_WRITE  ,
"net.maxon.graph.interface.nodepath"   
)
private

◆ Alloc() [1/2]

static MAXON_METHOD Result<NodePathInterface*> Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  ,
const PathBlock path 
)
static

Constructs a new node path from the given #path.

Parameters
[in]pathThe path to use.

◆ Alloc() [2/2]

Constructs a new node path from the given #path.

Parameters
[in]pathThe path to use.

◆ FromCString()

static MAXON_METHOD Result<NodePath> FromCString ( const Block< const Char > &  path)
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.

Parameters
[in]pathThe path to parse.
Returns
The parsed NodePath.

◆ ToCString() [1/2]

static MAXON_METHOD Result<CString> ToCString ( const PathBlock path)
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.

Parameters
[in]pathThe path to parse.
Returns
The textual notation of the path as a CString.

◆ ToCString() [2/2]

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.

Returns
The textual notation of this path as a CString.

◆ AppendToCString()

MAXON_METHOD Result<void> AppendToCString ( CString str) const

Converts this node path into its textual notation and appends this to the given CString.

See also
ToCString
Parameters
[in,out]strThe CString to append to.

◆ FromPathBlock()

static MAXON_METHOD Result<NodePath> FromPathBlock ( const PathBlock path)
static

Converts a node path given as an initializer list into a NodePath object.

Parameters
[in]pathThe path to use.
Returns
The new NodePath.

◆ FromInPathBlock()

static MAXON_METHOD Result<NodePath> FromInPathBlock ( const PathBlock path)
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.

Parameters
[in]pathThe path to use.
Returns
The new NodePath.

◆ FromOutPathBlock()

static MAXON_METHOD Result<NodePath> FromOutPathBlock ( const PathBlock path)
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.

Parameters
[in]pathThe path to use.
Returns
The new NodePath.

◆ ParsePath()

static MAXON_METHOD Result<void> ParsePath ( const Block< const Char > &  path,
BaseArray< InternedId > &  out 
)
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.

Parameters
[in]pathThe path to parse.
[in]outParsed path elements are appended to this array.

◆ ToBlock()

MAXON_METHOD PathBlock ToBlock ( ) const

Returns the internally stored path as a Block.

Returns
This path as a Block.

◆ Slice() [1/2]

MAXON_METHOD PathBlock Slice ( Int  start) const

Slice the NodePath from start to GetCount(). Does not make a heap allocation, only a sub block of the original NodePath is returned.

Parameters
[in]startThe starting depth index in the original NodePath.
Returns
The sliced block.

◆ Slice() [2/2]

MAXON_METHOD PathBlock Slice ( Int  start,
Int  end 
) const

Slice the NodePath from start to end. Does not make a heap allocation, only a sub block of the original NodePath is returned. Slice from 0 to GetNodeDepth() for a node path (without port and port list).

Parameters
[in]startThe starting depth index in the original NodePath.
[in]endThe ending depth index in the original NodePath.
Returns
The sliced block.

◆ operator PathBlock()

MAXON_FUNCTION operator PathBlock ( ) const

Returns the internally stored path as a Block.

Returns
This path as a Block.

◆ GetLastId()

MAXON_METHOD const InternedId& GetLastId ( ) const

Returns the last element of this path.

Returns
Last element of this path, or an empty identifier if the path is empty.

◆ GetCount()

MAXON_METHOD Int GetCount ( ) const

Returns the length of this path. The path elements have indices from 0 up to length-1.

Returns
Number of elements of this path.

◆ IsEmpty()

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.

Returns
True if this is an empty path (of length 0), false otherwise.

◆ IsPopulated()

MAXON_FUNCTION Bool IsPopulated ( ) const

Checks if this path contains anything.

Returns
True if this is not an empty path (of length 0).

◆ operator[]()

MAXON_METHOD const InternedId& operator[] ( Int  index) const

Returns the path element at the given index. The index is zero-based, i.e., from 0 up to length-1.

Parameters
[in]indexThe index of the element to return. It has to be within the bounds, otherwise the behaviour is undefined.
Returns
The path element at index.

◆ operator+() [1/3]

MAXON_METHOD Result<NodePath> operator+ ( const InternedId node) const

Appends a single identifier at the end of this path.

Parameters
[in]nodeThe identifier to append.

◆ operator+() [2/3]

MAXON_METHOD Result<NodePath> operator+ ( const PathBlock suffix) const

Appends a node subpath at the end of this path.

Parameters
[in]suffixThe subpath to append.

◆ operator+() [3/3]

MAXON_METHOD Result<NodePath> operator+ ( const NodePath &  suffix) const

Appends a node subpath at the end of this path.

Parameters
[in]suffixThe subpath to append.

◆ Prepend()

MAXON_METHOD Result<NodePath> Prepend ( const PathBlock prefix) const

Prepends a node prefix at the beginning of this path.

Parameters
[in]prefixThe prefix to insert.

◆ GetPart()

MAXON_METHOD Result<NodePath> GetPart ( StringPosition  start,
StringCount  count 
) const

Returns a part of this node path as a new NodePath.

Parameters
[in]startPosition where the new partial path will start. This has to be within the bounds, otherwise an error is returned.
[in]countNumber of identifiers for the partial path. If it is larger than the number of available identifiers an error is returned.
Returns
The partial path.

◆ GetPortPart()

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.

Returns
The port part of this path.

◆ GetPortPartAsId() [1/2]

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.

Returns
The relative path condensed in an identifier.

◆ GetPortPartAsId() [2/2]

static MAXON_METHOD Result<InternedId> GetPortPartAsId ( const PathBlock path)
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.

Returns
The relative path condensed in an identifier.

◆ GetParent()

MAXON_FUNCTION Result<NodePath> GetParent ( ) const

Returns the path of the parent of this path.

Returns
The parent of this path, or an empty path if this path is already the root path.

◆ Replace()

MAXON_METHOD Result<NodePath> Replace ( Int  index,
const InternedId id 
) const

Replaces the identifier at the given index.

Parameters
[in]indexThe index within this path.
[in]idThe new identifier to use.
Returns
A new path with the replaced identifier.

◆ Translate()

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.

Parameters
[in]indexThe index within this path.
[in]translationA mapping from old identifiers to new identifiers.
Returns
A path with the replaced identifier (or this path if no replacement was found in translation), and a Bool which is true if and only if a replacement has occurred.

◆ StartsWith()

MAXON_METHOD Bool StartsWith ( const PathBlock other) const

Checks whether this path starts with other.

Parameters
[in]otherAnother path.
Returns
True if this path starts with the given path.

◆ EndsWith()

MAXON_METHOD Bool EndsWith ( const PathBlock other) const

Checks whether this path ends with other.

Parameters
[in]otherAnother path.
Returns
True if this path ends with the given path.

◆ GetKind()

MAXON_METHOD NODE_KIND GetKind ( ) const

Returns the node kind of the graph node which is identified by this path:

  • A path without path list identifiers < or > is a true node (NODE_KIND::NODE), for example node/child.
  • A path which ends with < or > is a port list (NODE_KIND::INPUTS or NODE_KIND::OUTPUTS), for example node/child/<.
  • A path which contains < or >, but does not end with such an identifier is a port (NODE_KIND::INPORT or NODE_KIND::OUTPORT), for example node/child/</in.
    Returns
    The node kind of the graph node identified by this path.

◆ PrivateGetKind()

MAXON_METHOD NODE_KIND PrivateGetKind ( Bool  existing) const

@MAXON_ANNOTATION{refclass=false}

◆ GetNodeDepth()

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.

Returns
The depth of the true node given by this path.

◆ GetTopLevelPort()

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.

Returns
The path to the top-level port of the port given by this path. If this path doesn't represent a port, an error is returned.

◆ GetNode()

MAXON_METHOD Result<NodePath> GetNode ( ) const

GetNode returns only the path of the node without ports.

Returns
Path to the node on success.

◆ GetPortPath()

MAXON_FUNCTION PathBlock GetPortPath ( ) const

GetPortPath returns only the relative port path without the node path.

Returns
Node relative port path.

◆ IsTopLevelPort()

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.

See also
GetTopLevelPort
Returns
True if this path stands for a top-level port, false otherwise.

◆ IsPortOfRoot()

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.

Returns
True if this path stands for a port of the root node, false otherwise.

◆ ToString()

MAXON_METHOD String ToString ( const FormatStatement fs = nullptr) const

Returns a String representation of this @CLASS.

Parameters
[in]formatStatementNullptr or additional formatting instruction.
Returns
String representation of this @CLASS.

◆ IsEqual() [1/2]

MAXON_METHOD Bool IsEqual ( const NodePathInterface other) const

Checks if this @CLASS equals other.

Parameters
[in]otherAnother @CLASS.
Returns
True if this equals other, false otherwise.

◆ Compare()

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.

Parameters
[in]otherAnother path.
Returns
Result of the comparison.

◆ GetHashCode()

MAXON_METHOD HashInt GetHashCode ( ) const

Returns the hash code of this @CLASS.

Returns
Hash code of this @CLASS.

◆ GetUniqueHashCode()

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.

Returns
Hash value of this @CLASS.

◆ GetFastUniqueHashCode()

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.

Returns
A hash value for the node path.
See also
FastNodePathHash

◆ GetFastHashCode()

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.

Returns
A hash code for the node path.
See also
FastNodePathHash

◆ GetFastHashCodeOfPathBlock()

static MAXON_METHOD HashInt GetFastHashCodeOfPathBlock ( const PathBlock block)
static

Returns a hash code for the path block which is compatible with GetFastHashCode.

Parameters
[in]blockA node path.
Returns
The GetFastHashCode-compatible hash code of block.
See also
FastNodePathHash

◆ GetFastUniqueHashCodeOfPathBlock()

static MAXON_METHOD UniqueHash GetFastUniqueHashCodeOfPathBlock ( const PathBlock block)
static

Returns a hash value for the path block which is compatible with GetFastHashCode.

Parameters
[in]blockA node path.
Returns
The GetFastHashCode-compatible hash value of block.
See also
FastNodePathHash

◆ IsEqual() [2/2]

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}.

Parameters
[in]prefixThe first path block for the concatenation.
[in]suffixThe second path block for the concatenation.
[in]ignorePrefixWhenEmptyIf 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.
Returns
True if this node path equals {prefix + suffix}, false otherwise.

◆ LessThan()

MAXON_METHOD Bool LessThan ( const PathBlock other) const

Compares this node path with the other one. This uses lexicographic order, see Compare.

Parameters
[in]otherAnother path given as a PathBlock.
Returns
True if this node path is less than other, false otherwise.

◆ LessThanOrEqual()

MAXON_METHOD Bool LessThanOrEqual ( const PathBlock other) const

Compares this node path with the other one. This uses lexicographic order, see Compare.

Parameters
[in]otherAnother path given as a PathBlock.
Returns
True if this node path is less than or equal to other, false otherwise.

◆ Begin()

MAXON_FUNCTION ConstIterator Begin ( ) const

Returns an iterator pointing to the first identifier of this path.

Returns
Iterator pointing to first identifier.

◆ End()

Returns an iterator pointing behind the last identifier of this path.

Returns
Iterator pointing behind last identifier.

◆ DescribeIO()

static MAXON_METHOD Result<void> DescribeIO ( const DataSerializeInterface stream)
staticprivate

◆ IsInputsOrOutputs()

static Bool IsInputsOrOutputs ( const InternedId i)
static

Checks if the identifier i stands for the input or output port list of a node, so if it is either '<' or '>'.

Parameters
[in]iAn identifier for a general node.
Returns
True if the identifier stands for the input or output port list.

Member Data Documentation

◆ INPUTS

InternedId INPUTS
static

The identifier '<', this is used for the input port list of a node.

◆ OUTPUTS

InternedId OUTPUTS
static

The identifier '>', this is used for the output port list of a node.

◆ TEMPLATE

InternedId TEMPLATE
static

The identifier '#', this is used for the template port of a variadic port.

◆ SEPARATOR

constexpr Char SEPARATOR
staticconstexpr

'/' This is used as a separator for each node depth in a NodePath.