All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
SdfPath Class Reference

A path value used to locate objects in layers or scenegraphs. More...

#include <path.h>

Public Member Functions

Constructors


 SdfPath () noexcept=default
 Constructs the default, empty path.
 
SDF_API SdfPath (const std::string &path)
 Creates a path from the given string.
 
Querying paths
SDF_API size_t GetPathElementCount () const
 Returns the number of path elements in this path.
 
SDF_API bool IsAbsolutePath () const
 Returns whether the path is absolute.
 
SDF_API bool IsAbsoluteRootPath () const
 Return true if this path is the AbsoluteRootPath().
 
SDF_API bool IsPrimPath () const
 Returns whether the path identifies a prim.
 
SDF_API bool IsAbsoluteRootOrPrimPath () const
 Returns whether the path identifies a prim or the absolute root.
 
SDF_API bool IsRootPrimPath () const
 Returns whether the path identifies a root prim.
 
SDF_API bool IsPropertyPath () const
 Returns whether the path identifies a property.
 
SDF_API bool IsPrimPropertyPath () const
 Returns whether the path identifies a prim's property.
 
SDF_API bool IsNamespacedPropertyPath () const
 Returns whether the path identifies a namespaced property.
 
SDF_API bool IsPrimVariantSelectionPath () const
 Returns whether the path identifies a variant selection for a prim.
 
SDF_API bool IsPrimOrPrimVariantSelectionPath () const
 Return true if this path is a prim path or is a prim variant selection path.
 
SDF_API bool ContainsPrimVariantSelection () const
 Returns whether the path or any of its parent paths identifies a variant selection for a prim.
 
bool ContainsPropertyElements () const
 Return true if this path contains any property elements, false otherwise.
 
SDF_API bool ContainsTargetPath () const
 Return true if this path is or has a prefix that's a target path or a mapper path.
 
SDF_API bool IsRelationalAttributePath () const
 Returns whether the path identifies a relational attribute.
 
SDF_API bool IsTargetPath () const
 Returns whether the path identifies a relationship or connection target.
 
SDF_API bool IsMapperPath () const
 Returns whether the path identifies a connection mapper.
 
SDF_API bool IsMapperArgPath () const
 Returns whether the path identifies a connection mapper arg.
 
SDF_API bool IsExpressionPath () const
 Returns whether the path identifies a connection expression.
 
bool IsEmpty () const noexcept
 Returns true if this is the empty path (SdfPath::EmptyPath()).
 
SDF_API TfToken GetAsToken () const
 Return the string representation of this path as a TfToken.
 
SDF_API TfToken const & GetToken () const
 Return the string representation of this path as a TfToken lvalue.
 
SDF_API std::string GetAsString () const
 Return the string representation of this path as a std::string.
 
SDF_API const std::string & GetString () const
 Return the string representation of this path as a std::string.
 
SDF_API const char * GetText () const
 Returns the string representation of this path as a c string.
 
SDF_API SdfPathVector GetPrefixes () const
 Returns the prefix paths of this path.
 
SDF_API SdfPathVector GetPrefixes (size_t numPrefixes) const
 Return up to numPrefixes prefix paths of this path.
 
SDF_API void GetPrefixes (SdfPathVector *prefixes) const
 Fills prefixes with prefixes of this path.
 
SDF_API void GetPrefixes (SdfPathVector *prefixes, size_t numPrefixes) const
 Fill prefixes with up to numPrefixes prefixes of this path.
 
SDF_API TfSpan< SdfPathGetPrefixes (TfSpan< SdfPath > prefixes) const
 Fill prefixes with up to prefixes.size() prefixes of this path.
 
SDF_API SdfPathAncestorsRange GetAncestorsRange () const
 Return a range for iterating over the ancestors of this path.
 
SDF_API const std::string & GetName () const
 Returns the name of the prim, property or relational attribute identified by the path.
 
SDF_API const TfTokenGetNameToken () const
 Returns the name of the prim, property or relational attribute identified by the path, as a token.
 
SDF_API std::string GetElementString () const
 Returns an ascii representation of the "terminal" element of this path, which can be used to reconstruct the path using AppendElementString() on its parent.
 
SDF_API TfToken GetElementToken () const
 Like GetElementString() but return the value as a TfToken.
 
SDF_API SdfPath ReplaceName (TfToken const &newName) const
 Return a copy of this path with its final component changed to newName.
 
SDF_API const SdfPathGetTargetPath () const
 Returns the relational attribute or mapper target path for this path.
 
SDF_API void GetAllTargetPathsRecursively (SdfPathVector *result) const
 Returns all the relationship target or connection target paths contained in this path, and recursively all the target paths contained in those target paths in reverse depth-first order.
 
SDF_API std::pair< std::string, std::string > GetVariantSelection () const
 Returns the variant selection for this path, if this is a variant selection path.
 
SDF_API bool HasPrefix (const SdfPath &prefix) const
 Return true if both this path and prefix are not the empty path and this path has prefix as a prefix.
 
Creating new paths by modifying existing paths
SDF_API SdfPath GetParentPath () const
 Return the path that identifies this path's namespace parent.
 
