|
HDK
|
#include <path.h>
Classes | |
| struct | FastLessThan |
| struct | Hash |
Friends | |
| class | Sdf_PathNode |
| class | Sdfext_PathAccess |
| class | SdfPathAncestorsRange |
| void | swap (SdfPath &lhs, SdfPath &rhs) |
| SDF_API friend char const * | Sdf_PathGetDebuggerPathText (SdfPath const &) |
Operators | |
| template<class HashState > | |
| void | TfHashAppend (HashState &h, SdfPath const &path) |
| Equality operator. More... | |
| bool | operator== (const SdfPath &rhs) const |
| Equality operator. More... | |
| bool | operator!= (const SdfPath &rhs) const |
| Inequality operator. More... | |
| bool | operator< (const SdfPath &rhs) const |
| bool | operator> (const SdfPath &rhs) const |
| bool | operator<= (const SdfPath &rhs) const |
| bool | operator>= (const SdfPath &rhs) const |
| size_t | GetHash () const |
| Equality operator. More... | |
A path value used to locate objects in layers or scenegraphs.
SdfPath is used in several ways:
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.
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.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).
|
defaultnoexcept |
Constructs the default, empty 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.
The absolute path representing the top of the namespace hierarchy.
Creates a path by appending an element for childName to this path.
This path must be a prim path, the AbsoluteRootPath or the ReflexiveRelativePath.
| SDF_API SdfPath 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.
Like AppendElementString() but take the element as a TfToken.
Creates a path by appending an expression element.
This path must be a prim property or relational attribute path.
Creates a path by appending a mapper element for targetPath.
This path must be a prim property or relational attribute path.
Creates a path by appending an element for argName.
This path must be a mapper path.
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.
Creates a path by appending an element for propName to this path.
This path must be a prim path or the ReflexiveRelativePath.
Creates a path by appending an element for attrName to this path.
This path must be a target path.
Creates a path by appending an element for targetPath.
This path must be a prim property or relational attribute path.
| SDF_API SdfPath 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.
| SDF_API bool SdfPath::ContainsPrimVariantSelection | ( | ) | const |
Returns whether the path or any of its parent paths identifies a variant selection for a prim.
|
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.
| SDF_API bool SdfPath::ContainsTargetPath | ( | ) | const |
Return true if this path is or has a prefix that's a target path or a mapper path.
The empty path value, equivalent to SdfPath().
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.
| SDF_API void SdfPath::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'
| SDF_API SdfPathAncestorsRange SdfPath::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).
| SDF_API std::string SdfPath::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.
Returns a path with maximal length that is a prefix path of both this path and path.
|
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.
| SDF_API std::string SdfPath::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.
Like GetElementString() but return the value as a TfToken.
| SDF_API const std::string& SdfPath::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 the name of the prim, property or relational attribute identified by the path, as a token.
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().
| SDF_API size_t SdfPath::GetPathElementCount | ( | ) | const |
Returns the number of path elements in this path.
| SDF_API SdfPathVector SdfPath::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.
| SDF_API SdfPathVector SdfPath::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.
| SDF_API void SdfPath::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.
| SDF_API void SdfPath::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.
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.
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.
| SDF_API const std::string& SdfPath::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.
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).
| SDF_API const char* SdfPath::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.
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.
| SDF_API std::pair<std::string, std::string> SdfPath::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.
Return true if both this path and prefix are not the empty path and this path has prefix as a prefix. Return false otherwise.
| SDF_API bool SdfPath::IsAbsolutePath | ( | ) | const |
Returns whether the path is absolute.
| SDF_API bool SdfPath::IsAbsoluteRootOrPrimPath | ( | ) | const |
Returns whether the path identifies a prim or the absolute root.
| SDF_API bool SdfPath::IsAbsoluteRootPath | ( | ) | const |
Return true if this path is the AbsoluteRootPath().
|
inlinenoexcept |
Returns true if this is the empty path (SdfPath::EmptyPath()).
| SDF_API bool SdfPath::IsExpressionPath | ( | ) | const |
Returns whether the path identifies a connection expression.
| SDF_API bool SdfPath::IsMapperArgPath | ( | ) | const |
Returns whether the path identifies a connection mapper arg.
| SDF_API bool SdfPath::IsMapperPath | ( | ) | const |
Returns whether the path identifies a connection mapper.
| SDF_API bool SdfPath::IsNamespacedPropertyPath | ( | ) | const |
Returns whether the path identifies a namespaced property.
A namespaced property has colon embedded in its name.
| SDF_API bool SdfPath::IsPrimOrPrimVariantSelectionPath | ( | ) | const |
Return true if this path is a prim path or is a prim variant selection path.
| SDF_API bool SdfPath::IsPrimPath | ( | ) | const |
Returns whether the path identifies a prim.
| SDF_API bool SdfPath::IsPrimPropertyPath | ( | ) | const |
Returns whether the path identifies a prim's property.
A relational attribute is not a prim property.
| SDF_API bool SdfPath::IsPrimVariantSelectionPath | ( | ) | const |
Returns whether the path identifies a variant selection for a prim.
| SDF_API bool SdfPath::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.
| SDF_API bool SdfPath::IsRelationalAttributePath | ( | ) | const |
Returns whether the path identifies a relational attribute.
If this is true, IsPropertyPath() will also be true.
| SDF_API bool SdfPath::IsRootPrimPath | ( | ) | const |
Returns whether the path identifies a root prim.
the path must be absolute and have a single element (for example /foo).
| SDF_API bool SdfPath::IsTargetPath | ( | ) | const |
Returns whether the path identifies a relationship or connection target.
|
static |
Returns whether name is a legal identifier for any path component.
|
static |
Returns whether name is a legal namespaced identifier. This returns true if IsValidIdentifier() does.
|
static |
|
static |
Join names into a single identifier using the namespace delimiter. Any empty strings present in names are ignored when joining.
|
static |
Join names into a single identifier using the namespace delimiter. Any empty strings present in names are ignored when joining.
|
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.
|
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.
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.
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.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
The relative path representing "self".
|
static |
Remove all elements of paths that prefix other elements in paths. As a side-effect, the result is left in sorted order.
| SDF_API std::pair<SdfPath, 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.
|
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.
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'
| SDF_API SdfPath 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.
Replaces the relational attribute's target path
The path must be a relational attribute path.
Create a path by stripping all variant selections from all components of this path, leaving a path with no embedded variant selections.
|
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.
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.
|
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.
|
static |
Tokenizes name by the namespace delimiter. Returns the empty vector if name is not a valid namespaced identifier.
|
static |
Tokenizes name by the namespace delimiter. Returns the empty vector if name is not a valid namespaced identifier.
|
friend |
|
friend |
1.8.6