All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
path.h
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_USD_SDF_PATH_H
8#define PXR_USD_SDF_PATH_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/sdf/api.h"
12#include "pxr/usd/sdf/pool.h"
13#include "pxr/usd/sdf/tokens.h"
14#include "pxr/base/arch/defines.h"
15#include "pxr/base/tf/delegatedCountPtr.h"
16#include "pxr/base/tf/span.h"
17#include "pxr/base/tf/stl.h"
18#include "pxr/base/tf/token.h"
19#include "pxr/base/vt/traits.h"
20
21#include <algorithm>
22#include <iterator>
23#include <set>
24#include <string>
25#include <type_traits>
26#include <utility>
27#include <vector>
28
29PXR_NAMESPACE_OPEN_SCOPE
30
31class Sdf_PathNode;
33
34// Ref-counting pointer to a path node.
35// Delegated ref-counts are used to keep the size of SdfPath
36// the same as a raw pointer. (shared_ptr, by comparison,
37// is the size of two pointers.)
38
40
41void TfDelegatedCountIncrement(Sdf_PathNode const *) noexcept;
42void TfDelegatedCountDecrement(Sdf_PathNode const *) noexcept;
43
44// Tags used for the pools of path nodes.
45struct Sdf_PathPrimTag;
46struct Sdf_PathPropTag;
47
48// These are validated below.
49static constexpr size_t Sdf_SizeofPrimPathNode = sizeof(void *) * 3;
50static constexpr size_t Sdf_SizeofPropPathNode = sizeof(void *) * 3;
51
52using Sdf_PathPrimPartPool = Sdf_Pool<
53 Sdf_PathPrimTag, Sdf_SizeofPrimPathNode, /*regionBits=*/8>;
54
55using Sdf_PathPropPartPool = Sdf_Pool<
56 Sdf_PathPropTag, Sdf_SizeofPropPathNode, /*regionBits=*/8>;
57
58using Sdf_PathPrimHandle = Sdf_PathPrimPartPool::Handle;
59using Sdf_PathPropHandle = Sdf_PathPropPartPool::Handle;
60
61// This handle class wraps up the raw Prim/PropPartPool handles.
62template <class Handle, bool Counted, class PathNode=Sdf_PathNode const>
63struct Sdf_PathNodeHandleImpl {
64private:
65 typedef Sdf_PathNodeHandleImpl this_type;
66
67public:
68 static constexpr bool IsCounted = Counted;
69
70 constexpr Sdf_PathNodeHandleImpl() noexcept {};
71
72 explicit
73 Sdf_PathNodeHandleImpl(Sdf_PathNode const *p, bool add_ref = true)
74 : _poolHandle(Handle::GetHandle(reinterpret_cast<char const *>(p))) {
75 if (p && add_ref) {
76 _AddRef(p);
77 }
78 }
79
80 explicit
81 Sdf_PathNodeHandleImpl(Handle h, bool add_ref = true)
82 : _poolHandle(h) {
83 if (h && add_ref) {
84 _AddRef();
85 }
86 }
87
88 Sdf_PathNodeHandleImpl(Sdf_PathNodeHandleImpl const &rhs) noexcept
89 : _poolHandle(rhs._poolHandle) {
90 if (_poolHandle) {
91 _AddRef();
92 }
93 }
94
95 ~Sdf_PathNodeHandleImpl() {
96 if (_poolHandle) {
97 _DecRef();
98 }
99 }
100
101 Sdf_PathNodeHandleImpl &
102 operator=(Sdf_PathNodeHandleImpl const &rhs) {
103 if (Counted && *this == rhs) {
104 return *this;
105 }
106 this_type(rhs).swap(*this);
107 return *this;
108 }
109
110 Sdf_PathNodeHandleImpl(Sdf_PathNodeHandleImpl &&rhs) noexcept
111 : _poolHandle(rhs._poolHandle) {
112 rhs._poolHandle = nullptr;
113 }
114
115 Sdf_PathNodeHandleImpl &
116 operator=(Sdf_PathNodeHandleImpl &&rhs) noexcept {
117 this_type(std::move(rhs)).swap(*this);
118 return *this;
119 }
120
121 Sdf_PathNodeHandleImpl &
122 operator=(Sdf_PathNode const *rhs) noexcept {
123 this_type(rhs).swap(*this);
124 return *this;
125 }
126
127 void reset() noexcept {
128 _poolHandle = Handle { nullptr };
129 }
130
131 inline Sdf_PathNode const *
132 get() const noexcept {
133 return reinterpret_cast<Sdf_PathNode *>(_poolHandle.GetPtr());
134 }
135
136 Sdf_PathNode const &
137 operator*() const {
138 return *get();
139 }
140
141 Sdf_PathNode const *
142 operator->() const {
143 return get();
144 }
145
146 explicit operator bool() const noexcept {
147 return static_cast<bool>(_poolHandle);
148 }
149
150 void swap(Sdf_PathNodeHandleImpl &rhs) noexcept {
151 _poolHandle.swap(rhs._poolHandle);
152 }
153
154 inline bool operator==(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
155 return _poolHandle == rhs._poolHandle;
156 }
157 inline bool operator!=(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
158 return _poolHandle != rhs._poolHandle;
159 }
160 inline bool operator<(Sdf_PathNodeHandleImpl const &rhs) const noexcept {
161 return _poolHandle < rhs._poolHandle;
162 }
163private:
164
165 inline void _AddRef(Sdf_PathNode const *p) const {
166 if (Counted) {
167 TfDelegatedCountIncrement(p);
168 }
169 }
170
171 inline void _AddRef() const {
172 _AddRef(get());
173 }
174
175 inline void _DecRef() const {
176 if (Counted) {
177 TfDelegatedCountDecrement(get());
178 }
179 }
180
181 Handle _poolHandle { nullptr };
182};
183
184using Sdf_PathPrimNodeHandle =
185 Sdf_PathNodeHandleImpl<Sdf_PathPrimHandle, /*Counted=*/true>;
186
187using Sdf_PathPropNodeHandle =
188 Sdf_PathNodeHandleImpl<Sdf_PathPropHandle, /*Counted=*/false>;
189
190
192typedef std::set<class SdfPath> SdfPathSet;
194typedef std::vector<class SdfPath> SdfPathVector;
195
196// Tell VtValue that SdfPath is cheap to copy.
197VT_TYPE_IS_CHEAP_TO_COPY(class SdfPath);
198
274{
275public:
277 SDF_API static const SdfPath & EmptyPath();
278
281 SDF_API static const SdfPath & AbsoluteRootPath();
282
284 SDF_API static const SdfPath & ReflexiveRelativePath();
285
288
291 SdfPath() noexcept = default;
292
305 //
306 // XXX We may want to revisit the behavior when constructing
307 // a path with an empty string ("") to accept it without error and
308 // return EmptyPath.
309 SDF_API explicit SdfPath(const std::string &path);
310
312
315
317 SDF_API size_t GetPathElementCount() const;
318
320 SDF_API bool IsAbsolutePath() const;
321
323 SDF_API bool IsAbsoluteRootPath() const;
324
326 SDF_API bool IsPrimPath() const;
327
329 SDF_API bool IsAbsoluteRootOrPrimPath() const;
330
335 SDF_API bool IsRootPrimPath() const;
336
342 SDF_API bool IsPropertyPath() const;
343
347 SDF_API bool IsPrimPropertyPath() const;
348
352 SDF_API bool IsNamespacedPropertyPath() const;
353
356 SDF_API bool IsPrimVariantSelectionPath() const;
357
361
364 SDF_API bool ContainsPrimVariantSelection() const;
365
372 return static_cast<bool>(_propPart);
373 }
374
377 SDF_API bool ContainsTargetPath() const;
378
382 SDF_API bool IsRelationalAttributePath() const;
383
386 SDF_API bool IsTargetPath() const;
387
389 SDF_API bool IsMapperPath() const;
390
392 SDF_API bool IsMapperArgPath() const;
393
395 SDF_API bool IsExpressionPath() const;
396
398 inline bool IsEmpty() const noexcept {
399 // No need to check _propPart, because it can only be non-null if
400 // _primPart is non-null.
401 return !_primPart;
402 }
403
409 SDF_API TfToken GetAsToken() const;
410
420 SDF_API TfToken const &GetToken() const;
421
427 SDF_API std::string GetAsString() const;
428
438 SDF_API const std::string &GetString() const;
439
450 SDF_API const char *GetText() const;
451
459 SDF_API SdfPathVector GetPrefixes() const;
460
469 SDF_API SdfPathVector GetPrefixes(size_t numPrefixes) const;
470
480 SDF_API void GetPrefixes(SdfPathVector *prefixes) const;
481
490 SDF_API void GetPrefixes(SdfPathVector *prefixes, size_t numPrefixes) const;
491
505
512
523 SDF_API const std::string &GetName() const;
524
527 SDF_API const TfToken &GetNameToken() const;
528
546 SDF_API std::string GetElementString() const;
547
549 SDF_API TfToken GetElementToken() const;
550
570 SDF_API SdfPath ReplaceName(TfToken const &newName) const;
571
584 SDF_API const SdfPath &GetTargetPath() const;
585
593 SDF_API void GetAllTargetPathsRecursively(SdfPathVector *result) const;
594
599 SDF_API
600 std::pair<std::string, std::string> GetVariantSelection() const;
601
604 SDF_API bool HasPrefix( const SdfPath &prefix ) const;
605
607
610
633 SDF_API SdfPath GetParentPath() const;
634
642 SDF_API SdfPath GetPrimPath() const;
643
653
660
665
673 SDF_API SdfPath AppendPath(const SdfPath &newSuffix) const;
674
680 SDF_API SdfPath AppendChild(TfToken const &childName) const;
681
686 SDF_API SdfPath AppendProperty(TfToken const &propName) const;
687
692 SDF_API
693 SdfPath AppendVariantSelection(const std::string &variantSet,
694 const std::string &variant) const;
695
700 SDF_API SdfPath AppendTarget(const SdfPath &targetPath) const;
701
706 SDF_API
708
712 SDF_API
713 SdfPath ReplaceTargetPath( const SdfPath &newTargetPath ) const;
714
719 SDF_API SdfPath AppendMapper(const SdfPath &targetPath) const;
720
725 SDF_API SdfPath AppendMapperArg(TfToken const &argName) const;
726
730 SDF_API SdfPath AppendExpression() const;
731
741 SDF_API SdfPath AppendElementString(const std::string &element) const;
742
744 SDF_API SdfPath AppendElementToken(const TfToken &elementTok) const;
745
755 SDF_API
756 SdfPath ReplacePrefix(const SdfPath &oldPrefix,
757 const SdfPath &newPrefix,
758 bool fixTargetPaths=true) const;
759
762 SDF_API SdfPath GetCommonPrefix(const SdfPath &path) const;
763
779 SDF_API
780 std::pair<SdfPath, SdfPath>
781 RemoveCommonSuffix(const SdfPath& otherPath,
782 bool stopAtRootPrim = false) const;
783
793 SDF_API SdfPath MakeAbsolutePath(const SdfPath & anchor) const;
794
807 SDF_API SdfPath MakeRelativePath(const SdfPath & anchor) const;
808
810
813
816 SDF_API static bool IsValidIdentifier(const std::string &name);
817
820 SDF_API static bool IsValidNamespacedIdentifier(const std::string &name);
821
825 SDF_API static std::vector<std::string> TokenizeIdentifier(const std::string &name);
826
830 SDF_API
831 static TfTokenVector TokenizeIdentifierAsTokens(const std::string &name);
832
835 SDF_API
836 static std::string JoinIdentifier(const std::vector<std::string> &names);
837
840 SDF_API
841 static std::string JoinIdentifier(const TfTokenVector& names);
842
847 SDF_API
848 static std::string JoinIdentifier(const std::string &lhs,
849 const std::string &rhs);
850
855 SDF_API
856 static std::string JoinIdentifier(const TfToken &lhs, const TfToken &rhs);
857
861 SDF_API
862 static std::string StripNamespace(const std::string &name);
863
867 SDF_API
868 static TfToken StripNamespace(const TfToken &name);
869
878 SDF_API
879 static std::pair<std::string, bool>
880 StripPrefixNamespace(const std::string &name,
881 const std::string &matchNamespace);
882
887 SDF_API
888 static bool IsValidPathString(const std::string &pathString,
889 std::string *errMsg = 0);
890
892
895
897 inline bool operator==(const SdfPath &rhs) const {
898 return _AsInt() == rhs._AsInt();
899 }
900
902 inline bool operator!=(const SdfPath &rhs) const {
903 return !(*this == rhs);
904 }
905
910 inline bool operator<(const SdfPath &rhs) const {
911 if (_AsInt() == rhs._AsInt()) {
912 return false;
913 }
914 if (!_primPart || !rhs._primPart) {
915 return !_primPart && rhs._primPart;
916 }
917 // Valid prim parts -- must walk node structure, etc.
918 return _LessThanInternal(*this, rhs);
919 }
920
923 inline bool operator>(const SdfPath& rhs) const {
924 return rhs < *this;
925 }
926
929 inline bool operator<=(const SdfPath& rhs) const {
930 return !(rhs < *this);
931 }
932
935 inline bool operator>=(const SdfPath& rhs) const {
936 return !(*this < rhs);
937 }
938
939 template <class HashState>
940 friend void TfHashAppend(HashState &h, SdfPath const &path) {
941 // The hash function is pretty sensitive performance-wise. Be
942 // careful making changes here, and run tests.
943 uint32_t primPart, propPart;
944 memcpy(&primPart, &path._primPart, sizeof(primPart));
945 memcpy(&propPart, &path._propPart, sizeof(propPart));
946 h.Append(primPart);
947 h.Append(propPart);
948 }
949
950 // For hash maps and sets
951 struct Hash {
952 inline size_t operator()(const SdfPath& path) const {
953 return TfHash()(path);
954 }
955 };
956
957 inline size_t GetHash() const {
958 return Hash()(*this);
959 }
960
961 // For cases where an unspecified total order that is not stable from
962 // run-to-run is needed.
963 struct FastLessThan {
964 inline bool operator()(const SdfPath& a, const SdfPath& b) const {
965 return a._AsInt() < b._AsInt();
966 }
967 };
968
970
973
980 SDF_API static SdfPathVector
981 GetConciseRelativePaths(const SdfPathVector& paths);
982
986 SDF_API static void RemoveDescendentPaths(SdfPathVector *paths);
987
990 SDF_API static void RemoveAncestorPaths(SdfPathVector *paths);
991
993
994private:
995
996 // This is used for all internal path construction where we do operations
997 // via nodes and then want to return a new path with a resulting prim and
998 // property parts.
999
1000 // Accept rvalues.
1001 explicit SdfPath(Sdf_PathPrimNodeHandle &&primNode)
1002 : _primPart(std::move(primNode)) {}
1003
1004 SdfPath(Sdf_PathPrimNodeHandle &&primPart,
1005 Sdf_PathPropNodeHandle &&propPart)
1006 : _primPart(std::move(primPart))
1007 , _propPart(std::move(propPart)) {}
1008
1009 // Construct from prim & prop parts.
1010 SdfPath(Sdf_PathPrimNodeHandle const &primPart,
1011 Sdf_PathPropNodeHandle const &propPart)
1012 : _primPart(primPart)
1013 , _propPart(propPart) {}
1014
1015 // Construct from prim & prop node pointers.
1016 SdfPath(Sdf_PathNode const *primPart,
1017 Sdf_PathNode const *propPart)
1018 : _primPart(primPart)
1019 , _propPart(propPart) {}
1020
1021 friend class Sdf_PathNode;
1022 friend class Sdfext_PathAccess;
1023 friend class SdfPathAncestorsRange;
1024
1025 SdfPath _ReplacePrimPrefix(SdfPath const &oldPrefix,
1026 SdfPath const &newPrefix) const;
1027
1028 SdfPath _ReplaceTargetPathPrefixes(SdfPath const &oldPrefix,
1029 SdfPath const &newPrefix) const;
1030
1031 SdfPath _ReplacePropPrefix(SdfPath const &oldPrefix,
1032 SdfPath const &newPrefix,
1033 bool fixTargetPaths) const;
1034
1035 // Helper to implement the uninlined portion of operator<.
1036 SDF_API static bool
1037 _LessThanInternal(SdfPath const &lhs, SdfPath const &rhs);
1038
1039 inline uint64_t _AsInt() const {
1040 static_assert(sizeof(*this) == sizeof(uint64_t), "");
1041 uint64_t ret;
1042 std::memcpy(&ret, this, sizeof(*this));
1043 return ret;
1044 }
1045
1046 friend void swap(SdfPath &lhs, SdfPath &rhs) {
1047 lhs._primPart.swap(rhs._primPart);
1048 lhs._propPart.swap(rhs._propPart);
1049 }
1050
1051 SDF_API friend char const *
1052 Sdf_PathGetDebuggerPathText(SdfPath const &);
1053
1054 Sdf_PathPrimNodeHandle _primPart;
1055 Sdf_PathPropNodeHandle _propPart;
1056
1057};
1058
1059
1077{
1078public:
1079
1080 SdfPathAncestorsRange(const SdfPath& path)
1081 : _path(path) {}
1082
1083 const SdfPath& GetPath() const { return _path; }
1084
1085 struct iterator {
1086 using iterator_category = std::forward_iterator_tag;
1087 using value_type = SdfPath;
1088 using difference_type = std::ptrdiff_t;
1089 using reference = const SdfPath&;
1090 using pointer = const SdfPath*;
1091
1092 iterator(const SdfPath& path) : _path(path) {}
1093
1094 iterator() = default;
1095
1096 SDF_API
1097 iterator& operator++();
1098
1099 const SdfPath& operator*() const { return _path; }
1100
1101 const SdfPath* operator->() const { return &_path; }
1102
1103 bool operator==(const iterator& o) const { return _path == o._path; }
1104
1105 bool operator!=(const iterator& o) const { return _path != o._path; }
1106
1110 SDF_API friend difference_type
1111 distance(const iterator& first, const iterator& last);
1112
1113 private:
1114 SdfPath _path;
1115 };
1116
1117 iterator begin() const { return iterator(_path); }
1118
1119 iterator end() const { return iterator(); }
1120
1121private:
1122 SdfPath _path;
1123};
1124
1125
1126// Overload hash_value for SdfPath. Used by things like boost::hash.
1127inline size_t hash_value(SdfPath const &path)
1128{
1129 return path.GetHash();
1130}
1131
1133SDF_API std::ostream & operator<<( std::ostream &out, const SdfPath &path );
1134
1135// Helper for SdfPathFindPrefixedRange & SdfPathFindLongestPrefix. A function
1136// object that returns an SdfPath const & unchanged.
1137struct Sdf_PathIdentity {
1138 inline SdfPath const &operator()(SdfPath const &arg) const {
1139 return arg;
1140 }
1141};
1142
1149template <class ForwardIterator, class GetPathFn = Sdf_PathIdentity>
1150std::pair<ForwardIterator, ForwardIterator>
1151SdfPathFindPrefixedRange(ForwardIterator begin, ForwardIterator end,
1152 SdfPath const &prefix,
1153 GetPathFn const &getPath = GetPathFn()) {
1154 using IterRef =
1155 typename std::iterator_traits<ForwardIterator>::reference;
1156
1157 struct Compare {
1158 Compare(GetPathFn const &getPath) : _getPath(getPath) {}
1159 GetPathFn const &_getPath;
1160 bool operator()(IterRef a, SdfPath const &b) const {
1161 return _getPath(a) < b;
1162 }
1163 };
1164
1165 std::pair<ForwardIterator, ForwardIterator> result;
1166
1167 // First, use lower_bound to find where \a prefix would go.
1168 result.first = std::lower_bound(begin, end, prefix, Compare(getPath));
1169
1170 // Next, find end of range starting from the lower bound, using the
1171 // prefixing condition to define the boundary.
1172 result.second = TfFindBoundary(result.first, end,
1173 [&prefix, &getPath](IterRef iterRef) {
1174 return getPath(iterRef).HasPrefix(prefix);
1175 });
1176
1177 return result;
1178}
1179
1180template <class RandomAccessIterator, class GetPathFn>
1181RandomAccessIterator
1182Sdf_PathFindLongestPrefixImpl(RandomAccessIterator begin,
1183 RandomAccessIterator end,
1184 SdfPath const &path,
1185 bool strictPrefix,
1186 GetPathFn const &getPath)
1187{
1188 using IterRef =
1189 typename std::iterator_traits<RandomAccessIterator>::reference;
1190
1191 struct Compare {
1192 Compare(GetPathFn const &getPath) : _getPath(getPath) {}
1193 GetPathFn const &_getPath;
1194 bool operator()(IterRef a, SdfPath const &b) const {
1195 return _getPath(a) < b;
1196 }
1197 };
1198
1199 // Search for the path in [begin, end). If present, return it. If not,
1200 // examine prior element in [begin, end). If none, return end. Else, is it
1201 // a prefix of path? If so, return it. Else find common prefix of that
1202 // element and path and recurse.
1203
1204 // If empty sequence, return.
1205 if (begin == end)
1206 return end;
1207
1208 Compare comp(getPath);
1209
1210 // Search for where this path would lexicographically appear in the range.
1211 RandomAccessIterator result = std::lower_bound(begin, end, path, comp);
1212
1213 // If we didn't get the end, check to see if we got the path exactly if
1214 // we're not looking for a strict prefix.
1215 if (!strictPrefix && result != end && getPath(*result) == path) {
1216 return result;
1217 }
1218
1219 // If we got begin (and didn't match in the case of a non-strict prefix)
1220 // then there's no prefix.
1221 if (result == begin) {
1222 return end;
1223 }
1224
1225 // If the prior element is a prefix, we're done.
1226 if (path.HasPrefix(getPath(*--result))) {
1227 return result;
1228 }
1229
1230 // Otherwise, find the common prefix of the lexicographical predecessor and
1231 // look for its prefix in the preceding range.
1232 SdfPath newPath = path.GetCommonPrefix(getPath(*result));
1233 auto origEnd = end;
1234 do {
1235 end = result;
1236 result = std::lower_bound(begin, end, newPath, comp);
1237
1238 if (result != end && getPath(*result) == newPath) {
1239 return result;
1240 }
1241 if (result == begin) {
1242 return origEnd;
1243 }
1244 if (newPath.HasPrefix(getPath(*--result))) {
1245 return result;
1246 }
1247 newPath = newPath.GetCommonPrefix(getPath(*result));
1248 } while (true);
1249}
1250
1258template <class RandomAccessIterator, class GetPathFn = Sdf_PathIdentity,
1259 class = typename std::enable_if<
1260 std::is_base_of<
1261 std::random_access_iterator_tag,
1262 typename std::iterator_traits<
1263 RandomAccessIterator>::iterator_category
1264 >::value
1265 >::type
1266 >
1267RandomAccessIterator
1268SdfPathFindLongestPrefix(RandomAccessIterator begin,
1269 RandomAccessIterator end,
1270 SdfPath const &path,
1271 GetPathFn const &getPath = GetPathFn())
1272{
1273 return Sdf_PathFindLongestPrefixImpl(
1274 begin, end, path, /*strictPrefix=*/false, getPath);
1275}
1276
1284template <class RandomAccessIterator, class GetPathFn = Sdf_PathIdentity,
1285 class = typename std::enable_if<
1286 std::is_base_of<
1287 std::random_access_iterator_tag,
1288 typename std::iterator_traits<
1289 RandomAccessIterator>::iterator_category
1290 >::value
1291 >::type
1292 >
1293RandomAccessIterator
1294SdfPathFindLongestStrictPrefix(RandomAccessIterator begin,
1295 RandomAccessIterator end,
1296 SdfPath const &path,
1297 GetPathFn const &getPath = GetPathFn())
1298{
1299 return Sdf_PathFindLongestPrefixImpl(
1300 begin, end, path, /*strictPrefix=*/true, getPath);
1301}
1302
1303template <class Iter, class MapParam, class GetPathFn = Sdf_PathIdentity>
1304Iter
1305Sdf_PathFindLongestPrefixImpl(
1306 MapParam map, SdfPath const &path, bool strictPrefix,
1307 GetPathFn const &getPath = GetPathFn())
1308{
1309 // Search for the path in map. If present, return it. If not, examine
1310 // prior element in map. If none, return end. Else, is it a prefix of
1311 // path? If so, return it. Else find common prefix of that element and
1312 // path and recurse.
1313
1314 const Iter mapEnd = map.end();
1315
1316 // If empty, return.
1317 if (map.empty())
1318 return mapEnd;
1319
1320 // Search for where this path would lexicographically appear in the range.
1321 Iter result = map.lower_bound(path);
1322
1323 // If we didn't get the end, check to see if we got the path exactly if
1324 // we're not looking for a strict prefix.
1325 if (!strictPrefix && result != mapEnd && getPath(*result) == path)
1326 return result;
1327
1328 // If we got begin (and didn't match in the case of a non-strict prefix)
1329 // then there's no prefix.
1330 if (result == map.begin())
1331 return mapEnd;
1332
1333 // If the prior element is a prefix, we're done.
1334 if (path.HasPrefix(getPath(*--result)))
1335 return result;
1336
1337 // Otherwise, find the common prefix of the lexicographical predecessor and
1338 // recurse looking for it or its longest prefix in the preceding range. We
1339 // always pass strictPrefix=false, since now we're operating on prefixes of
1340 // the original caller's path.
1341 return Sdf_PathFindLongestPrefixImpl<Iter, MapParam>(
1342 map, path.GetCommonPrefix(getPath(*result)), /*strictPrefix=*/false,
1343 getPath);
1344}
1345
1349SDF_API
1350typename std::set<SdfPath>::const_iterator
1351SdfPathFindLongestPrefix(std::set<SdfPath> const &set, SdfPath const &path);
1352
1356template <class T>
1357typename std::map<SdfPath, T>::const_iterator
1358SdfPathFindLongestPrefix(std::map<SdfPath, T> const &map, SdfPath const &path)
1359{
1360 return Sdf_PathFindLongestPrefixImpl<
1361 typename std::map<SdfPath, T>::const_iterator,
1362 std::map<SdfPath, T> const &>(map, path, /*strictPrefix=*/false,
1363 TfGet<0>());
1364}
1365template <class T>
1366typename std::map<SdfPath, T>::iterator
1367SdfPathFindLongestPrefix(std::map<SdfPath, T> &map, SdfPath const &path)
1368{
1369 return Sdf_PathFindLongestPrefixImpl<
1370 typename std::map<SdfPath, T>::iterator,
1371 std::map<SdfPath, T> &>(map, path, /*strictPrefix=*/false,
1372 TfGet<0>());
1373}
1374
1378SDF_API
1379typename std::set<SdfPath>::const_iterator
1380SdfPathFindLongestStrictPrefix(std::set<SdfPath> const &set,
1381 SdfPath const &path);
1382
1386template <class T>
1387typename std::map<SdfPath, T>::const_iterator
1388SdfPathFindLongestStrictPrefix(
1389 std::map<SdfPath, T> const &map, SdfPath const &path)
1390{
1391 return Sdf_PathFindLongestPrefixImpl<
1392 typename std::map<SdfPath, T>::const_iterator,
1393 std::map<SdfPath, T> const &>(map, path, /*strictPrefix=*/true,
1394 TfGet<0>());
1395}
1396template <class T>
1397typename std::map<SdfPath, T>::iterator
1398SdfPathFindLongestStrictPrefix(
1399 std::map<SdfPath, T> &map, SdfPath const &path)
1400{
1401 return Sdf_PathFindLongestPrefixImpl<
1402 typename std::map<SdfPath, T>::iterator,
1403 std::map<SdfPath, T> &>(map, path, /*strictPrefix=*/true,
1404 TfGet<0>());
1405}
1406
1407// A helper function for debugger pretty-printers, etc. This function is *not*
1408// thread-safe. It writes to a static buffer and returns a pointer to it.
1409// Subsequent calls to this function overwrite the memory written in prior
1410// calls. If the given path's string representation exceeds the static buffer
1411// size, return a pointer to a message indicating so.
1412SDF_API
1413char const *
1414Sdf_PathGetDebuggerPathText(SdfPath const &);
1415
1416PXR_NAMESPACE_CLOSE_SCOPE
1417
1418// Sdf_PathNode is not public API, but we need to include it here
1419// so we can inline the ref-counting operations, which must manipulate
1420// its internal _refCount member.
1421#include "pxr/usd/sdf/pathNode.h"
1422
1423PXR_NAMESPACE_OPEN_SCOPE
1424
1425static_assert(Sdf_SizeofPrimPathNode == sizeof(Sdf_PrimPathNode), "");
1426static_assert(Sdf_SizeofPropPathNode == sizeof(Sdf_PrimPropertyPathNode), "");
1427
1428PXR_NAMESPACE_CLOSE_SCOPE
1429
1430#endif // PXR_USD_SDF_PATH_H
Range representing a path and ancestors, and providing methods for iterating over them.
Definition: path.h:1077
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
SDF_API SdfPath MakeAbsolutePath(const SdfPath &anchor) const
Returns the absolute form of this path using anchor as the relative basis.
SDF_API SdfPath GetParentPath() const
Return the path that identifies this path's namespace parent.
SDF_API const std::string & GetString() const
Return the string representation of this path as a std::string.
SDF_API bool IsPrimVariantSelectionPath() const
Returns whether the path identifies a variant selection for a prim.
static SDF_API std::string JoinIdentifier(const TfTokenVector &names)
Join names into a single identifier using the namespace delimiter.
static SDF_API bool IsValidIdentifier(const std::string &name)
Returns whether name is a legal identifier for any path component.
SDF_API SdfPath ReplaceTargetPath(const SdfPath &newTargetPath) const
Replaces the relational attribute's target path.
SDF_API void GetAllTargetPathsRecursively(SdfPathVector *result) const
Returns all the relationship target or connection target paths contained in this path,...
SDF_API SdfPath GetPrimOrPrimVariantSelectionPath() const
Creates a path by stripping all relational attributes, targets, and properties, leaving the nearest p...
SDF_API std::pair< SdfPath, SdfPath > RemoveCommonSuffix(const SdfPath &otherPath, bool stopAtRootPrim=false) const
Find and remove the longest common suffix from two paths.
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 bool IsMapperArgPath() const
Returns whether the path identifies a connection mapper arg.
SDF_API bool IsRelationalAttributePath() const
Returns whether the path identifies a relational attribute.
static SDF_API TfToken StripNamespace(const TfToken &name)
Returns name stripped of any namespaces.
SDF_API bool IsAbsoluteRootOrPrimPath() const
Returns whether the path identifies a prim or the absolute root.
static SDF_API const SdfPath & AbsoluteRootPath()
The absolute path representing the top of the namespace hierarchy.
SDF_API const char * GetText() const
Returns the string representation of this path as a c string.
static SDF_API SdfPathVector GetConciseRelativePaths(const SdfPathVector &paths)
Given some vector of paths, get a vector of concise unambiguous relative paths.
SDF_API std::pair< std::string, std::string > GetVariantSelection() const
Returns the variant selection for this path, if this is a variant selection path.
bool operator<=(const SdfPath &rhs) const
Less than or equal operator.
Definition: path.h:929
SDF_API SdfPath AppendExpression() const
Creates a path by appending an expression element.
SDF_API SdfPath AppendRelationalAttribute(TfToken const &attrName) const
Creates a path by appending an element for attrName to this path.
SDF_API std::string GetElementString() const
Returns an ascii representation of the "terminal" element of this path, which can be used to reconstr...
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:398
SDF_API bool IsAbsolutePath() const
Returns whether the path is absolute.
SDF_API SdfPath GetAbsoluteRootOrPrimPath() const
Creates a path by stripping all properties and relational attributes from this path,...
SDF_API SdfPath AppendPath(const SdfPath &newSuffix) const
Creates a path by appending a given relative path to this path.
SDF_API SdfPath MakeRelativePath(const SdfPath &anchor) const
Returns the relative form of this path using anchor as the relative basis.
static SDF_API const SdfPath & ReflexiveRelativePath()
The relative path representing "self".
bool operator>(const SdfPath &rhs) const
Greater than operator.
Definition: path.h:923
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::vector< std::string > TokenizeIdentifier(const std::string &name)
Tokenizes name by the namespace delimiter.
SDF_API bool IsPropertyPath() const
Returns whether the path identifies a property.
SDF_API SdfPath AppendMapper(const SdfPath &targetPath) const
Creates a path by appending a mapper element for targetPath.
SDF_API SdfPath AppendElementToken(const TfToken &elementTok) const
Like AppendElementString() but take the element as a TfToken.
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.
static SDF_API std::string JoinIdentifier(const std::vector< std::string > &names)
Join names into a single identifier using the namespace delimiter.
SDF_API bool IsTargetPath() const
Returns whether the path identifies a relationship or connection target.
SDF_API size_t GetPathElementCount() const
Returns the number of path elements in this path.
SDF_API TfToken GetElementToken() const
Like GetElementString() but return the value as a TfToken.
static SDF_API const SdfPath & EmptyPath()
The empty path value, equivalent to SdfPath().
SDF_API const std::string & GetName() const
Returns the name of the prim, property or relational attribute identified by the path.
SDF_API TfToken GetAsToken() const
Return the string representation of this path as a TfToken.
SDF_API const SdfPath & GetTargetPath() const
Returns the relational attribute or mapper target path for this path.
SDF_API SdfPathVector GetPrefixes() const
Returns the prefix paths of this path.
static SDF_API std::string StripNamespace(const std::string &name)
Returns name stripped of any namespaces.
SDF_API void GetPrefixes(SdfPathVector *prefixes, size_t numPrefixes) const
Fill prefixes with up to numPrefixes prefixes of this path.
static SDF_API TfTokenVector TokenizeIdentifierAsTokens(const std::string &name)
Tokenizes name by the namespace delimiter.
SDF_API bool IsRootPrimPath() const
Returns whether the path identifies a root prim.
static SDF_API bool IsValidNamespacedIdentifier(const std::string &name)
Returns whether name is a legal namespaced identifier.
SDF_API const TfToken & GetNameToken() const
Returns the name of the prim, property or relational attribute identified by the path,...
SDF_API bool IsPrimPath() const
Returns whether the path identifies a prim.
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 ...
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 AppendProperty(TfToken const &propName) const
Creates a path by appending an element for propName to this path.
SDF_API bool IsExpressionPath() const
Returns whether the path identifies a connection expression.
SDF_API bool IsNamespacedPropertyPath() const
Returns whether the path identifies a namespaced property.
SDF_API SdfPath AppendMapperArg(TfToken const &argName) const
Creates a path by appending an element for argName.
SDF_API TfToken const & GetToken() const
Return the string representation of this path as a TfToken lvalue.
bool operator<(const SdfPath &rhs) const
Comparison operator.
Definition: path.h:910
bool operator>=(const SdfPath &rhs) const
Greater than or equal operator.
Definition: path.h:935
SDF_API SdfPath AppendChild(TfToken const &childName) const
Creates a path by appending an element for childName to this path.
bool ContainsPropertyElements() const
Return true if this path contains any property elements, false otherwise.
Definition: path.h:371
SDF_API bool IsMapperPath() const
Returns whether the path identifies a connection mapper.
static SDF_API void RemoveDescendentPaths(SdfPathVector *paths)
Remove all elements of paths that are prefixed by other elements in paths.
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.
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 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 cons...
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 newPre...
SDF_API TfSpan< SdfPath > GetPrefixes(TfSpan< SdfPath > prefixes) const
Fill prefixes with up to prefixes.size() prefixes of this path.
SDF_API bool IsAbsoluteRootPath() const
Return true if this path is the AbsoluteRootPath().
bool operator==(const SdfPath &rhs) const
Equality operator.
Definition: path.h:897
SDF_API SdfPathAncestorsRange GetAncestorsRange() const
Return a range for iterating over the ancestors of this path.
SDF_API bool ContainsPrimVariantSelection() const
Returns whether the path or any of its parent paths identifies a variant selection for a prim.
SDF_API bool IsPrimPropertyPath() const
Returns whether the path identifies a prim's property.
SDF_API SdfPath StripAllVariantSelections() const
Create a path by stripping all variant selections from all components of this path,...
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 SdfPath ReplaceName(TfToken const &newName) const
Return a copy of this path with its final component changed to newName.
SDF_API void GetPrefixes(SdfPathVector *prefixes) const
Fills prefixes with prefixes of this path.
SDF_API bool IsPrimOrPrimVariantSelectionPath() const
Return true if this path is a prim path or is a prim variant selection path.
SDF_API SdfPath AppendTarget(const SdfPath &targetPath) const
Creates a path by appending an element for targetPath.
SdfPath() noexcept=default
Constructs the default, empty path.
SDF_API SdfPathVector GetPrefixes(size_t numPrefixes) const
Return up to numPrefixes prefix paths of this path.
SDF_API SdfPath GetPrimPath() const
Creates a path by stripping all relational attributes, targets, properties, and variant selections fr...
static SDF_API void RemoveAncestorPaths(SdfPathVector *paths)
Remove all elements of paths that prefix other elements in paths.
bool operator!=(const SdfPath &rhs) const
Inequality operator.
Definition: path.h:902
SDF_API std::string GetAsString() const
Return the string representation of this path as a std::string.
Stores a pointer to a ValueType which uses TfDelegatedCountIncrement and TfDelegatedCountDecrement to...
Function object for retrieving the N'th element of a std::pair or std::tuple.
Definition: stl.h:362
A user-extensible hashing mechanism for use with runtime hash tables.
Definition: hash.h:460
Represents a range of contiguous elements.
Definition: span.h:71
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].
STL namespace.
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440