SDF_API SdfPath GetPrimPath () const
 Creates a path by stripping all relational attributes, targets, properties, and variant selections from the leafmost prim path, leaving the nearest path for which IsPrimPath() returns true.
 
SDF_API SdfPath GetPrimOrPrimVariantSelectionPath () const
 Creates a path by stripping all relational attributes, targets, and properties, leaving the nearest path for which IsPrimOrPrimVariantSelectionPath() returns true.
 
SDF_API SdfPath GetAbsoluteRootOrPrimPath () const
 Creates a path by stripping all properties and relational attributes from this path, leaving the path to the containing prim.
 
SDF_API SdfPath StripAllVariantSelections () const
 Create a path by stripping all variant selections from all components of this path, leaving a path with no embedded variant selections.
 
SDF_API SdfPath AppendPath (const SdfPath &newSuffix) const
 Creates a path by appending a given relative path to this path.
 
SDF_API SdfPath AppendChild (TfToken const &childName) const
 Creates a path by appending an element for childName to this path.
 
SDF_API SdfPath AppendProperty (TfToken const &propName) const
 Creates a path by appending an element for propName to this path.
 
SDF_API SdfPath AppendVariantSelection (const std::string &variantSet, const std::string &variant) const
 Creates a path by appending an element for variantSet and variant to this path.
 
SDF_API SdfPath AppendTarget (const SdfPath &targetPath) const
 Creates a path by appending an element for targetPath.
 
SDF_API SdfPath AppendRelationalAttribute (TfToken const &attrName) const
 Creates a path by appending an element for attrName to this path.
 
SDF_API SdfPath ReplaceTargetPath (const SdfPath &newTargetPath) const
 Replaces the relational attribute's target path.
 
SDF_API SdfPath AppendMapper (const SdfPath &targetPath) const
 Creates a path by appending a mapper element for targetPath.
 
SDF_API SdfPath AppendMapperArg (TfToken const &argName) const
 Creates a path by appending an element for argName.
 
SDF_API SdfPath AppendExpression () const
 Creates a path by appending an expression element.
 
SDF_API SdfPath AppendElementString (const std::string &element) const
 Creates a path by extracting and appending an element from the given ascii element encoding.
 
SDF_API SdfPath AppendElementToken (const TfToken &elementTok) const
 Like AppendElementString() but take the element as a TfToken.
 
SDF_API SdfPath ReplacePrefix (const SdfPath &oldPrefix, const SdfPath &newPrefix, bool fixTargetPaths=true) const
 Returns a path with all occurrences of the prefix path oldPrefix replaced with the prefix path newPrefix.
 
SDF_API SdfPath GetCommonPrefix (const SdfPath &path) const
 Returns a path with maximal length that is a prefix path of both this path and path.
 
SDF_API std::pair< SdfPath, SdfPathRemoveCommonSuffix (const SdfPath &otherPath, bool stopAtRootPrim=false) const
 Find and remove the longest common suffix from two paths.
 
SDF_API SdfPath MakeAbsolutePath (const SdfPath &anchor) const
 Returns the absolute form of this path using anchor as the relative basis.
 
SDF_API SdfPath MakeRelativePath (const SdfPath &anchor) const
 Returns the relative form of this path using anchor as the relative basis.
 

Static Public Member Functions

static SDF_API const SdfPathEmptyPath ()
 The empty path value, equivalent to SdfPath().
 
static SDF_API const SdfPathAbsoluteRootPath ()
 The absolute path representing the top of the namespace hierarchy.
 
static SDF_API const SdfPathReflexiveRelativePath ()
 The relative path representing "self".
 
Valid path strings, prim and property names
static SDF_API bool IsValidIdentifier (const std::string &name)
 Returns whether name is a legal identifier for any path component.
 
static SDF_API bool IsValidNamespacedIdentifier (const std::string &name)
 Returns whether name is a legal namespaced identifier.
 
static SDF_API std::vector< std::string > TokenizeIdentifier (const std::string &name)
 Tokenizes name by the namespace delimiter.
 
static SDF_API TfTokenVector TokenizeIdentifierAsTokens (const std::string &name)
 Tokenizes name by the namespace delimiter.
 
static SDF_API std::string JoinIdentifier (const std::vector< std::string > &names)
 Join names into a single identifier using the namespace delimiter.
 
static SDF_API std::string JoinIdentifier (const TfTokenVector &names)
 Join names into a single identifier using the namespace delimiter.
 
static SDF_API std::string JoinIdentifier (const std::string &lhs, const std::string &rhs)
 Join lhs and rhs into a single identifier using the namespace delimiter.
 
static SDF_API std::string JoinIdentifier (const TfToken &lhs, const TfToken &rhs)
 Join lhs and rhs into a single identifier using the namespace delimiter.
 
static SDF_API std::string StripNamespace (const std::string &name)
 Returns name stripped of any namespaces.
 
static SDF_API TfToken StripNamespace (const TfToken &name)
 Returns name stripped of any namespaces.
 
