#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< CString >	ToCString () 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

const MAXON_METHOD InternedId &	GetLastId () const

MAXON_METHOD Int	GetCount () const

MAXON_FUNCTION Bool	IsEmpty () const

MAXON_FUNCTION Bool	IsPopulated () const

const MAXON_METHOD InternedId &	operator[] (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_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

const MAXON_METHOD HashValue &	GetFastHashValue () 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< CString >	ToCString (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 HashInt	GetFastHashCodeOfPathBlock (const PathBlock &block)

static MAXON_METHOD HashValue	GetFastHashValueOfPathBlock (const PathBlock &block)

static Bool	IsInputsOrOutputs (const InternedId &i)

Static Public Attributes
static InternedId	INPUTS

static InternedId	OUTPUTS

static InternedId	TEMPLATE

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

using Iterator = ConstIterator

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] path The path to use.

◆ Alloc() [2/2]

static MAXON_METHOD Result<NodePathInterface*> Alloc	(	MAXON_SOURCE_LOCATION_DECLARATION	,
		BaseArray< InternedId > &&	path
	)

static

Constructs a new node path from the given #path.

Parameters

[in] path The 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] path The 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] path The 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] str The 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] path The 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] path The 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] path The 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]	path	The path to parse.
[in]	out	Parsed 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() [2/2]

MAXON_METHOD PathBlock Slice	(	Int	start,
		Int	end
	)		const

◆ operator PathBlock()

MAXON_FUNCTION operator PathBlock ( ) const

Returns the internally stored path as a Block.

Returns: This path as a Block.

◆ GetLastId()

const MAXON_METHOD 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[]()

const MAXON_METHOD 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] index The 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] node The 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] suffix The 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] suffix The 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] prefix The 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]	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.

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.

◆ 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]	index	The index within this path.
[in]	id	The 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]	index	The index within this path.
[in]	translation	A 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] other Another 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] other Another 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: NodePath with the node path on success.

◆ GetPortPath()

MAXON_FUNCTION PathBlock GetPortPath ( ) const

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

Returns: PathBlock with the ports on success.

◆ 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] formatStatement Nullptr 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] other Another @CLASS.

Returns: True if this equals #other, false otherwise.

◆ Compare()

MAXON_METHOD COMPARERESULT Compare ( const NodePathInterface * other ) const

Compares this and #other.

Parameters

[in] other Another @CLASS.

Returns: Result of the comparison.

◆ GetHashCode()

MAXON_METHOD HashInt GetHashCode ( ) const

Returns the hash code of this @CLASS.

Returns: Hash code of this @CLASS.

◆ GetFastHashValue()

const MAXON_METHOD HashValue& GetFastHashValue ( ) 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

◆ GetFastHashCodeOfPathBlock()

static MAXON_METHOD HashInt GetFastHashCodeOfPathBlock ( const PathBlock & block )

static

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

Parameters

[in] block A node path.

Returns: The GetFastHashValue-compatible hash code of block.

See also: FastNodePathHash

◆ GetFastHashValueOfPathBlock()

static MAXON_METHOD HashValue GetFastHashValueOfPathBlock ( const PathBlock & block )

static

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

Parameters

[in] block A node path.

Returns: The GetFastHashValue-compatible hash value of block.

See also: FastNodePathHash

◆ IsEqual() [2/2]

MAXON_METHOD Bool IsEqual	(	const PathBlock &	prefix,
		const PathBlock &	suffix,
		Bool	ignorePrefixWhenEmpty
	)		const

◆ LessThan()

MAXON_METHOD Bool LessThan ( const PathBlock & other ) const

◆ LessThanOrEqual()

MAXON_METHOD Bool LessThanOrEqual ( const PathBlock & other ) const

◆ Begin()

MAXON_FUNCTION ConstIterator Begin ( ) const

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

Returns: Iterator pointing to first identifier.

◆ End()

MAXON_FUNCTION ConstIterator End ( ) const

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] i An 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.

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Member Typedef Documentation

◆ ConstIterator

◆ Iterator

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

◆ Alloc() [1/2]

◆ Alloc() [2/2]

◆ FromCString()

◆ ToCString() [1/2]

◆ ToCString() [2/2]

◆ AppendToCString()

◆ FromPathBlock()

◆ FromInPathBlock()

◆ FromOutPathBlock()

◆ ParsePath()

◆ ToBlock()

◆ Slice() [1/2]

◆ Slice() [2/2]

◆ operator PathBlock()

◆ GetLastId()

◆ GetCount()

◆ IsEmpty()

◆ IsPopulated()

◆ operator[]()

◆ operator+() [1/3]

◆ operator+() [2/3]

◆ operator+() [3/3]

◆ Prepend()

◆ GetPart()

◆ GetPortPart()

◆ GetParent()

◆ Replace()

◆ Translate()

◆ StartsWith()

◆ EndsWith()

◆ GetKind()

◆ PrivateGetKind()

◆ GetNodeDepth()

◆ GetTopLevelPort()

◆ GetNode()

◆ GetPortPath()

◆ IsTopLevelPort()

◆ IsPortOfRoot()

◆ ToString()

◆ IsEqual() [1/2]

◆ Compare()

◆ GetHashCode()

◆ GetFastHashValue()

◆ GetFastHashCodeOfPathBlock()

◆ GetFastHashValueOfPathBlock()

◆ IsEqual() [2/2]

◆ LessThan()

◆ LessThanOrEqual()

◆ Begin()

◆ End()

◆ DescribeIO()

◆ IsInputsOrOutputs()

Member Data Documentation

◆ INPUTS

◆ OUTPUTS

◆ TEMPLATE