HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
path.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_SDF_PATH_H
25 #define PXR_USD_SDF_PATH_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/sdf/api.h"
29 #include "pxr/usd/sdf/pool.h"
30 #include "pxr/usd/sdf/tokens.h"
31 #include "pxr/base/tf/stl.h"
32 #include "pxr/base/tf/token.h"
33 #include "pxr/base/vt/traits.h"
34 
35 #include <hboost/intrusive_ptr.hpp>
36 #include <hboost/operators.hpp>
37 
38 #include <algorithm>
39 #include <iterator>
40 #include <set>
41 #include <string>
42 #include <type_traits>
43 #include <utility>
44 #include <vector>
45 
47 
48 class Sdf_PathNode;
50 
51 // Ref-counting pointer to a path node.
52 // Intrusive ref-counts are used to keep the size of SdfPath
53 // the same as a raw pointer. (shared_ptr, by comparison,
54 // is the size of two pointers.)
55 
56 typedef hboost::intrusive_ptr<const Sdf_PathNode> Sdf_PathNodeConstRefPtr;
57 
60 
61 // Tags used for the pools of path nodes.
62 struct Sdf_PathPrimTag;
63 struct Sdf_PathPropTag;
64 
65 // These are validated below.
66 static constexpr size_t Sdf_SizeofPrimPathNode = sizeof(void *) * 3;
67 static constexpr size_t Sdf_SizeofPropPathNode = sizeof(void *) * 3;
68 
70  Sdf_PathPrimTag, Sdf_SizeofPrimPathNode, /*regionBits=*/8>;
71 
73  Sdf_PathPropTag, Sdf_SizeofPropPathNode, /*regionBits=*/8>;
74 
77 
78 // This handle class wraps up the raw Prim/PropPartPool handles.
79 template <class Handle, bool Counted, class PathNode=Sdf_PathNode const>
81 private:
83 
84 public:
85  static constexpr bool IsCounted = Counted;
86 
87  constexpr Sdf_PathNodeHandleImpl() noexcept {};
88 
89  explicit
90  Sdf_PathNodeHandleImpl(Sdf_PathNode const *p, bool add_ref = true)
91  : _poolHandle(Handle::GetHandle(reinterpret_cast<char const *>(p))) {
92  if (p && add_ref) {
93  _AddRef(p);
94  }
95  }
96 
97  explicit
98  Sdf_PathNodeHandleImpl(Handle h, bool add_ref = true)
99  : _poolHandle(h) {
100  if (h && add_ref) {
101  _AddRef();
102  }
103  }
104 
106  : _poolHandle(rhs._poolHandle) {
107  if (_poolHandle) {
108  _AddRef();
109  }
110  }
111 
113  if (_poolHandle) {
114  _DecRef();
115  }
116  }
117 
120  if (Counted && *this == rhs) {
121  return *this;
122  }
123  this_type(rhs).swap(*this);
124  return *this;
125  }
126 
128  : _poolHandle(rhs._poolHandle) {
129  rhs._poolHandle = nullptr;
130  }
131 
134  this_type(std::move(rhs)).swap(*this);
135  return *this;
136  }
137 
139  operator=(Sdf_PathNode const *rhs) noexcept {
140  this_type(rhs).swap(*this);
141  return *this;
142  }
143 
144  void reset() noexcept {
145  _poolHandle = Handle { nullptr };
146  }
147 
148  Sdf_PathNode const *
149  get() const noexcept {
150  return reinterpret_cast<Sdf_PathNode *>(_poolHandle.GetPtr());
151  }
152 
153  Sdf_PathNode const &
154  operator*() const {
155  return *get();
156  }
157 
158  Sdf_PathNode const *
159  operator->() const {
160  return get();
161  }
162 
163  explicit operator bool() const noexcept {
164  return static_cast<bool>(_poolHandle);
165  }
166 
167  void swap(Sdf_PathNodeHandleImpl &rhs) noexcept {
168  _poolHandle.swap(rhs._poolHandle);
169  }
170 
171  inline bool operator==(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
172  return _poolHandle == rhs._poolHandle;
173  }
174  inline bool operator!=(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
175  return _poolHandle != rhs._poolHandle;
176  }
177  inline bool operator<(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
178  return _poolHandle < rhs._poolHandle;
179  }
180 private:
181 
182  void _AddRef(Sdf_PathNode const *p) const {
183  if (Counted) {
185  }
186  }
187 
188  void _AddRef() const {
189  _AddRef(get());
190  }
191 
192  void _DecRef() const {
193  if (Counted) {
194  intrusive_ptr_release(get());
195  }
196  }
197 
198  Handle _poolHandle { nullptr };
199 };
200 
203 
206 
207 
208 /// A set of SdfPaths.
209 typedef std::set<class SdfPath> SdfPathSet;
210 /// A vector of SdfPaths.
211 typedef std::vector<class SdfPath> SdfPathVector;
212 
213 // Tell VtValue that SdfPath is cheap to copy.
215 
216 /// \class SdfPath
217 ///
218 /// A path value used to locate objects in layers or scenegraphs.
219 ///
220 /// \section sec_SdfPath_Overview Overview
221 ///
222 /// SdfPath is used in several ways:
223 /// \li As a storage key for addressing and accessing values held in a SdfLayer
224 /// \li As a namespace identity for scenegraph objects
225 /// \li As a way to refer to other scenegraph objects through relative paths
226 ///
227 /// The paths represented by an SdfPath class may be either relative or
228 /// absolute. Relative paths are relative to the prim object that contains them
229 /// (that is, if an SdfRelationshipSpec target is relative, it is relative to
230 /// the SdfPrimSpec object that owns the SdfRelationshipSpec object).
231 ///
232 /// SdfPath objects can be readily created from and converted back to strings,
233 /// but as SdfPath objects, they have behaviors that make it easy and efficient
234 /// to work with them. The SdfPath class provides a full range of methods for
235 /// manipulating scene paths by appending a namespace child, appending a
236 /// relationship target, getting the parent path,
237 /// and so on. Since the SdfPath class uses a node-based representation
238 /// internally, you should use the editing functions rather than converting to
239 /// and from strings if possible.
240 ///
241 /// \section sec_SdfPath_Syntax Path Syntax
242 ///
243 /// Like a filesystem path, an SdfPath is conceptually just a sequence of
244 /// path components. Unlike a filesystem path, each component has a type,
245 /// and the type is indicated by the syntax.
246 ///
247 /// Two separators are used between parts of a path. A slash ("/") following an
248 /// identifier is used to introduce a namespace child. A period (".") following
249 /// an identifier is used to introduce a property. A property may also have
250 /// several non-sequential colons (':') in its name to provide a rudimentary
251 /// namespace within properties but may not end or begin with a colon.
252 ///
253 /// A leading slash in the string representation of an SdfPath object indicates
254 /// an absolute path. Two adjacent periods indicate the parent namespace.
255 ///
256 /// Brackets ("[" and "]") are used to indicate relationship target paths for
257 /// relational attributes.
258 ///
259 /// The first part in a path is assumed to be a namespace child unless
260 /// it is preceded by a period. That means:
261 /// \li <c>/Foo</c> is an absolute path specifying the root prim Foo.
262 /// \li <c>/Foo/Bar</c> is an absolute path specifying namespace child Bar
263 /// of root prim Foo.
264 /// \li <c>/Foo/Bar.baz</c> is an absolute path specifying property \c baz of
265 /// namespace child Bar of root prim Foo.
266 /// \li <c>Foo</c> is a relative path specifying namespace child Foo of
267 /// the current prim.
268 /// \li <c>Foo/Bar</c> is a relative path specifying namespace child Bar of
269 /// namespace child Foo of the current prim.
270 /// \li <c>Foo/Bar.baz</c> is a relative path specifying property \c baz of
271 /// namespace child Bar of namespace child Foo of the current prim.
272 /// \li <c>.foo</c> is a relative path specifying the property \c foo of the
273 /// current prim.
274 /// \li <c>/Foo.bar[/Foo.baz].attrib</c> is a relational attribute path. The
275 /// relationship <c>/Foo.bar</c> has a target <c>/Foo.baz</c>. There is a
276 /// relational attribute \c attrib on that relationship-&gt;target pair.
277 ///
278 /// \section sec_SdfPath_ThreadSafety A Note on Thread-Safety
279 ///
280 /// SdfPath is strongly thread-safe, in the sense that zero additional
281 /// synchronization is required between threads creating or using SdfPath
282 /// values. Just like TfToken, SdfPath values are immutable. Internally,
283 /// SdfPath uses a global prefix tree to efficiently share representations
284 /// of paths, and provide fast equality/hashing operations, but
285 /// modifications to this table are internally synchronized. Consequently,
286 /// as with TfToken, for best performance it is important to minimize
287 /// the number of values created (since it requires synchronized access to
288 /// this table) or copied (since it requires atomic ref-counting operations).
289 ///
290 class SdfPath : hboost::totally_ordered<SdfPath>
291 {
292 public:
293  /// The empty path value, equivalent to SdfPath().
294  SDF_API static const SdfPath & EmptyPath();
295 
296  /// The absolute path representing the top of the
297  /// namespace hierarchy.
298  SDF_API static const SdfPath & AbsoluteRootPath();
299 
300  /// The relative path representing "self".
301  SDF_API static const SdfPath & ReflexiveRelativePath();
302 
303  /// \name Constructors
304  /// @{
305 
306  /// Constructs the default, empty path.
307  ///
308  SdfPath() noexcept {
309  // This generates a single instruction instead of 2 on gcc 6.3. Seems
310  // to be fixed on gcc 7+ and newer clangs. Remove when we're there!
311  memset(this, 0, sizeof(*this));
312  }
313 
314  /// Creates a path from the given string.
315  ///
316  /// If the given string is not a well-formed path, this will raise
317  /// a Tf error. Note that passing an empty std::string() will also
318  /// raise an error; the correct way to get the empty path is SdfPath().
319  ///
320  /// Internal dot-dots will be resolved by removing the first dot-dot,
321  /// the element preceding it, and repeating until no internal dot-dots
322  /// remain.
323  ///
324  /// Note that most often new paths are expected to be created by
325  /// asking existing paths to return modified versions of themselves.
326  //
327  // XXX We may want to revisit the behavior when constructing
328  // a path with an empty string ("") to accept it without error and
329  // return EmptyPath.
330  SDF_API explicit SdfPath(const std::string &path);
331 
332  /// @}
333 
334  /// \name Querying paths
335  /// @{
336 
337  /// Returns the number of path elements in this path.
338  SDF_API size_t GetPathElementCount() const;
339 
340  /// Returns whether the path is absolute.
341  SDF_API bool IsAbsolutePath() const;
342 
343  /// Return true if this path is the AbsoluteRootPath().
344  SDF_API bool IsAbsoluteRootPath() const;
345 
346  /// Returns whether the path identifies a prim.
347  SDF_API bool IsPrimPath() const;
348 
349  /// Returns whether the path identifies a prim or the absolute root.
350  SDF_API bool IsAbsoluteRootOrPrimPath() const;
351 
352  /// Returns whether the path identifies a root prim.
353  ///
354  /// the path must be absolute and have a single element
355  /// (for example <c>/foo</c>).
356  SDF_API bool IsRootPrimPath() const;
357 
358  /// Returns whether the path identifies a property.
359  ///
360  /// A relational attribute is considered to be a property, so this
361  /// method will return true for relational attributes as well
362  /// as properties of prims.
363  SDF_API bool IsPropertyPath() const;
364 
365  /// Returns whether the path identifies a prim's property.
366  ///
367  /// A relational attribute is not a prim property.
368  SDF_API bool IsPrimPropertyPath() const;
369 
370  /// Returns whether the path identifies a namespaced property.
371  ///
372  /// A namespaced property has colon embedded in its name.
373  SDF_API bool IsNamespacedPropertyPath() const;
374 
375  /// Returns whether the path identifies a variant selection for a
376  /// prim.
377  SDF_API bool IsPrimVariantSelectionPath() const;
378 
379  /// Return true if this path is a prim path or is a prim variant
380  /// selection path.
382 
383  /// Returns whether the path or any of its parent paths identifies
384  /// a variant selection for a prim.
386 
387  /// Return true if this path contains any property elements, false
388  /// otherwise. A false return indicates a prim-like path, specifically a
389  /// root path, a prim path, or a prim variant selection path. A true return
390  /// indicates a property-like path: a prim property path, a target path, a
391  /// relational attribute path, etc.
393  return static_cast<bool>(_propPart);
394  }
395 
396  /// Return true if this path is or has a prefix that's a target path or a
397  /// mapper path.
398  SDF_API bool ContainsTargetPath() const;
399 
400  /// Returns whether the path identifies a relational attribute.
401  ///
402  /// If this is true, IsPropertyPath() will also be true.
403  SDF_API bool IsRelationalAttributePath() const;
404 
405  /// Returns whether the path identifies a relationship or
406  /// connection target.
407  SDF_API bool IsTargetPath() const;
408 
409  /// Returns whether the path identifies a connection mapper.
410  SDF_API bool IsMapperPath() const;
411 
412  /// Returns whether the path identifies a connection mapper arg.
413  SDF_API bool IsMapperArgPath() const;
414 
415  /// Returns whether the path identifies a connection expression.
416  SDF_API bool IsExpressionPath() const;
417 
418  /// Returns true if this is the empty path (SdfPath::EmptyPath()).
419  inline bool IsEmpty() const noexcept {
420  // No need to check _propPart, because it can only be non-null if
421  // _primPart is non-null.
422  return !_primPart;
423  }
424 
425  /// Return the string representation of this path as a TfToken.
426  ///
427  /// This function is recommended only for human-readable or diagnostic
428  /// output. Use the SdfPath API to manipulate paths. It is less
429  /// error-prone and has better performance.
430  SDF_API TfToken GetAsToken() const;
431 
432  /// Return the string representation of this path as a TfToken lvalue.
433  ///
434  /// This function returns a persistent lvalue. If an rvalue will suffice,
435  /// call GetAsToken() instead. That avoids populating internal data
436  /// structures to hold the persistent token.
437  ///
438  /// This function is recommended only for human-readable or diagnostic
439  /// output. Use the SdfPath API to manipulate paths. It is less
440  /// error-prone and has better performance.
441  SDF_API TfToken const &GetToken() const;
442 
443  /// Return the string representation of this path as a std::string.
444  ///
445  /// This function is recommended only for human-readable or diagnostic
446  /// output. Use the SdfPath API to manipulate paths. It is less
447  /// error-prone and has better performance.
449 
450  /// Return the string representation of this path as a std::string.
451  ///
452  /// This function returns a persistent lvalue. If an rvalue will suffice,
453  /// call GetAsString() instead. That avoids populating internal data
454  /// structures to hold the persistent string.
455  ///
456  /// This function is recommended only for human-readable or diagnostic
457  /// output. Use the SdfPath API to manipulate paths. It is less
458  /// error-prone and has better performance.
459  SDF_API const std::string &GetString() const;
460 
461  /// Returns the string representation of this path as a c string.
462  ///
463  /// This function returns a pointer to a persistent c string. If a
464  /// temporary c string will suffice, call GetAsString().c_str() instead.
465  /// That avoids populating internal data structures to hold the persistent
466  /// string.
467  ///
468  /// This function is recommended only for human-readable or diagnostic
469  /// output. Use the SdfPath API to manipulate paths. It is less
470  /// error-prone and has better performance.
471  SDF_API const char *GetText() const;
472 
473  /// Returns the prefix paths of this path.
474  ///
475  /// Prefixes are returned in order of shortest to longest. The path
476  /// itself is returned as the last prefix.
477  /// Note that if the prefix order does not need to be from shortest to
478  /// longest, it is more efficient to use GetAncestorsRange, which
479  /// produces an equivalent set of paths, ordered from longest to shortest.
480  SDF_API SdfPathVector GetPrefixes() const;
481 
482  /// Fills prefixes with prefixes of this path.
483  ///
484  /// This avoids copy constructing the return value.
485  ///
486  /// Prefixes are returned in order of shortest to longest. The path
487  /// itself is returned as the last prefix.
488  /// Note that if the prefix order does not need to be from shortest to
489  /// longest, it is more efficient to use GetAncestorsRange, which
490  /// produces an equivalent set of paths, ordered from longest to shortest.
491  SDF_API void GetPrefixes(SdfPathVector *prefixes) const;
492 
493  /// Return a range for iterating over the ancestors of this path.
494  ///
495  /// The range provides iteration over the prefixes of a path, ordered
496  /// from longest to shortest (the opposite of the order of the prefixes
497  /// returned by GetPrefixes).
499 
500  /// Returns the name of the prim, property or relational
501  /// attribute identified by the path.
502  ///
503  /// Returns EmptyPath if this path is a target or mapper path.
504  ///
505  /// <ul>
506  /// <li>Returns "" for EmptyPath.</li>
507  /// <li>Returns "." for ReflexiveRelativePath.</li>
508  /// <li>Returns ".." for a path ending in ParentPathElement.</li>
509  /// </ul>
510  SDF_API const std::string &GetName() const;
511 
512  /// Returns the name of the prim, property or relational
513  /// attribute identified by the path, as a token.
514  SDF_API const TfToken &GetNameToken() const;
515 
516  /// Returns an ascii representation of the "terminal" element
517  /// of this path, which can be used to reconstruct the path using
518  /// \c AppendElementString() on its parent.
519  ///
520  /// EmptyPath(), AbsoluteRootPath(), and ReflexiveRelativePath() are
521  /// \em not considered elements (one of the defining properties of
522  /// elements is that they have a parent), so \c GetElementString() will
523  /// return the empty string for these paths.
524  ///
525  /// Unlike \c GetName() and \c GetTargetPath(), which provide you "some"
526  /// information about the terminal element, this provides a complete
527  /// representation of the element, for all element types.
528  ///
529  /// Also note that whereas \c GetName(), \c GetNameToken(), \c GetText(),
530  /// \c GetString(), and \c GetTargetPath() return cached results,
531  /// \c GetElementString() always performs some amount of string
532  /// manipulation, which you should keep in mind if performance is a concern.
534 
535  /// Like GetElementString() but return the value as a TfToken.
537 
538  /// Return a copy of this path with its final component changed to
539  /// \a newName. This path must be a prim or property path.
540  ///
541  /// This method is shorthand for path.GetParentPath().AppendChild(newName)
542  /// for prim paths, path.GetParentPath().AppendProperty(newName) for
543  /// prim property paths, and
544  /// path.GetParentPath().AppendRelationalAttribute(newName) for relational
545  /// attribute paths.
546  ///
547  /// Note that only the final path component is ever changed. If the name of
548  /// the final path component appears elsewhere in the path, it will not be
549  /// modified.
550  ///
551  /// Some examples:
552  ///
553  /// ReplaceName('/chars/MeridaGroup', 'AngusGroup') -> '/chars/AngusGroup'
554  /// ReplaceName('/Merida.tx', 'ty') -> '/Merida.ty'
555  /// ReplaceName('/Merida.tx[targ].tx', 'ty') -> '/Merida.tx[targ].ty'
556  ///
557  SDF_API SdfPath ReplaceName(TfToken const &newName) const;
558 
559  /// Returns the relational attribute or mapper target path
560  /// for this path.
561  ///
562  /// Returns EmptyPath if this is not a target, relational attribute or
563  /// mapper path.
564  ///
565  /// Note that it is possible for a path to have multiple "target" paths.
566  /// For example a path that identifies a connection target for a
567  /// relational attribute includes the target of the connection as well
568  /// as the target of the relational attribute. In these cases, the
569  /// "deepest" or right-most target path will be returned (the connection
570  /// target in this example).
571  SDF_API const SdfPath &GetTargetPath() const;
572 
573  /// Returns all the relationship target or connection target
574  /// paths contained in this path, and recursively all the target paths
575  /// contained in those target paths in reverse depth-first order.
576  ///
577  /// For example, given the path: '/A/B.a[/C/D.a[/E/F.a]].a[/A/B.a[/C/D.a]]'
578  /// this method produces: '/A/B.a[/C/D.a]', '/C/D.a', '/C/D.a[/E/F.a]',
579  /// '/E/F.a'
580  SDF_API void GetAllTargetPathsRecursively(SdfPathVector *result) const;
581 
582  /// Returns the variant selection for this path, if this is a variant
583  /// selection path.
584  /// Returns a pair of empty strings if this path is not a variant
585  /// selection path.
586  SDF_API
587  std::pair<std::string, std::string> GetVariantSelection() const;
588 
589  /// Return true if both this path and \a prefix are not the empty
590  /// path and this path has \a prefix as a prefix. Return false otherwise.
591  SDF_API bool HasPrefix( const SdfPath &prefix ) const;
592 
593  /// @}
594 
595  /// \name Creating new paths by modifying existing paths
596  /// @{
597 
598  /// Return the path that identifies this path's namespace parent.
599  ///
600  /// For a prim path (like '/foo/bar'), return the prim's parent's path
601  /// ('/foo'). For a prim property path (like '/foo/bar.property'), return
602  /// the prim's path ('/foo/bar'). For a target path (like
603  /// '/foo/bar.property[/target]') return the property path
604  /// ('/foo/bar.property'). For a mapper path (like
605  /// '/foo/bar.property.mapper[/target]') return the property path
606  /// ('/foo/bar.property). For a relational attribute path (like
607  /// '/foo/bar.property[/target].relAttr') return the relationship target's
608  /// path ('/foo/bar.property[/target]'). For a prim variant selection path
609  /// (like '/foo/bar{var=sel}') return the prim path ('/foo/bar'). For a
610  /// root prim path (like '/rootPrim'), return AbsoluteRootPath() ('/'). For
611  /// a single element relative prim path (like 'relativePrim'), return
612  /// ReflexiveRelativePath() ('.'). For ReflexiveRelativePath(), return the
613  /// relative parent path ('..').
614  ///
615  /// Note that the parent path of a relative parent path ('..') is a relative
616  /// grandparent path ('../..'). Use caution writing loops that walk to
617  /// parent paths since relative paths have infinitely many ancestors. To
618  /// more safely traverse ancestor paths, consider iterating over an
619  /// SdfPathAncestorsRange instead, as returend by GetAncestorsRange().
620  SDF_API SdfPath GetParentPath() const;
621 
622  /// Creates a path by stripping all relational attributes, targets,
623  /// properties, and variant selections from the leafmost prim path, leaving
624  /// the nearest path for which \a IsPrimPath() returns true.
625  ///
626  /// See \a GetPrimOrPrimVariantSelectionPath also.
627  ///
628  /// If the path is already a prim path, the same path is returned.
629  SDF_API SdfPath GetPrimPath() const;
630 
631  /// Creates a path by stripping all relational attributes, targets,
632  /// and properties, leaving the nearest path for which
633  /// \a IsPrimOrPrimVariantSelectionPath() returns true.
634  ///
635  /// See \a GetPrimPath also.
636  ///
637  /// If the path is already a prim or a prim variant selection path, the same
638  /// path is returned.
640 
641  /// Creates a path by stripping all properties and relational
642  /// attributes from this path, leaving the path to the containing prim.
643  ///
644  /// If the path is already a prim or absolute root path, the same
645  /// path is returned.
647 
648  /// Create a path by stripping all variant selections from all
649  /// components of this path, leaving a path with no embedded variant
650  /// selections.
652 
653  /// Creates a path by appending a given relative path to this path.
654  ///
655  /// If the newSuffix is a prim path, then this path must be a prim path
656  /// or a root path.
657  ///
658  /// If the newSuffix is a prim property path, then this path must be
659  /// a prim path or the ReflexiveRelativePath.
660  SDF_API SdfPath AppendPath(const SdfPath &newSuffix) const;
661 
662  /// Creates a path by appending an element for \p childName
663  /// to this path.
664  ///
665  /// This path must be a prim path, the AbsoluteRootPath
666  /// or the ReflexiveRelativePath.
667  SDF_API SdfPath AppendChild(TfToken const &childName) const;
668 
669  /// Creates a path by appending an element for \p propName
670  /// to this path.
671  ///
672  /// This path must be a prim path or the ReflexiveRelativePath.
673  SDF_API SdfPath AppendProperty(TfToken const &propName) const;
674 
675  /// Creates a path by appending an element for \p variantSet
676  /// and \p variant to this path.
677  ///
678  /// This path must be a prim path.
679  SDF_API
680  SdfPath AppendVariantSelection(const std::string &variantSet,
681  const std::string &variant) const;
682 
683  /// Creates a path by appending an element for
684  /// \p targetPath.
685  ///
686  /// This path must be a prim property or relational attribute path.
687  SDF_API SdfPath AppendTarget(const SdfPath &targetPath) const;
688 
689  /// Creates a path by appending an element for
690  /// \p attrName to this path.
691  ///
692  /// This path must be a target path.
693  SDF_API
694  SdfPath AppendRelationalAttribute(TfToken const &attrName) const;
695 
696  /// Replaces the relational attribute's target path
697  ///
698  /// The path must be a relational attribute path.
699  SDF_API
700  SdfPath ReplaceTargetPath( const SdfPath &newTargetPath ) const;
701 
702  /// Creates a path by appending a mapper element for
703  /// \p targetPath.
704  ///
705  /// This path must be a prim property or relational attribute path.
706  SDF_API SdfPath AppendMapper(const SdfPath &targetPath) const;
707 
708  /// Creates a path by appending an element for
709  /// \p argName.
710  ///
711  /// This path must be a mapper path.
712  SDF_API SdfPath AppendMapperArg(TfToken const &argName) const;
713 
714  /// Creates a path by appending an expression element.
715  ///
716  /// This path must be a prim property or relational attribute path.
718 
719  /// Creates a path by extracting and appending an element
720  /// from the given ascii element encoding.
721  ///
722  /// Attempting to append a root or empty path (or malformed path)
723  /// or attempting to append \em to the EmptyPath will raise an
724  /// error and return the EmptyPath.
725  ///
726  /// May also fail and return EmptyPath if this path's type cannot
727  /// possess a child of the type encoded in \p element.
728  SDF_API SdfPath AppendElementString(const std::string &element) const;
729 
730  /// Like AppendElementString() but take the element as a TfToken.
731  SDF_API SdfPath AppendElementToken(const TfToken &elementTok) const;
732 
733  /// Returns a path with all occurrences of the prefix path
734  /// \p oldPrefix replaced with the prefix path \p newPrefix.
735  ///
736  /// If fixTargetPaths is true, any embedded target paths will also
737  /// have their paths replaced. This is the default.
738  ///
739  /// If this is not a target, relational attribute or mapper path this
740  /// will do zero or one path prefix replacements, if not the number of
741  /// replacements can be greater than one.
742  SDF_API
743  SdfPath ReplacePrefix(const SdfPath &oldPrefix,
744  const SdfPath &newPrefix,
745  bool fixTargetPaths=true) const;
746 
747  /// Returns a path with maximal length that is a prefix path of
748  /// both this path and \p path.
750 
751  /// Find and remove the longest common suffix from two paths.
752  ///
753  /// Returns this path and \p otherPath with the longest common suffix
754  /// removed (first and second, respectively). If the two paths have no
755  /// common suffix then the paths are returned as-is. If the paths are
756  /// equal then this returns empty paths for relative paths and absolute
757  /// roots for absolute paths. The paths need not be the same length.
758  ///
759  /// If \p stopAtRootPrim is \c true then neither returned path will be
760  /// the root path. That, in turn, means that some common suffixes will
761  /// not be removed. For example, if \p stopAtRootPrim is \c true then
762  /// the paths /A/B and /B will be returned as is. Were it \c false
763  /// then the result would be /A and /. Similarly paths /A/B/C and
764  /// /B/C would return /A/B and /B if \p stopAtRootPrim is \c true but
765  /// /A and / if it's \c false.
766  SDF_API
767  std::pair<SdfPath, SdfPath>
768  RemoveCommonSuffix(const SdfPath& otherPath,
769  bool stopAtRootPrim = false) const;
770 
771  /// Returns the absolute form of this path using \p anchor
772  /// as the relative basis.
773  ///
774  /// \p anchor must be an absolute prim path.
775  ///
776  /// If this path is a relative path, resolve it using \p anchor as the
777  /// relative basis.
778  ///
779  /// If this path is already an absolute path, just return a copy.
780  SDF_API SdfPath MakeAbsolutePath(const SdfPath & anchor) const;
781 
782  /// Returns the relative form of this path using \p anchor
783  /// as the relative basis.
784  ///
785  /// \p anchor must be an absolute prim path.
786  ///
787  /// If this path is an absolute path, return the corresponding relative path
788  /// that is relative to the absolute path given by \p anchor.
789  ///
790  /// If this path is a relative path, return the optimal relative
791  /// path to the absolute path given by \p anchor. (The optimal
792  /// relative path from a given prim path is the relative path
793  /// with the least leading dot-dots.
794  SDF_API SdfPath MakeRelativePath(const SdfPath & anchor) const;
795 
796  /// @}
797 
798  /// \name Valid path strings, prim and property names
799  /// @{
800 
801  /// Returns whether \p name is a legal identifier for any
802  /// path component.
803  SDF_API static bool IsValidIdentifier(const std::string &name);
804 
805  /// Returns whether \p name is a legal namespaced identifier.
806  /// This returns \c true if IsValidIdentifier() does.
808 
809  /// Tokenizes \p name by the namespace delimiter.
810  /// Returns the empty vector if \p name is not a valid namespaced
811  /// identifier.
812  SDF_API static std::vector<std::string> TokenizeIdentifier(const std::string &name);
813 
814  /// Tokenizes \p name by the namespace delimiter.
815  /// Returns the empty vector if \p name is not a valid namespaced
816  /// identifier.
817  SDF_API
819 
820  /// Join \p names into a single identifier using the namespace delimiter.
821  /// Any empty strings present in \p names are ignored when joining.
822  SDF_API
823  static std::string JoinIdentifier(const std::vector<std::string> &names);
824 
825  /// Join \p names into a single identifier using the namespace delimiter.
826  /// Any empty strings present in \p names are ignored when joining.
827  SDF_API
829 
830  /// Join \p lhs and \p rhs into a single identifier using the
831  /// namespace delimiter.
832  /// Returns \p lhs if \p rhs is empty and vice verse.
833  /// Returns an empty string if both \p lhs and \p rhs are empty.
834  SDF_API
835  static std::string JoinIdentifier(const std::string &lhs,
836  const std::string &rhs);
837 
838  /// Join \p lhs and \p rhs into a single identifier using the
839  /// namespace delimiter.
840  /// Returns \p lhs if \p rhs is empty and vice verse.
841  /// Returns an empty string if both \p lhs and \p rhs are empty.
842  SDF_API
843  static std::string JoinIdentifier(const TfToken &lhs, const TfToken &rhs);
844 
845  /// Returns \p name stripped of any namespaces.
846  /// This does not check the validity of the name; it just attempts
847  /// to remove anything that looks like a namespace.
848  SDF_API
850 
851  /// Returns \p name stripped of any namespaces.
852  /// This does not check the validity of the name; it just attempts
853  /// to remove anything that looks like a namespace.
854  SDF_API
855  static TfToken StripNamespace(const TfToken &name);
856 
857  /// Returns (\p name, \c true) where \p name is stripped of the prefix
858  /// specified by \p matchNamespace if \p name indeed starts with
859  /// \p matchNamespace. Returns (\p name, \c false) otherwise, with \p name
860  /// unmodified.
861  ///
862  /// This function deals with both the case where \p matchNamespace contains
863  /// the trailing namespace delimiter ':' or not.
864  ///
865  SDF_API
866  static std::pair<std::string, bool>
868  const std::string &matchNamespace);
869 
870  /// Return true if \p pathString is a valid path string, meaning that
871  /// passing the string to the \a SdfPath constructor will result in a valid,
872  /// non-empty SdfPath. Otherwise, return false and if \p errMsg is not NULL,
873  /// set the pointed-to string to the parse error.
874  SDF_API
875  static bool IsValidPathString(const std::string &pathString,
876  std::string *errMsg = 0);
877 
878  /// @}
879 
880  /// \name Operators
881  /// @{
882 
883  /// Equality operator.
884  /// (Boost provides inequality from this.)
885  inline bool operator==(const SdfPath &rhs) const {
886  return _AsInt() == rhs._AsInt();
887  }
888 
889  /// Comparison operator.
890  ///
891  /// This orders paths lexicographically, aka dictionary-style.
892  ///
893  inline bool operator<(const SdfPath &rhs) const {
894  if (_AsInt() == rhs._AsInt()) {
895  return false;
896  }
897  if (!_primPart || !rhs._primPart) {
898  return !_primPart && rhs._primPart;
899  }
900  // Valid prim parts -- must walk node structure, etc.
901  return _LessThanInternal(*this, rhs);
902  }
903 
904  template <class HashState>
905  friend void TfHashAppend(HashState &h, SdfPath const &path) {
906  // The hash function is pretty sensitive performance-wise. Be
907  // careful making changes here, and run tests.
908  uint32_t primPart, propPart;
909  memcpy(&primPart, &path._primPart, sizeof(primPart));
910  memcpy(&propPart, &path._propPart, sizeof(propPart));
911  h.Append(primPart);
912  h.Append(propPart);
913  }
914 
915  // For hash maps and sets
916  struct Hash {
917  inline size_t operator()(const SdfPath& path) const {
918  return TfHash()(path);
919  }
920  };
921 
922  inline size_t GetHash() const {
923  return Hash()(*this);
924  }
925 
926  // For cases where an unspecified total order that is not stable from
927  // run-to-run is needed.
928  struct FastLessThan {
929  inline bool operator()(const SdfPath& a, const SdfPath& b) const {
930  return a._AsInt() < b._AsInt();
931  }
932  };
933 
934  /// @}
935 
936  /// \name Utilities
937  /// @{
938 
939  /// Given some vector of paths, get a vector of concise unambiguous
940  /// relative paths.
941  ///
942  /// GetConciseRelativePaths requires a vector of absolute paths. It
943  /// finds a set of relative paths such that each relative path is
944  /// unique.
945  SDF_API static SdfPathVector
946  GetConciseRelativePaths(const SdfPathVector& paths);
947 
948  /// Remove all elements of \a paths that are prefixed by other
949  /// elements in \a paths. As a side-effect, the result is left in sorted
950  /// order.
951  SDF_API static void RemoveDescendentPaths(SdfPathVector *paths);
952 
953  /// Remove all elements of \a paths that prefix other elements in
954  /// \a paths. As a side-effect, the result is left in sorted order.
955  SDF_API static void RemoveAncestorPaths(SdfPathVector *paths);
956 
957  /// @}
958 
959 private:
960 
961  // This is used for all internal path construction where we do operations
962  // via nodes and then want to return a new path with a resulting prim and
963  // property parts.
964 
965  // Accept rvalues.
966  explicit SdfPath(Sdf_PathPrimNodeHandle &&primNode)
967  : _primPart(std::move(primNode)) {}
968 
969  SdfPath(Sdf_PathPrimNodeHandle &&primPart,
970  Sdf_PathPropNodeHandle &&propPart)
971  : _primPart(std::move(primPart))
972  , _propPart(std::move(propPart)) {}
973 
974  // Construct from prim & prop parts.
975  SdfPath(Sdf_PathPrimNodeHandle const &primPart,
976  Sdf_PathPropNodeHandle const &propPart)
977  : _primPart(primPart)
978  , _propPart(propPart) {}
979 
980  // Construct from prim & prop node pointers.
981  SdfPath(Sdf_PathNode const *primPart,
982  Sdf_PathNode const *propPart)
983  : _primPart(primPart)
984  , _propPart(propPart) {}
985 
986  friend class Sdf_PathNode;
987  friend class Sdfext_PathAccess;
988  friend class SdfPathAncestorsRange;
989 
990  // converts elements to a string for parsing (unfortunate)
991  static std::string
992  _ElementsToString(bool absolute, const std::vector<std::string> &elements);
993 
994  SdfPath _ReplacePrimPrefix(SdfPath const &oldPrefix,
995  SdfPath const &newPrefix) const;
996 
997  SdfPath _ReplaceTargetPathPrefixes(SdfPath const &oldPrefix,
998  SdfPath const &newPrefix) const;
999 
1000  SdfPath _ReplacePropPrefix(SdfPath const &oldPrefix,
1001  SdfPath const &newPrefix,
1002  bool fixTargetPaths) const;
1003 
1004  // Helper to implement the uninlined portion of operator<.
1005  SDF_API static bool
1006  _LessThanInternal(SdfPath const &lhs, SdfPath const &rhs);
1007 
1008  inline uint64_t _AsInt() const {
1009  static_assert(sizeof(*this) == sizeof(uint64_t), "");
1010  uint64_t ret;
1011  std::memcpy(&ret, this, sizeof(*this));
1012  return ret;
1013  }
1014 
1015  friend void swap(SdfPath &lhs, SdfPath &rhs) {
1016  lhs._primPart.swap(rhs._primPart);
1017  lhs._propPart.swap(rhs._propPart);
1018  }
1019 
1020  SDF_API friend char const *
1022 
1023  Sdf_PathPrimNodeHandle _primPart;
1024  Sdf_PathPropNodeHandle _propPart;
1025 
1026 };
1027 
1028 
1029 /// \class SdfPathAncestorsRange
1030 ///
1031 /// Range representing a path and ancestors, and providing methods for
1032 /// iterating over them.
1033 ///
1034 /// An ancestor range represents a path and all of its ancestors ordered from
1035 /// nearest to furthest (root-most).
1036 /// For example, given a path like `/a/b.prop`, the range represents paths
1037 /// `/a/b.prop`, `/a/b` and `/a`, in that order.
1038 /// A range accepts relative paths as well: For path `a/b.prop`, the range
1039 /// represents paths 'a/b.prop`, `a/b` and `a`.
1040 /// If a path contains parent path elements, (`..`), those elements are treated
1041 /// as elements of the range. For instance, given path `../a/b`, the range
1042 /// represents paths `../a/b`, `../a` and `..`.
1043 /// This represents the same of set of `prefix` paths as SdfPath::GetPrefixes,
1044 /// but in reverse order.
1046 {
1047 public:
1048 
1050  : _path(path) {}
1051 
1052  const SdfPath& GetPath() const { return _path; }
1053 
1054  struct iterator {
1055  using iterator_category = std::forward_iterator_tag;
1057  using difference_type = std::ptrdiff_t;
1058  using reference = const SdfPath&;
1059  using pointer = const SdfPath*;
1060 
1061  iterator(const SdfPath& path) : _path(path) {}
1062 
1063  iterator() = default;
1064 
1065  SDF_API
1066  iterator& operator++();
1067 
1068  const SdfPath& operator*() const { return _path; }
1069 
1070  const SdfPath* operator->() const { return &_path; }
1071 
1072  bool operator==(const iterator& o) const { return _path == o._path; }
1073 
1074  bool operator!=(const iterator& o) const { return _path != o._path; }
1075 
1076  /// Return the distance between two iterators.
1077  /// It is only valid to compute the distance between paths
1078  /// that share a common prefix.
1079  SDF_API friend difference_type
1080  distance(const iterator& first, const iterator& last);
1081 
1082  private:
1083  SdfPath _path;
1084  };
1085 
1086  iterator begin() const { return iterator(_path); }
1087 
1088  iterator end() const { return iterator(); }
1089 
1090 private:
1091  SdfPath _path;
1092 };
1093 
1094 
1095 // Overload hash_value for SdfPath. Used by things like hboost::hash.
1096 inline size_t hash_value(SdfPath const &path)
1097 {
1098  return path.GetHash();
1099 }
1100 
1101 /// Writes the string representation of \p path to \p out.
1102 SDF_API std::ostream & operator<<( std::ostream &out, const SdfPath &path );
1103 
1104 // Helper for SdfPathFindPrefixedRange & SdfPathFindLongestPrefix. A function
1105 // object that returns an SdfPath const & unchanged.
1107  inline SdfPath const &operator()(SdfPath const &arg) const {
1108  return arg;
1109  }
1110 };
1111 
1112 /// Find the subrange of the sorted range [\a begin, \a end) that includes all
1113 /// paths prefixed by \a path. The input range must be ordered according to
1114 /// SdfPath::operator<. If your range's iterators' value_types are not SdfPath,
1115 /// but you can obtain SdfPaths from them (e.g. map<SdfPath, X>::iterator), you
1116 /// can pass a function to extract the path from the dereferenced iterator in
1117 /// \p getPath.
1118 template <class ForwardIterator, class GetPathFn = Sdf_PathIdentity>
1119 std::pair<ForwardIterator, ForwardIterator>
1120 SdfPathFindPrefixedRange(ForwardIterator begin, ForwardIterator end,
1121  SdfPath const &prefix,
1122  GetPathFn const &getPath = GetPathFn()) {
1123  using IterRef =
1125 
1126  struct Compare {
1127  Compare(GetPathFn const &getPath) : _getPath(getPath) {}
1128  GetPathFn const &_getPath;
1129  bool operator()(IterRef a, SdfPath const &b) const {
1130  return _getPath(a) < b;
1131  }
1132  };
1133 
1134  std::pair<ForwardIterator, ForwardIterator> result;
1135 
1136  // First, use lower_bound to find where \a prefix would go.
1137  result.first = std::lower_bound(begin, end, prefix, Compare(getPath));
1138 
1139  // Next, find end of range starting from the lower bound, using the
1140  // prefixing condition to define the boundary.
1141  result.second = TfFindBoundary(result.first, end,
1142  [&prefix, &getPath](IterRef iterRef) {
1143  return getPath(iterRef).HasPrefix(prefix);
1144  });
1145 
1146  return result;
1147 }
1148 
1149 template <class RandomAccessIterator, class GetPathFn>
1150 RandomAccessIterator
1152  RandomAccessIterator end,
1153  SdfPath const &path,
1154  bool strictPrefix,
1155  GetPathFn const &getPath)
1156 {
1157  using IterRef =
1159 
1160  struct Compare {
1161  Compare(GetPathFn const &getPath) : _getPath(getPath) {}
1162  GetPathFn const &_getPath;
1163  bool operator()(IterRef a, SdfPath const &b) const {
1164  return _getPath(a) < b;
1165  }
1166  };
1167 
1168  // Search for the path in [begin, end). If present, return it. If not,
1169  // examine prior element in [begin, end). If none, return end. Else, is it
1170  // a prefix of path? If so, return it. Else find common prefix of that
1171  // element and path and recurse.
1172 
1173  // If empty sequence, return.
1174  if (begin == end)
1175  return end;
1176 
1177  Compare comp(getPath);
1178 
1179  // Search for where this path would lexicographically appear in the range.
1180  RandomAccessIterator result = std::lower_bound(begin, end, path, comp);
1181 
1182  // If we didn't get the end, check to see if we got the path exactly if
1183  // we're not looking for a strict prefix.
1184  if (!strictPrefix && result != end && getPath(*result) == path) {
1185  return result;
1186  }
1187 
1188  // If we got begin (and didn't match in the case of a non-strict prefix)
1189  // then there's no prefix.
1190  if (result == begin) {
1191  return end;
1192  }
1193 
1194  // If the prior element is a prefix, we're done.
1195  if (path.HasPrefix(getPath(*--result))) {
1196  return result;
1197  }
1198 
1199  // Otherwise, find the common prefix of the lexicographical predecessor and
1200  // look for its prefix in the preceding range.
1201  SdfPath newPath = path.GetCommonPrefix(getPath(*result));
1202  auto origEnd = end;
1203  do {
1204  end = result;
1205  result = std::lower_bound(begin, end, newPath, comp);
1206 
1207  if (result != end && getPath(*result) == newPath) {
1208  return result;
1209  }
1210  if (result == begin) {
1211  return origEnd;
1212  }
1213  if (newPath.HasPrefix(getPath(*--result))) {
1214  return result;
1215  }
1216  newPath = newPath.GetCommonPrefix(getPath(*result));
1217  } while (true);
1218 }
1219 
1220 /// Return an iterator to the element of [\a begin, \a end) that is the longest
1221 /// prefix of the given path (including the path itself), if there is such an
1222 /// element, otherwise \a end. The input range must be ordered according to
1223 /// SdfPath::operator<. If your range's iterators' value_types are not SdfPath,
1224 /// but you can obtain SdfPaths from them (e.g. vector<pair<SdfPath,
1225 /// X>>::iterator), you can pass a function to extract the path from the
1226 /// dereferenced iterator in \p getPath.
1227 template <class RandomAccessIterator, class GetPathFn = Sdf_PathIdentity,
1228  class = typename std::enable_if<
1229  std::is_base_of<
1230  std::random_access_iterator_tag,
1231  typename std::iterator_traits<
1232  RandomAccessIterator>::iterator_category
1233  >::value
1234  >::type
1235  >
1236 RandomAccessIterator
1237 SdfPathFindLongestPrefix(RandomAccessIterator begin,
1238  RandomAccessIterator end,
1239  SdfPath const &path,
1240  GetPathFn const &getPath = GetPathFn())
1241 {
1243  begin, end, path, /*strictPrefix=*/false, getPath);
1244 }
1245 
1246 /// Return an iterator to the element of [\a begin, \a end) that is the longest
1247 /// prefix of the given path (excluding the path itself), if there is such an
1248 /// element, otherwise \a end. The input range must be ordered according to
1249 /// SdfPath::operator<. If your range's iterators' value_types are not SdfPath,
1250 /// but you can obtain SdfPaths from them (e.g. vector<pair<SdfPath,
1251 /// X>>::iterator), you can pass a function to extract the path from the
1252 /// dereferenced iterator in \p getPath.
1253 template <class RandomAccessIterator, class GetPathFn = Sdf_PathIdentity,
1254  class = typename std::enable_if<
1255  std::is_base_of<
1256  std::random_access_iterator_tag,
1257  typename std::iterator_traits<
1258  RandomAccessIterator>::iterator_category
1259  >::value
1260  >::type
1261  >
1262 RandomAccessIterator
1263 SdfPathFindLongestStrictPrefix(RandomAccessIterator begin,
1264  RandomAccessIterator end,
1265  SdfPath const &path,
1266  GetPathFn const &getPath = GetPathFn())
1267 {
1269  begin, end, path, /*strictPrefix=*/true, getPath);
1270 }
1271 
1272 template <class Iter, class MapParam, class GetPathFn = Sdf_PathIdentity>
1273 Iter
1275  MapParam map, SdfPath const &path, bool strictPrefix,
1276  GetPathFn const &getPath = GetPathFn())
1277 {
1278  // Search for the path in map. If present, return it. If not, examine
1279  // prior element in map. If none, return end. Else, is it a prefix of
1280  // path? If so, return it. Else find common prefix of that element and
1281  // path and recurse.
1282 
1283  const Iter mapEnd = map.end();
1284 
1285  // If empty, return.
1286  if (map.empty())
1287  return mapEnd;
1288 
1289  // Search for where this path would lexicographically appear in the range.
1290  Iter result = map.lower_bound(path);
1291 
1292  // If we didn't get the end, check to see if we got the path exactly if
1293  // we're not looking for a strict prefix.
1294  if (!strictPrefix && result != mapEnd && getPath(*result) == path)
1295  return result;
1296 
1297  // If we got begin (and didn't match in the case of a non-strict prefix)
1298  // then there's no prefix.
1299  if (result == map.begin())
1300  return mapEnd;
1301 
1302  // If the prior element is a prefix, we're done.
1303  if (path.HasPrefix(getPath(*--result)))
1304  return result;
1305 
1306  // Otherwise, find the common prefix of the lexicographical predecessor and
1307  // recurse looking for it or its longest prefix in the preceding range. We
1308  // always pass strictPrefix=false, since now we're operating on prefixes of
1309  // the original caller's path.
1310  return Sdf_PathFindLongestPrefixImpl<Iter, MapParam>(
1311  map, path.GetCommonPrefix(getPath(*result)), /*strictPrefix=*/false,
1312  getPath);
1313 }
1314 
1315 /// Return an iterator pointing to the element of \a set whose key is the
1316 /// longest prefix of the given path (including the path itself). If there is
1317 /// no such element, return \a set.end().
1318 SDF_API
1319 typename std::set<SdfPath>::const_iterator
1320 SdfPathFindLongestPrefix(std::set<SdfPath> const &set, SdfPath const &path);
1321 
1322 /// Return an iterator pointing to the element of \a map whose key is the
1323 /// longest prefix of the given path (including the path itself). If there is
1324 /// no such element, return \a map.end().
1325 template <class T>
1326 typename std::map<SdfPath, T>::const_iterator
1327 SdfPathFindLongestPrefix(std::map<SdfPath, T> const &map, SdfPath const &path)
1328 {
1330  typename std::map<SdfPath, T>::const_iterator,
1331  std::map<SdfPath, T> const &>(map, path, /*strictPrefix=*/false,
1332  TfGet<0>());
1333 }
1334 template <class T>
1335 typename std::map<SdfPath, T>::iterator
1336 SdfPathFindLongestPrefix(std::map<SdfPath, T> &map, SdfPath const &path)
1337 {
1339  typename std::map<SdfPath, T>::iterator,
1340  std::map<SdfPath, T> &>(map, path, /*strictPrefix=*/false,
1341  TfGet<0>());
1342 }
1343 
1344 /// Return an iterator pointing to the element of \a set whose key is the
1345 /// longest prefix of the given path (excluding the path itself). If there is
1346 /// no such element, return \a set.end().
1347 SDF_API
1348 typename std::set<SdfPath>::const_iterator
1349 SdfPathFindLongestStrictPrefix(std::set<SdfPath> const &set,
1350  SdfPath const &path);
1351 
1352 /// Return an iterator pointing to the element of \a map whose key is the
1353 /// longest prefix of the given path (excluding the path itself). If there is
1354 /// no such element, return \a map.end().
1355 template <class T>
1356 typename std::map<SdfPath, T>::const_iterator
1358  std::map<SdfPath, T> const &map, SdfPath const &path)
1359 {
1361  typename std::map<SdfPath, T>::const_iterator,
1362  std::map<SdfPath, T> const &>(map, path, /*strictPrefix=*/true,
1363  TfGet<0>());
1364 }
1365 template <class T>
1366 typename std::map<SdfPath, T>::iterator
1368  std::map<SdfPath, T> &map, SdfPath const &path)
1369 {
1371  typename std::map<SdfPath, T>::iterator,
1372  std::map<SdfPath, T> &>(map, path, /*strictPrefix=*/true,
1373  TfGet<0>());
1374 }
1375 
1376 // A helper function for debugger pretty-printers, etc. This function is *not*
1377 // thread-safe. It writes to a static buffer and returns a pointer to it.
1378 // Subsequent calls to this function overwrite the memory written in prior
1379 // calls. If the given path's string representation exceeds the static buffer
1380 // size, return a pointer to a message indicating so.
1381 SDF_API
1382 char const *
1384 
1386 
1387 // Sdf_PathNode is not public API, but we need to include it here
1388 // so we can inline the ref-counting operations, which must manipulate
1389 // its internal _refCount member.
1390 #include "pxr/usd/sdf/pathNode.h"
1391 
1393 
1394 static_assert(Sdf_SizeofPrimPathNode == sizeof(Sdf_PrimPathNode), "");
1395 static_assert(Sdf_SizeofPropPathNode == sizeof(Sdf_PrimPropertyPathNode), "");
1396 
1398 
1399 #endif // PXR_USD_SDF_PATH_H
SDF_API const char * GetText() const
SDF_API bool IsPrimOrPrimVariantSelectionPath() const
SDF_API SdfPath AppendTarget(const SdfPath &targetPath) const
SDF_API bool IsMapperPath() const
Returns whether the path identifies a connection mapper.
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
friend void swap(SdfPath &lhs, SdfPath &rhs)
Definition: path.h:1015
SDF_API iterator & operator++()
SDF_API const std::string & GetName() const
static SDF_API const SdfPath & AbsoluteRootPath()
friend class Sdfext_PathAccess
Definition: path.h:987
static constexpr bool IsCounted
Definition: path.h:85
Sdf_PathNodeHandleImpl(Sdf_PathNodeHandleImpl const &rhs) noexcept
Definition: path.h:105
SDF_API std::string GetElementString() const
SDF_API bool IsExpressionPath() const
Returns whether the path identifies a connection expression.
SDF_API SdfPath AppendExpression() const
iterator(const SdfPath &path)
Definition: path.h:1061
Sdf_PathNodeHandleImpl(Handle h, bool add_ref=true)
Definition: path.h:98
SDF_API SdfPath AppendMapper(const SdfPath &targetPath) const
GLint first
Definition: glcorearb.h:405
STATIC_INLINE size_t Hash(const char *s, size_t len)
Definition: farmhash.h:2038
SDF_API char const * Sdf_PathGetDebuggerPathText(SdfPath const &)
bool operator==(const SdfPath &rhs) const
Definition: path.h:885
Sdf_PathPropPartPool::Handle Sdf_PathPropHandle
Definition: path.h:76
SDF_API SdfPath ReplaceTargetPath(const SdfPath &newTargetPath) const
void reset() noexcept
Definition: path.h:144
std::pair< ForwardIterator, ForwardIterator > SdfPathFindPrefixedRange(ForwardIterator begin, ForwardIterator end, SdfPath const &prefix, GetPathFn const &getPath=GetPathFn())
Definition: path.h:1120
static SDF_API bool IsValidPathString(const std::string &pathString, std::string *errMsg=0)
RandomAccessIterator Sdf_PathFindLongestPrefixImpl(RandomAccessIterator begin, RandomAccessIterator end, SdfPath const &path, bool strictPrefix, GetPathFn const &getPath)
Definition: path.h:1151
SDF_API bool IsAbsoluteRootPath() const
Return true if this path is the AbsoluteRootPath().
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
SDF_API bool IsMapperArgPath() const
Returns whether the path identifies a connection mapper arg.
GLenum const void GLuint GLint reference
Definition: glew.h:13927
SDF_API const SdfPath & GetTargetPath() const
GLenum GLsizei const void * pathString
Definition: glew.h:13919
SDF_API bool IsPrimPropertyPath() const
SDF_API SdfPath GetAbsoluteRootOrPrimPath() const
SdfPathAncestorsRange(const SdfPath &path)
Definition: path.h:1049
SDF_API TfToken GetAsToken() const
Sdf_PathNodeHandleImpl & operator=(Sdf_PathNodeHandleImpl &&rhs) noexcept
Definition: path.h:133
bool operator==(const iterator &o) const
Definition: path.h:1072
static SDF_API void RemoveDescendentPaths(SdfPathVector *paths)
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:419
bool operator==(Sdf_PathNodeHandleImpl const &rhs) const noexcept
Definition: path.h:171
SdfPath() noexcept
Definition: path.h:308
GLuint const GLchar * name
Definition: glcorearb.h:786
Sdf_PathNodeHandleImpl(Sdf_PathNode const *p, bool add_ref=true)
Definition: path.h:90
auto arg(const Char *name, const T &arg) -> detail::named_arg< Char, T >
Definition: core.h:1736
SdfPath const & operator()(SdfPath const &arg) const
Definition: path.h:1107
size_t GetHash() const
Definition: path.h:922
SDF_API std::pair< std::string, std::string > GetVariantSelection() const
SDF_API SdfPath StripAllVariantSelections() const
bool operator!=(const iterator &o) const
Definition: path.h:1074
SDF_API SdfPath AppendRelationalAttribute(TfToken const &attrName) const
Definition: hash.h:447
static SDF_API std::vector< std::string > TokenizeIdentifier(const std::string &name)
static SDF_API const SdfPath & EmptyPath()
The empty path value, equivalent to SdfPath().
const SdfPath & operator*() const
Definition: path.h:1068
Definition: token.h:87
GLuint64EXT * result
Definition: glew.h:14311
bool operator<(const SdfPath &rhs) const
Definition: path.h:893
void swap(Sdf_PathNodeHandleImpl &rhs) noexcept
Definition: path.h:167
friend void TfHashAppend(HashState &h, SdfPath const &path)
Definition: path.h:905
SDF_API void GetAllTargetPathsRecursively(SdfPathVector *result) const
bool ContainsPropertyElements() const
Definition: path.h:392
SDF_API bool IsPrimVariantSelectionPath() const
bool operator!=(Sdf_PathNodeHandleImpl const &rhs) const noexcept
Definition: path.h:174
void intrusive_ptr_add_ref(Sdf_PathNode const *)
SDF_API SdfPath AppendChild(TfToken const &childName) const
static SDF_API bool IsValidNamespacedIdentifier(const std::string &name)
Sdf_PathNode const & operator*() const
Definition: path.h:154
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1222
GLuint GLuint end
Definition: glcorearb.h:475
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
SDF_API SdfPath AppendVariantSelection(const std::string &variantSet, const std::string &variant) const
SDF_API SdfPath AppendMapperArg(TfToken const &argName) const
SDF_API bool IsAbsolutePath() const
Returns whether the path is absolute.
GLfloat GLfloat p
Definition: glew.h:16656
static SDF_API std::string JoinIdentifier(const std::vector< std::string > &names)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
GLuint const GLuint * names
Definition: glew.h:2695
SDF_API bool ContainsTargetPath() const
static SDF_API bool IsValidIdentifier(const std::string &name)
SDF_API size_t GetPathElementCount() const
Returns the number of path elements in this path.
Definition: stl.h:391
Definition: path.h:290
SDF_API TfToken GetElementToken() const
Like GetElementString() but return the value as a TfToken.
SDF_API const std::string & GetString() const
SDF_API bool IsPrimPath() const
Returns whether the path identifies a prim.
size_t operator()(const SdfPath &path) const
Definition: path.h:917
Sdf_PathPrimPartPool::Handle Sdf_PathPrimHandle
Definition: path.h:75
Sdf_PathNodeHandleImpl & operator=(Sdf_PathNode const *rhs) noexcept
Definition: path.h:139
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
constexpr Sdf_PathNodeHandleImpl() noexcept
Definition: path.h:87
SDF_API const TfToken & GetNameToken() const
SDF_API bool HasPrefix(const SdfPath &prefix) const
SDF_API bool IsRelationalAttributePath() const
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:209
SDF_API SdfPath AppendProperty(TfToken const &propName) const
SDF_API bool ContainsPrimVariantSelection() const
hboost::intrusive_ptr< const Sdf_PathNode > Sdf_PathNodeConstRefPtr
Definition: path.h:49
std::forward_iterator_tag iterator_category
Definition: path.h:1055
#define SDF_API
Definition: api.h:40
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
bool operator<(Sdf_PathNodeHandleImpl const &rhs) const noexcept
Definition: path.h:177
SDF_API std::ostream & operator<<(std::ostream &out, const SdfPath &path)
Writes the string representation of path to out.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
const SdfPath * operator->() const
Definition: path.h:1070
SDF_API SdfPathAncestorsRange GetAncestorsRange() const
SDF_API SdfPath GetCommonPrefix(const SdfPath &path) const
SDF_API TfToken const & GetToken() const
SDF_API bool IsTargetPath() const
iterator end() const
Definition: path.h:1088
Sdf_PathNodeHandleImpl & operator=(Sdf_PathNodeHandleImpl const &rhs)
Definition: path.h:119
SDF_API std::pair< SdfPath, SdfPath > RemoveCommonSuffix(const SdfPath &otherPath, bool stopAtRootPrim=false) const
size_t hash_value(SdfPath const &path)
Definition: path.h:1096
SDF_API bool IsRootPrimPath() const
SDF_API SdfPath AppendPath(const SdfPath &newSuffix) const
SDF_API std::string GetAsString() const
const SdfPath & GetPath() const
Definition: path.h:1052
iterator begin() const
Definition: path.h:1086
void intrusive_ptr_release(Sdf_PathNode const *)
SDF_API SdfPath MakeAbsolutePath(const SdfPath &anchor) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDF_API bool IsNamespacedPropertyPath() const
SDF_API SdfPath AppendElementToken(const TfToken &elementTok) const
Like AppendElementString() but take the element as a TfToken.
SDF_API SdfPath GetParentPath() const
static SDF_API SdfPathVector GetConciseRelativePaths(const SdfPathVector &paths)
SDF_API SdfPath GetPrimOrPrimVariantSelectionPath() const
SDF_API bool IsPropertyPath() const
static SDF_API std::pair< std::string, bool > StripPrefixNamespace(const std::string &name, const std::string &matchNamespace)
Definition: core.h:1131
SDF_API friend char const * Sdf_PathGetDebuggerPathText(SdfPath const &)
SDF_API friend difference_type distance(const iterator &first, const iterator &last)
RandomAccessIterator SdfPathFindLongestPrefix(RandomAccessIterator begin, RandomAccessIterator end, SdfPath const &path, GetPathFn const &getPath=GetPathFn())
Definition: path.h:1237
static SDF_API void RemoveAncestorPaths(SdfPathVector *paths)
#define const
Definition: zconf.h:214
SDF_API bool IsAbsoluteRootOrPrimPath() const
Returns whether the path identifies a prim or the absolute root.
RandomAccessIterator SdfPathFindLongestStrictPrefix(RandomAccessIterator begin, RandomAccessIterator end, SdfPath const &path, GetPathFn const &getPath=GetPathFn())
Definition: path.h:1263
Sdf_PathNode const * operator->() const
Definition: path.h:159
Sdf_PathNodeHandleImpl(Sdf_PathNodeHandleImpl &&rhs) noexcept
Definition: path.h:127
SDF_API SdfPathVector GetPrefixes() const
type
Definition: core.h:1059
static SDF_API std::string StripNamespace(const std::string &name)
friend struct Handle
Definition: pool.h:94
SDF_API SdfPath ReplaceName(TfToken const &newName) const
static SDF_API const SdfPath & ReflexiveRelativePath()
The relative path representing "self".
SDF_API SdfPath AppendElementString(const std::string &element) const
bool operator()(const SdfPath &a, const SdfPath &b) const
Definition: path.h:929
VT_TYPE_IS_CHEAP_TO_COPY(class SdfPath)
Definition: pool.h:79
std::ptrdiff_t difference_type
Definition: path.h:1057
SDF_API SdfPath MakeRelativePath(const SdfPath &anchor) const
SDF_API SdfPath ReplacePrefix(const SdfPath &oldPrefix, const SdfPath &newPrefix, bool fixTargetPaths=true) const
SDF_API SdfPath GetPrimPath() const
GLenum const void * paths
Definition: glew.h:13872
void * Handle
Definition: plugin.h:27
static SDF_API TfTokenVector TokenizeIdentifierAsTokens(const std::string &name)
PcpNodeRef_ChildrenIterator begin(const PcpNodeRef::child_const_range &r)
Support for range-based for loops for PcpNodeRef children ranges.
Definition: node.h:450