static SDF_API std::pair< std::string, bool > StripPrefixNamespace (const std::string &name, const std::string &matchNamespace)
 Returns (name, true) where name is stripped of the prefix specified by matchNamespace if name indeed starts with matchNamespace.
 
static SDF_API bool IsValidPathString (const std::string &pathString, std::string *errMsg=0)
 Return true if pathString is a valid path string, meaning that passing the string to the SdfPath constructor will result in a valid, non-empty SdfPath.
 
Utilities
static SDF_API SdfPathVector GetConciseRelativePaths (const SdfPathVector &paths)
 Given some vector of paths, get a vector of concise unambiguous relative paths.
 
static SDF_API void RemoveDescendentPaths (SdfPathVector *paths)
 Remove all elements of paths that are prefixed by other elements in paths.
 
static SDF_API void RemoveAncestorPaths (SdfPathVector *paths)
 Remove all elements of paths that prefix other elements in paths.
 

Friends

class Sdfext_PathAccess
 
class SdfPathAncestorsRange
 
void swap (SdfPath &lhs, SdfPath &rhs)
 

Operators

template<class HashState >
void TfHashAppend (HashState &h, SdfPath const &path)
 
bool operator== (const SdfPath &rhs) const
 Equality operator.
 
bool operator!= (const SdfPath &rhs) const
 Inequality operator.
 
bool operator< (const SdfPath &rhs) const
 Comparison operator.
 
bool operator> (const SdfPath &rhs) const
 Greater than operator.
 
bool operator<= (const SdfPath &rhs) const
 Less than or equal operator.
 
bool operator>= (const SdfPath &rhs) const
 Greater than or equal operator.
 
size_t GetHash () const
 

Detailed Description

A path value used to locate objects in layers or scenegraphs.

Overview

SdfPath is used in several ways:

  • As a storage key for addressing and accessing values held in a SdfLayer
  • As a namespace identity for scenegraph objects
  • As a way to refer to other scenegraph objects through relative paths

The paths represented by an SdfPath class may be either relative or absolute. Relative paths are relative to the prim object that contains them (that is, if an SdfRelationshipSpec target is relative, it is relative to the SdfPrimSpec object that owns the SdfRelationshipSpec object).

SdfPath objects can be readily created from and converted back to strings, but as SdfPath objects, they have behaviors that make it easy and efficient to work with them. The SdfPath class provides a full range of methods for manipulating scene paths by appending a namespace child, appending a relationship target, getting the parent path, and so on. Since the SdfPath class uses a node-based representation internally, you should use the editing functions rather than converting to and from strings if possible.

Path Syntax

Like a filesystem path, an SdfPath is conceptually just a sequence of path components. Unlike a filesystem path, each component has a type, and the type is indicated by the syntax.

Two separators are used between parts of a path. A slash ("/") following an identifier is used to introduce a namespace child. A period (".") following an identifier is used to introduce a property. A property may also have several non-sequential colons (':') in its name to provide a rudimentary namespace within properties but may not end or begin with a colon.

A leading slash in the string representation of an SdfPath object indicates an absolute path. Two adjacent periods indicate the parent namespace.

Brackets ("[" and "]") are used to indicate relationship target paths for relational attributes.

The first part in a path is assumed to be a namespace child unless it is preceded by a period. That means:

  • /Foo is an absolute path specifying the root prim Foo.
  • /Foo/Bar is an absolute path specifying namespace child Bar of root prim Foo.
  • /Foo/Bar.baz is an absolute path specifying property baz of namespace child Bar of root prim Foo.
  • Foo is a relative path specifying namespace child Foo of the current prim.
  • Foo/Bar is a relative path specifying namespace child Bar of namespace child Foo of the current prim.
  • Foo/Bar.baz is a relative path specifying property baz of namespace child Bar of namespace child Foo of the current prim.
  • .foo is a relative path specifying the property foo of the current prim.
  • /Foo.bar[/Foo.baz].attrib is a relational attribute path. The relationship /Foo.bar has a target /Foo.baz. There is a relational attribute attrib on that relationship->target pair.

A Note on Thread-Safety

SdfPath is strongly thread-safe, in the sense that zero additional synchronization is required between threads creating or using SdfPath values. Just like TfToken, SdfPath values are immutable. Internally, SdfPath uses a global prefix tree to efficiently share representations of paths, and provide fast equality/hashing operations, but modifications to this table are internally synchronized. Consequently, as with TfToken, for best performance it is important to minimize the number of values created (since it requires synchronized access to this table) or copied (since it requires atomic ref-counting operations).

Definition at line 273 of file path.h.

Constructor & Destructor Documentation

◆ SdfPath() [1/2]

SdfPath ( )
defaultnoexcept

Constructs the default, empty path.

◆ SdfPath() [2/2]

SDF_API SdfPath ( const std::string &  path)
explicit

Creates a path from the given string.

If the given string is not a well-formed path, this will raise a Tf error. Note that passing an empty std::string() will also raise an error; the correct way to get the empty path is SdfPath().

Internal dot-dots will be resolved by removing the first dot-dot, the element preceding it, and repeating until no internal dot-dots remain.

Note that most often new paths are expected to be created by asking existing paths to return modified versions of themselves.

Member Function Documentation

◆ AbsoluteRootPath()

static SDF_API const SdfPath & AbsoluteRootPath ( )
static

The absolute path representing the top of the namespace hierarchy.

◆ AppendChild()

SDF_API SdfPath AppendChild ( TfToken const &  childName) const

Creates a path by appending an element for childName to this path.

This path must be a prim path, the AbsoluteRootPath or the ReflexiveRelativePath.

◆ AppendElementString()

SDF_API SdfPath AppendElementString ( const std::string &  element) const

Creates a path by extracting and appending an element from the given ascii element encoding.

Attempting to append a root or empty path (or malformed path) or attempting to append to the EmptyPath will raise an error and return the EmptyPath.

May also fail and return EmptyPath if this path's type cannot possess a child of the type encoded in element.

◆ AppendElementToken()

SDF_API SdfPath AppendElementToken ( const TfToken elementTok) const

Like AppendElementString() but take the element as a TfToken.

◆ AppendExpression()

SDF_API SdfPath AppendExpression ( ) const

Creates a path by appending an expression element.

This path must be a prim property or relational attribute path.

◆ AppendMapper()

SDF_API SdfPath AppendMapper ( const SdfPath targetPath) const

Creates a path by appending a mapper element for targetPath.

This path must be a prim property or relational attribute path.

◆ AppendMapperArg()

SDF_API SdfPath AppendMapperArg ( TfToken const &  argName) const

Creates a path by appending an element for argName.

This path must be a mapper path.

◆ AppendPath()

SDF_API SdfPath AppendPath ( const SdfPath newSuffix) const

Creates a path by appending a given relative path to this path.

If the newSuffix is a prim path, then this path must be a prim path or a root path.

If the newSuffix is a prim property path, then this path must be a prim path or the ReflexiveRelativePath.

◆ AppendProperty()

SDF_API SdfPath AppendProperty ( TfToken const &  propName) const

Creates a path by appending an element for propName to this path.

This path must be a prim path or the ReflexiveRelativePath.

◆ AppendRelationalAttribute()

SDF_API SdfPath AppendRelationalAttribute ( TfToken const &  attrName) const

Creates a path by appending an element for attrName to this path.

This path must be a target path.

◆ AppendTarget()

SDF_API SdfPath AppendTarget ( const SdfPath targetPath) const

Creates a path by appending an element for targetPath.

This path must be a prim property or relational attribute path.

◆ AppendVariantSelection()

SDF_API SdfPath AppendVariantSelection ( const std::string &  variantSet,
const std::string &  variant 
) const

Creates a path by appending an element for variantSet and variant to this path.

This path must be a prim path.

◆ ContainsPrimVariantSelection()

SDF_API bool ContainsPrimVariantSelection ( ) const

Returns whether the path or any of its parent paths identifies a variant selection for a prim.

◆ ContainsPropertyElements()

bool ContainsPropertyElements ( ) const
inline

Return true if this path contains any property elements, false otherwise.

A false return indicates a prim-like path, specifically a root path, a prim path, or a prim variant selection path. A true return indicates a property-like path: a prim property path, a target path, a relational attribute path, etc.

Definition at line 371 of file path.h.

◆ ContainsTargetPath()

SDF_API bool ContainsTargetPath ( ) const

Return true if this path is or has a prefix that's a target path or a mapper path.

◆ EmptyPath()

static SDF_API const SdfPath & EmptyPath ( )
static

The empty path value, equivalent to SdfPath().

◆ GetAbsoluteRootOrPrimPath()

SDF_API SdfPath GetAbsoluteRootOrPrimPath ( ) const

Creates a path by stripping all properties and relational attributes from this path, leaving the path to the containing prim.

If the path is already a prim or absolute root path, the same path is returned.

◆ GetAllTargetPathsRecursively()

SDF_API void GetAllTargetPathsRecursively ( SdfPathVector *  result) const

Returns all the relationship target or connection target paths contained in this path, and recursively all the target paths contained in those target paths in reverse depth-first order.

For example, given the path: '/A/B.a[/C/D.a[/E/F.a]].a[/A/B.a[/C/D.a]]' this method produces: '/A/B.a[/C/D.a]', '/C/D.a', '/C/D.a[/E/F.a]', '/E/F.a'

◆ GetAncestorsRange()

SDF_API SdfPathAncestorsRange GetAncestorsRange ( ) const

Return a range for iterating over the ancestors of this path.

The range provides iteration over the prefixes of a path, ordered from longest to shortest (the opposite of the order of the prefixes returned by GetPrefixes).

◆ GetAsString()

SDF_API std::string GetAsString ( ) const

Return the string representation of this path as a std::string.

This function is recommended only for human-readable or diagnostic output. Use the SdfPath API to manipulate paths. It is less error-prone and has better performance.

◆ GetAsToken()

SDF_API TfToken GetAsToken ( ) const

Return the string representation of this path as a TfToken.

This function is recommended only for human-readable or diagnostic output. Use the SdfPath API to manipulate paths. It is less error-prone and has better performance.

◆ GetCommonPrefix()

SDF_API SdfPath GetCommonPrefix ( const SdfPath path) const

Returns a path with maximal length that is a prefix path of both this path and path.

◆ GetConciseRelativePaths()

static SDF_API SdfPathVector GetConciseRelativePaths ( const SdfPathVector &  paths)
static

Given some vector of paths, get a vector of concise unambiguous relative paths.

GetConciseRelativePaths requires a vector of absolute paths. It finds a set of relative paths such that each relative path is unique.

◆ GetElementString()

SDF_API std::string GetElementString ( ) const

Returns an ascii representation of the "terminal" element of this path, which can be used to reconstruct the path using AppendElementString() on its parent.

EmptyPath(), AbsoluteRootPath(), and ReflexiveRelativePath() are not considered elements (one of the defining properties of elements is that they have a parent), so GetElementString() will return the empty string for these paths.

Unlike GetName() and GetTargetPath(), which provide you "some" information about the terminal element, this provides a complete representation of the element, for all element types.

Also note that whereas GetName(), GetNameToken(), GetText(), GetString(), and GetTargetPath() return cached results, GetElementString() always performs some amount of string manipulation, which you should keep in mind if performance is a concern.

◆ GetElementToken()

SDF_API TfToken GetElementToken ( ) const

Like GetElementString() but return the value as a TfToken.

◆ GetHash()

size_t GetHash ( ) const
inline

Definition at line 957 of file path.h.

◆ GetName()

SDF_API const std::string & GetName ( ) const

Returns the name of the prim, property or relational attribute identified by the path.

Returns EmptyPath if this path is a target or mapper path.

  • Returns "" for EmptyPath.
  • Returns "." for ReflexiveRelativePath.
  • Returns ".." for a path ending in ParentPathElement.

◆ GetNameToken()

SDF_API const TfToken & GetNameToken ( ) const

Returns the name of the prim, property or relational attribute identified by the path, as a token.

◆ GetParentPath()

SDF_API SdfPath GetParentPath ( ) const

Return the path that identifies this path's namespace parent.

For a prim path (like '/foo/bar'), return the prim's parent's path ('/foo'). For a prim property path (like '/foo/bar.property'), return the prim's path ('/foo/bar'). For a target path (like '/foo/bar.property[/target]') return the property path ('/foo/bar.property'). For a mapper path (like '/foo/bar.property.mapper[/target]') return the property path ('/foo/bar.property). For a relational attribute path (like '/foo/bar.property[/target].relAttr') return the relationship target's path ('/foo/bar.property[/target]'). For a prim variant selection path (like '/foo/bar{var=sel}') return the prim path ('/foo/bar'). For a root prim path (like '/rootPrim'), return AbsoluteRootPath() ('/'). For a single element relative prim path (like 'relativePrim'), return ReflexiveRelativePath() ('.'). For ReflexiveRelativePath(), return the relative parent path ('..').

Note that the parent path of a relative parent path ('..') is a relative grandparent path ('../..'). Use caution writing loops that walk to parent paths since relative paths have infinitely many ancestors. To more safely traverse ancestor paths, consider iterating over an SdfPathAncestorsRange instead, as returned by GetAncestorsRange().

◆ GetPathElementCount()

SDF_API size_t GetPathElementCount ( ) const

Returns the number of path elements in this path.

◆ GetPrefixes() [1/5]

SDF_API SdfPathVector GetPrefixes ( ) const

Returns the prefix paths of this path.

Prefixes are returned in order of shortest to longest. The path itself is returned as the last prefix. Note that if the prefix order does not need to be from shortest to longest, it is more efficient to use GetAncestorsRange, which produces an equivalent set of paths, ordered from longest to shortest.

◆ GetPrefixes() [2/5]

SDF_API void GetPrefixes ( SdfPathVector *  prefixes) const

Fills prefixes with prefixes of this path.

This avoids copy constructing the return value.

Prefixes are returned in order of shortest to longest. The path itself is returned as the last prefix. Note that if the prefix order does not need to be from shortest to longest, it is more efficient to use GetAncestorsRange(), which produces an equivalent set of paths, ordered from longest to shortest.

◆ GetPrefixes() [3/5]

SDF_API void GetPrefixes ( SdfPathVector *  prefixes,
size_t  numPrefixes 
) const

Fill prefixes with up to numPrefixes prefixes of this path.

Prefixes are filled in order of shortest to longest. The path itself is included as the last prefix. Note that if the prefix order does not need to be from shortest to longest, it can be more efficient to use GetAncestorsRange(), which produces an equivalent set of paths, ordered from longest to shortest. If numPrefixes is 0 or greater than the number of this path's prefixes, fill all prefixes.

◆ GetPrefixes() [4/5]

SDF_API SdfPathVector GetPrefixes ( size_t  numPrefixes) const

Return up to numPrefixes prefix paths of this path.

Prefixes are returned in order of shortest to longest. The path itself is returned as the last prefix. Note that if the prefix order does not need to be from shortest to longest, it is more efficient to use GetAncestorsRange, which produces an equivalent set of paths, ordered from longest to shortest. If numPrefixes is 0 or greater than the number of this path's prefixes, fill all prefixes.

◆ GetPrefixes() [5/5]

SDF_API TfSpan< SdfPath > GetPrefixes ( TfSpan< SdfPath prefixes) const

Fill prefixes with up to prefixes.size() prefixes of this path.

Return the subspan of prefixes filled.

Prefixes are filled in order of shortest to longest. The path itself is always included as the last prefix. If prefixes is not large enough to contain all prefixes, the shortest prefixes are omitted. If prefixes is larger than the number of prefixes filled, return the subspan filled by calling TfSpan::first() with the number of filled prefixes. Note that if the prefix order does not need to be from shortest to longest, it can be more efficient to use GetAncestorsRange(), which produces an equivalent set of paths, ordered from longest to shortest.

◆ GetPrimOrPrimVariantSelectionPath()

SDF_API SdfPath GetPrimOrPrimVariantSelectionPath ( ) const

Creates a path by stripping all relational attributes, targets, and properties, leaving the nearest path for which IsPrimOrPrimVariantSelectionPath() returns true.

See GetPrimPath also.

If the path is already a prim or a prim variant selection path, the same path is returned.

◆ GetPrimPath()

SDF_API SdfPath GetPrimPath ( ) const

Creates a path by stripping all relational attributes, targets, properties, and variant selections from the leafmost prim path, leaving the nearest path for which IsPrimPath() returns true.

See GetPrimOrPrimVariantSelectionPath also.

If the path is already a prim path, the same path is returned.

◆ GetString()

SDF_API const std::string & GetString ( ) const

Return the string representation of this path as a std::string.

This function returns a persistent lvalue. If an rvalue will suffice, call GetAsString() instead. That avoids populating internal data structures to hold the persistent string.

This function is recommended only for human-readable or diagnostic output. Use the SdfPath API to manipulate paths. It is less error-prone and has better performance.

◆ GetTargetPath()

SDF_API const SdfPath & GetTargetPath ( ) const

Returns the relational attribute or mapper target path for this path.

Returns EmptyPath if this is not a target, relational attribute or mapper path.

Note that it is possible for a path to have multiple "target" paths. For example a path that identifies a connection target for a relational attribute includes the target of the connection as well as the target of the relational attribute. In these cases, the "deepest" or right-most target path will be returned (the connection target in this example).

◆ GetText()

SDF_API const char * GetText ( ) const

Returns the string representation of this path as a c string.

This function returns a pointer to a persistent c string. If a temporary c string will suffice, call GetAsString().c_str() instead. That avoids populating internal data structures to hold the persistent string.

This function is recommended only for human-readable or diagnostic output. Use the SdfPath API to manipulate paths. It is less error-prone and has better performance.

◆ GetToken()

SDF_API TfToken const & GetToken ( ) const

Return the string representation of this path as a TfToken lvalue.

This function returns a persistent lvalue. If an rvalue will suffice, call GetAsToken() instead. That avoids populating internal data structures to hold the persistent token.

This function is recommended only for human-readable or diagnostic output. Use the SdfPath API to manipulate paths. It is less error-prone and has better performance.

◆ GetVariantSelection()

SDF_API std::pair< std::string, std::string > GetVariantSelection ( ) const

Returns the variant selection for this path, if this is a variant selection path.

Returns a pair of empty strings if this path is not a variant selection path.

◆ HasPrefix()

SDF_API bool HasPrefix ( const SdfPath prefix) const

Return true if both this path and prefix are not the empty path and this path has prefix as a prefix.

Return false otherwise.

◆ IsAbsolutePath()

SDF_API bool IsAbsolutePath ( ) const

Returns whether the path is absolute.

◆ IsAbsoluteRootOrPrimPath()

SDF_API bool IsAbsoluteRootOrPrimPath ( ) const

Returns whether the path identifies a prim or the absolute root.

◆ IsAbsoluteRootPath()

SDF_API bool IsAbsoluteRootPath ( ) const

Return true if this path is the AbsoluteRootPath().

◆ IsEmpty()

bool IsEmpty ( ) const
inlinenoexcept

Returns true if this is the empty path (SdfPath::EmptyPath()).

Definition at line 398 of file path.h.

◆ IsExpressionPath()

SDF_API bool IsExpressionPath ( ) const

Returns whether the path identifies a connection expression.

◆ IsMapperArgPath()

SDF_API bool IsMapperArgPath ( ) const

Returns whether the path identifies a connection mapper arg.

◆ IsMapperPath()

SDF_API bool IsMapperPath ( ) const

Returns whether the path identifies a connection mapper.

◆ IsNamespacedPropertyPath()

SDF_API bool IsNamespacedPropertyPath ( ) const

Returns whether the path identifies a namespaced property.

A namespaced property has colon embedded in its name.

◆ IsPrimOrPrimVariantSelectionPath()

SDF_API bool IsPrimOrPrimVariantSelectionPath ( ) const

Return true if this path is a prim path or is a prim variant selection path.

◆ IsPrimPath()

SDF_API bool IsPrimPath ( ) const

Returns whether the path identifies a prim.

◆ IsPrimPropertyPath()

SDF_API bool IsPrimPropertyPath ( ) const

Returns whether the path identifies a prim's property.

A relational attribute is not a prim property.

◆ IsPrimVariantSelectionPath()

SDF_API bool IsPrimVariantSelectionPath ( ) const

Returns whether the path identifies a variant selection for a prim.

◆ IsPropertyPath()

SDF_API bool IsPropertyPath ( ) const

Returns whether the path identifies a property.

A relational attribute is considered to be a property, so this method will return true for relational attributes as well as properties of prims.

◆ IsRelationalAttributePath()

SDF_API bool IsRelationalAttributePath ( ) const

Returns whether the path identifies a relational attribute.

If this is true, IsPropertyPath() will also be true.

◆ IsRootPrimPath()

SDF_API bool IsRootPrimPath ( ) const

Returns whether the path identifies a root prim.

the path must be absolute and have a single element (for example /foo).

◆ IsTargetPath()

SDF_API bool IsTargetPath ( ) const

Returns whether the path identifies a relationship or connection target.

◆ IsValidIdentifier()

static SDF_API bool IsValidIdentifier ( const std::string &  name)
static

Returns whether name is a legal identifier for any path component.

◆ IsValidNamespacedIdentifier()

static SDF_API bool IsValidNamespacedIdentifier ( const std::string &  name)
static

Returns whether name is a legal namespaced identifier.

This returns true if IsValidIdentifier() does.

◆ IsValidPathString()

static SDF_API bool IsValidPathString ( const std::string &  pathString,
std::string *  errMsg = 0 
)
static

Return true if pathString is a valid path string, meaning that passing the string to the SdfPath constructor will result in a valid, non-empty SdfPath.

Otherwise, return false and if errMsg is not NULL, set the pointed-to string to the parse error.

◆ JoinIdentifier() [1/4]

static SDF_API std::string JoinIdentifier ( const std::string &  lhs,
const std::string &  rhs 
)
static

Join lhs and rhs into a single identifier using the namespace delimiter.

Returns lhs if rhs is empty and vice verse. Returns an empty string if both lhs and rhs are empty.

◆ JoinIdentifier() [2/4]

static SDF_API std::string JoinIdentifier ( const std::vector< std::string > &  names)
static

Join names into a single identifier using the namespace delimiter.

Any empty strings present in names are ignored when joining.

◆ JoinIdentifier() [3/4]

static SDF_API std::string JoinIdentifier ( const TfToken lhs,
const TfToken rhs 
)
static

Join lhs and rhs into a single identifier using the namespace delimiter.

Returns lhs if rhs is empty and vice verse. Returns an empty string if both lhs and rhs are empty.

◆ JoinIdentifier() [4/4]

static SDF_API std::string JoinIdentifier ( const TfTokenVector names)
static

Join names into a single identifier using the namespace delimiter.

Any empty strings present in names are ignored when joining.

◆ MakeAbsolutePath()

SDF_API SdfPath MakeAbsolutePath ( const SdfPath anchor) const

Returns the absolute form of this path using anchor as the relative basis.

anchor must be an absolute prim path.

If this path is a relative path, resolve it using anchor as the relative basis.

If this path is already an absolute path, just return a copy.

◆ MakeRelativePath()

SDF_API SdfPath MakeRelativePath ( const SdfPath anchor) const

Returns the relative form of this path using anchor as the relative basis.

anchor must be an absolute prim path.

If this path is an absolute path, return the corresponding relative path that is relative to the absolute path given by anchor.

If this path is a relative path, return the optimal relative path to the absolute path given by anchor. (The optimal relative path from a given prim path is the relative path with the least leading dot-dots.

◆ operator!=()

bool operator!= ( const SdfPath rhs) const
inline

Inequality operator.

Definition at line 902 of file path.h.

◆ operator<()

bool operator< ( const SdfPath rhs) const
inline

Comparison operator.

This orders paths lexicographically, aka dictionary-style.

Definition at line 910 of file path.h.

◆ operator<=()

bool operator<= ( const SdfPath rhs) const
inline

Less than or equal operator.

See also
SdfPath::operator<(const SdfPath&)

Definition at line 929 of file path.h.

◆ operator==()

bool operator== ( const SdfPath rhs) const
inline

Equality operator.

Definition at line 897 of file path.h.

◆ operator>()

bool operator> ( const SdfPath rhs) const
inline

Greater than operator.

See also
SdfPath::operator<(const SdfPath&)

Definition at line 923 of file path.h.

◆ operator>=()

bool operator>= ( const SdfPath rhs) const
inline

Greater than or equal operator.

See also
SdfPath::operator<(const SdfPath&)

Definition at line 935 of file path.h.

◆ ReflexiveRelativePath()

static SDF_API const SdfPath & ReflexiveRelativePath ( )
static

The relative path representing "self".

◆ RemoveAncestorPaths()

static SDF_API void RemoveAncestorPaths ( SdfPathVector *  paths)
static

Remove all elements of paths that prefix other elements in paths.

As a side-effect, the result is left in sorted order.

◆ RemoveCommonSuffix()

SDF_API std::pair< SdfPath, SdfPath > RemoveCommonSuffix ( const SdfPath otherPath,
bool  stopAtRootPrim = false 
) const

Find and remove the longest common suffix from two paths.

Returns this path and otherPath with the longest common suffix removed (first and second, respectively). If the two paths have no common suffix then the paths are returned as-is. If the paths are equal then this returns empty paths for relative paths and absolute roots for absolute paths. The paths need not be the same length.

If stopAtRootPrim is true then neither returned path will be the root path. That, in turn, means that some common suffixes will not be removed. For example, if stopAtRootPrim is true then the paths /A/B and /B will be returned as is. Were it false then the result would be /A and /. Similarly paths /A/B/C and /B/C would return /A/B and /B if stopAtRootPrim is true but /A and / if it's false.

◆ RemoveDescendentPaths()

static SDF_API void RemoveDescendentPaths ( SdfPathVector *  paths)
static

Remove all elements of paths that are prefixed by other elements in paths.

As a side-effect, the result is left in sorted order.

◆ ReplaceName()

SDF_API SdfPath ReplaceName ( TfToken const &  newName) const

Return a copy of this path with its final component changed to newName.

This path must be a prim or property path.

This method is shorthand for path.GetParentPath().AppendChild(newName) for prim paths, path.GetParentPath().AppendProperty(newName) for prim property paths, and path.GetParentPath().AppendRelationalAttribute(newName) for relational attribute paths.

Note that only the final path component is ever changed. If the name of the final path component appears elsewhere in the path, it will not be modified.

Some examples:

ReplaceName('/chars/MeridaGroup', 'AngusGroup') -> '/chars/AngusGroup' ReplaceName('/Merida.tx', 'ty') -> '/Merida.ty' ReplaceName('/Merida.tx[targ].tx', 'ty') -> '/Merida.tx[targ].ty'

◆ ReplacePrefix()

SDF_API SdfPath ReplacePrefix ( const SdfPath oldPrefix,
const SdfPath newPrefix,
bool  fixTargetPaths = true 
) const

Returns a path with all occurrences of the prefix path oldPrefix replaced with the prefix path newPrefix.

If fixTargetPaths is true, any embedded target paths will also have their paths replaced. This is the default.

If this is not a target, relational attribute or mapper path this will do zero or one path prefix replacements, if not the number of replacements can be greater than one.

◆ ReplaceTargetPath()

SDF_API SdfPath ReplaceTargetPath ( const SdfPath newTargetPath) const

Replaces the relational attribute's target path.

The path must be a relational attribute path.

◆ StripAllVariantSelections()

SDF_API SdfPath StripAllVariantSelections ( ) const

Create a path by stripping all variant selections from all components of this path, leaving a path with no embedded variant selections.

◆ StripNamespace() [1/2]

static SDF_API std::string StripNamespace ( const std::string &  name)
static

Returns name stripped of any namespaces.

This does not check the validity of the name; it just attempts to remove anything that looks like a namespace.

◆ StripNamespace() [2/2]

static SDF_API TfToken StripNamespace ( const TfToken name)
static

Returns name stripped of any namespaces.

This does not check the validity of the name; it just attempts to remove anything that looks like a namespace.

◆ StripPrefixNamespace()

static SDF_API std::pair< std::string, bool > StripPrefixNamespace ( const std::string &  name,
const std::string &  matchNamespace 
)
static

Returns (name, true) where name is stripped of the prefix specified by matchNamespace if name indeed starts with matchNamespace.

Returns (name, false) otherwise, with name unmodified.

This function deals with both the case where matchNamespace contains the trailing namespace delimiter ':' or not.

◆ TokenizeIdentifier()

static SDF_API std::vector< std::string > TokenizeIdentifier ( const std::string &  name)
static

Tokenizes name by the namespace delimiter.

Returns the empty vector if name is not a valid namespaced identifier.

◆ TokenizeIdentifierAsTokens()

static SDF_API TfTokenVector TokenizeIdentifierAsTokens ( const std::string &  name)
static

Tokenizes name by the namespace delimiter.

Returns the empty vector if name is not a valid namespaced identifier.

Friends And Related Function Documentation

◆ Sdfext_PathAccess

friend class Sdfext_PathAccess
friend

Definition at line 1022 of file path.h.

◆ SdfPathAncestorsRange

friend class SdfPathAncestorsRange
friend

Definition at line 1023 of file path.h.

◆ swap

void swap ( SdfPath lhs,
SdfPath rhs 
)
friend

Definition at line 1046 of file path.h.

◆ TfHashAppend

void TfHashAppend ( HashState &  h,
SdfPath const &  path 
)
friend

Definition at line 940 of file path.h.


The documentation for this class was generated from the following file: