HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
listOp.h
Go to the documentation of this file.
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_LIST_OP_H
8 #define PXR_USD_SDF_LIST_OP_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/usd/sdf/api.h"
12 #include "pxr/base/tf/token.h"
13 #include "pxr/base/tf/hash.h"
14 
15 #include <functional>
16 #include <iosfwd>
17 #include <list>
18 #include <map>
19 #include <optional>
20 #include <string>
21 #include <vector>
22 
24 
25 /// \enum SdfListOpType
26 ///
27 /// Enum for specifying one of the list editing operation types.
28 ///
36 };
37 
38 /// \struct Sdf_ListOpTraits
39 ///
40 /// Trait classes for specializing behaviors of SdfListOp for a given item
41 /// type.
42 ///
43 template <class T>
45 {
46  typedef std::less<T> ItemComparator;
47 };
48 
49 /// \class SdfListOp
50 ///
51 /// SdfListOp is a value type representing an operation that edits a list.
52 /// It may append or prepend items, delete them, or replace the list entirely.
53 ///
54 /// SdfListOp maintains lists of items to be prepended, appended, deleted, or
55 /// used explicitly. If used in explicit mode, the ApplyOperations method replaces the given list
56 /// with the set explicit items. Otherwise, the ApplyOperations
57 /// method is used to apply the list-editing options in the input list in the
58 /// following order:
59 /// - Delete
60 /// - Prepend
61 /// - Append
62 ///
63 /// Lists are meant to contain unique values, and all list operations
64 /// will remove duplicates if encountered. Prepending items and using
65 /// explicit mode will preserve the position of the first of the duplicates
66 /// to be encountered, while appending items will preserve the last.
67 
68 template <typename T>
69 class SdfListOp {
70 public:
71  typedef T ItemType;
72  typedef std::vector<ItemType> ItemVector;
75 
76  /// Create a ListOp in explicit mode with the given \p explicitItems.
77  SDF_API
79  const ItemVector& explicitItems = ItemVector());
80 
81  /// Create a ListOp in non-explicit mode with the given
82  /// \p prependedItems, \p appendedItems, and \p deletedItems
83  SDF_API
84  static SdfListOp Create(
85  const ItemVector& prependedItems = ItemVector(),
86  const ItemVector& appendedItems = ItemVector(),
87  const ItemVector& deletedItems = ItemVector());
88 
89  /// Create an empty ListOp in non-explicit mode.
91 
92  SDF_API void Swap(SdfListOp<T>& rhs);
93 
94  /// Returns \c true if the editor has an explicit list (even if it's
95  /// empty) or it has any added, prepended, appended, deleted,
96  /// or ordered keys.
97  bool HasKeys() const
98  {
99  if (IsExplicit()) {
100  return true;
101  }
102  if (_addedItems.size() != 0 ||
103  _prependedItems.size() != 0 ||
104  _appendedItems.size() != 0 ||
105  _deletedItems.size() != 0) {
106  return true;
107  }
108  return _orderedItems.size() != 0;
109  }
110 
111  /// Returns \c true if the given item is in any of the item lists.
112  SDF_API bool HasItem(const T& item) const;
113 
114  /// Returns \c true if the list is explicit.
115  bool IsExplicit() const
116  {
117  return _isExplicit;
118  }
119 
120  /// Returns the explicit items.
122  {
123  return _explicitItems;
124  }
125 
126  /// Returns the explicit items.
128  {
129  return _prependedItems;
130  }
131 
132  /// Returns the explicit items.
134  {
135  return _appendedItems;
136  }
137 
138  /// Returns the deleted items.
140  {
141  return _deletedItems;
142  }
143 
144  /// Return the item vector identified by \p type.
146 
147  /// Returns the effective list of items represented by the operations in
148  /// this list op. This function should be used to determine the final list
149  /// of items added instead of looking at the individual explicit, prepended,
150  /// and appended item lists.
151  ///
152  /// This is equivalent to calling ApplyOperations on an empty item vector.
154 
155  /// Sets the explicit items. If duplicates are present in \p items,
156  /// preserves the first occurence.
157  /// Returns true if no duplicates were present, false otherwise. If
158  /// duplicates were present, errMsg is set to indicate which item was duplicated.
159  SDF_API bool SetExplicitItems(const ItemVector &items, std::string* errMsg = nullptr);
160 
161  /// Sets the prepended items. If duplicates are present in \p items,
162  /// preserves the first occurence.
163  /// Returns true if no duplicates were present, false otherwise. If
164  /// duplicates were present, errMsg is set to indicate which item was duplicated.
165  SDF_API bool SetPrependedItems(const ItemVector &items, std::string* errMsg = nullptr);
166 
167  /// Sets the appended items. If duplicates are present in \p items,
168  /// preserves the last occurence.
169  /// Returns true if no duplicates were present, false otherwise. If
170  /// duplicates were present, errMsg is set to indicate which item was duplicated.
171  SDF_API bool SetAppendedItems(const ItemVector &items, std::string* errMsg = nullptr);
172 
173  /// Sets the deleted items. If duplicates are present in \p items,
174  /// preserves the first occurence.
175  /// Returns true if no duplicates were present, false otherwise. If
176  /// duplicates were present, errMsg is set to indicate which item was duplicated.
177  SDF_API bool SetDeletedItems(const ItemVector &items, std::string* errMsg = nullptr);
178 
179  /// Sets the item vector for the given operation \p type.
180  /// Removes duplicates in \p items if present.
181  /// Returns true if no duplicates were present, false otherwise. If
182  /// duplicates were present, errMsg is set to indicate which item was duplicated.
183  SDF_API bool SetItems(const ItemVector &items, SdfListOpType type,
184  std::string* errMsg = nullptr);
185 
186  /// Removes all items and changes the list to be non-explicit.
187  SDF_API void Clear();
188 
189  /// Removes all items and changes the list to be explicit.
191 
192  /// Callback type for ApplyOperations.
193  typedef std::function<
194  std::optional<ItemType>(SdfListOpType, const ItemType&)
196 
197  /// Applies edit operations to the given ItemVector.
198  /// If supplied, \p cb will be called on each item in the operation vectors
199  /// before they are applied to \p vec. Consumers can use this to transform
200  /// the items stored in the operation vectors to match what's stored in
201  /// \p vec.
202  SDF_API
203  void ApplyOperations(ItemVector* vec,
204  const ApplyCallback& cb = ApplyCallback()) const;
205 
206  /// Applies edit operations to the given ListOp.
207  ///
208  /// The result is a ListOp that, when applied to a list, has the same
209  /// effect as applying \p inner and then \p this in sequence.
210  ///
211  /// The result will be empty if the result is not well defined.
212  /// The result is well-defined when \p inner and \p this do not
213  /// use the 'ordered' or 'added' item lists. In other words, only
214  /// the explicit, prepended, appended, and deleted portions of
215  /// SdfListOp are closed under composition with ApplyOperations().
216  SDF_API
217  std::optional<SdfListOp<T>>
218  ApplyOperations(const SdfListOp<T> &inner) const;
219 
220  /// Callback type for ModifyOperations.
221  typedef std::function<
222  std::optional<ItemType>(const ItemType&)
224 
225  /// Modifies operations specified in this object.
226  /// \p callback is called for every item in all operation vectors. If the
227  /// returned key is empty then the key is removed, otherwise it's replaced
228  /// with the returned key.
229  ///
230  /// If \p callback returns a key that was previously returned for the
231  /// current operation vector being processed, the returned key will be
232  /// removed.
233  ///
234  /// Returns true if a change was made, false otherwise.
235  SDF_API
236  bool ModifyOperations(const ModifyCallback& callback);
237 
238  /// \deprecated Please use ModifyOperations(const ModifyCallback& callback)
239  /// instead.
240  SDF_API
241  bool ModifyOperations(const ModifyCallback& callback,
242  bool unusedRemoveDuplicates);
243 
244  /// Replaces the items in the specified operation vector in the range
245  /// (index, index + n] with the given \p newItems. If \p newItems is empty
246  /// the items in the range will simply be removed.
247  SDF_API
248  bool ReplaceOperations(const SdfListOpType op, size_t index, size_t n,
249  const ItemVector& newItems);
250 
251  /// Composes a stronger SdfListOp's opinions for a given operation list
252  /// over this one.
253  SDF_API
254  void ComposeOperations(const SdfListOp<T>& stronger, SdfListOpType op);
255 
256  /// \deprecated The add and reorder operations have been deprecated in favor
257  /// of the append and prepend operations.
258  const ItemVector& GetAddedItems() const
259  {
260  return _addedItems;
261  }
262 
263  /// \deprecated The add and reorder operations have been deprecated in favor
264  /// of the append and prepend operations.
266  {
267  return _orderedItems;
268  }
269  /// \deprecated The add and reorder operations have been deprecated in favor
270  /// of the append and prepend operations.
271  SDF_API void SetAddedItems(const ItemVector &items);
272 
273  /// \deprecated The add and reorder operations have been deprecated in favor
274  /// of the append and prepend operations.
275  SDF_API void SetOrderedItems(const ItemVector &items);
276 
277  friend inline size_t hash_value(const SdfListOp &op) {
278  return TfHash::Combine(
279  op._isExplicit,
280  op._explicitItems,
281  op._addedItems,
282  op._prependedItems,
283  op._appendedItems,
284  op._deletedItems,
285  op._orderedItems
286  );
287  }
288 
289  bool operator==(const SdfListOp<T> &rhs) const {
290  return _isExplicit == rhs._isExplicit &&
291  _explicitItems == rhs._explicitItems &&
292  _addedItems == rhs._addedItems &&
293  _prependedItems == rhs._prependedItems &&
294  _appendedItems == rhs._appendedItems &&
295  _deletedItems == rhs._deletedItems &&
296  _orderedItems == rhs._orderedItems;
297  };
298 
299  bool operator!=(const SdfListOp<T> &rhs) const {
300  return !(*this == rhs);
301  };
302 
303 private:
304  void _SetExplicit(bool isExplicit);
305 
306  typedef typename Sdf_ListOpTraits<T>::ItemComparator _ItemComparator;
307  typedef std::list<ItemType> _ApplyList;
308  typedef std::map<ItemType, typename _ApplyList::iterator, _ItemComparator>
309  _ApplyMap;
310 
311  void _PrependKeys(const ApplyCallback& cb,
312  _ApplyList* result, _ApplyMap* search) const;
313  void _AppendKeys(const ApplyCallback& cb,
314  _ApplyList* result, _ApplyMap* search) const;
315  void _DeleteKeys(const ApplyCallback& cb,
316  _ApplyList* result, _ApplyMap* search) const;
317 
318  /// \deprecated
319  /// Use _PrependKeys or _AppendKeys instead.
320  void _AddKeys(SdfListOpType, const ApplyCallback& cb,
321  _ApplyList* result, _ApplyMap* search) const;
322 
323  /// \deprecated
324  /// Use _PrependKeys or _AppendKeys instead.
325  void _ReorderKeys(const ApplyCallback& cb,
326  _ApplyList* result, _ApplyMap* search) const;
327  static void _ReorderKeysHelper(ItemVector order, const ApplyCallback& cb,
328  _ApplyList *result, _ApplyMap *search);
329  template <class ItemType>
330  friend void SdfApplyListOrdering(std::vector<ItemType> *v,
331  const std::vector<ItemType> &order);
332  bool _MakeUnique(std::vector<T>& items, bool reverse=false,
333  std::string* errMsg = nullptr);
334 
335 private:
336  bool _isExplicit;
337  ItemVector _explicitItems;
338  ItemVector _addedItems;
339  ItemVector _prependedItems;
340  ItemVector _appendedItems;
341  ItemVector _deletedItems;
342  ItemVector _orderedItems;
343 };
344 
345 // ADL swap.
346 template <class T>
348 {
349  x.Swap(y);
350 }
351 
352 // Helper function for applying an ordering operation described by \p orderVector
353 // to vector \p v.
354 template <class ItemType>
355 SDF_API
356 void SdfApplyListOrdering(std::vector<ItemType>* v,
357  const std::vector<ItemType>& order);
358 
359 // Ostream output methods for list values (useful for debugging and required
360 // for storing a list value in a VtValue).
361 template <typename T>
362 SDF_API
363 std::ostream & operator<<( std::ostream &, const SdfListOp<T> & );
364 
365 // Concrete, instantiated listop types.
366 typedef class SdfListOp<int> SdfIntListOp;
367 typedef class SdfListOp<unsigned int> SdfUIntListOp;
368 typedef class SdfListOp<int64_t> SdfInt64ListOp;
369 typedef class SdfListOp<uint64_t> SdfUInt64ListOp;
371 typedef class SdfListOp<std::string> SdfStringListOp;
372 typedef class SdfListOp<class SdfPath> SdfPathListOp;
373 typedef class SdfListOp<class SdfReference> SdfReferenceListOp;
374 typedef class SdfListOp<class SdfPayload> SdfPayloadListOp;
375 typedef class SdfListOp<class SdfUnregisteredValue> SdfUnregisteredValueListOp;
376 
378 
379 #endif // PXR_USD_SDF_LIST_OP_H
SDF_API bool SetItems(const ItemVector &items, SdfListOpType type, std::string *errMsg=nullptr)
void swap(ArAssetInfo &lhs, ArAssetInfo &rhs)
Definition: assetInfo.h:57
SDF_API bool SetAppendedItems(const ItemVector &items, std::string *errMsg=nullptr)
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
ItemVector value_vector_type
Definition: listOp.h:74
const ItemVector & GetPrependedItems() const
Returns the explicit items.
Definition: listOp.h:127
SDF_API void ComposeOperations(const SdfListOp< T > &stronger, SdfListOpType op)
const ItemVector & GetExplicitItems() const
Returns the explicit items.
Definition: listOp.h:121
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:632
const ItemVector & GetAppendedItems() const
Returns the explicit items.
Definition: listOp.h:133
const GLdouble * v
Definition: glcorearb.h:837
SDF_API const ItemVector & GetItems(SdfListOpType type) const
Return the item vector identified by type.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
SDF_API bool ReplaceOperations(const SdfListOpType op, size_t index, size_t n, const ItemVector &newItems)
class SdfListOp< class SdfReference > SdfReferenceListOp
Definition: listOp.h:373
SDF_API void ClearAndMakeExplicit()
Removes all items and changes the list to be explicit.
PUGI__FN void reverse(I begin, I end)
Definition: pugixml.cpp:7458
friend void SdfApplyListOrdering(std::vector< ItemType > *v, const std::vector< ItemType > &order)
GLint y
Definition: glcorearb.h:103
**But if you need a result
Definition: thread.h:622
class SdfListOp< uint64_t > SdfUInt64ListOp
Definition: listOp.h:369
SDF_API void Swap(SdfListOp< T > &rhs)
class SdfListOp< class SdfPayload > SdfPayloadListOp
Definition: listOp.h:374
class SdfListOp< class SdfUnregisteredValue > SdfUnregisteredValueListOp
Definition: listOp.h:375
std::function< std::optional< ItemType >const ItemType &) > ModifyCallback
Callback type for ModifyOperations.
Definition: listOp.h:223
class SdfListOp< class SdfPath > SdfPathListOp
Definition: listOp.h:372
GLdouble n
Definition: glcorearb.h:2008
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:108
Definition: token.h:70
SDF_API bool ModifyOperations(const ModifyCallback &callback)
T ItemType
Definition: listOp.h:71
class SdfListOp< int > SdfIntListOp
Definition: listOp.h:366
const ItemVector & GetOrderedItems() const
Definition: listOp.h:265
const ItemVector & GetAddedItems() const
Definition: listOp.h:258
SdfListOpType
Definition: listOp.h:29
bool HasKeys() const
Definition: listOp.h:97
SDF_API bool SetExplicitItems(const ItemVector &items, std::string *errMsg=nullptr)
const ItemVector & GetDeletedItems() const
Returns the deleted items.
Definition: listOp.h:139
SDF_API ItemVector GetAppliedItems() const
GLdouble GLdouble GLint GLint order
Definition: glad.h:2676
class SdfListOp< std::string > SdfStringListOp
Definition: listOp.h:371
SDF_API bool SetDeletedItems(const ItemVector &items, std::string *errMsg=nullptr)
SDF_API bool SetPrependedItems(const ItemVector &items, std::string *errMsg=nullptr)
SDF_API void SetOrderedItems(const ItemVector &items)
SDF_API void Clear()
Removes all items and changes the list to be non-explicit.
class SdfListOp< int64_t > SdfInt64ListOp
Definition: listOp.h:368
class SdfListOp< TfToken > SdfTokenListOp
Definition: listOp.h:370
GLint GLenum GLint x
Definition: glcorearb.h:409
auto search(const T &set, const V &val) -> std::pair< bool, decltype(std::begin(detail::smart_deref(set)))>
A search function.
Definition: CLI11.h:3170
class SdfListOp< unsigned int > SdfUIntListOp
Definition: listOp.h:367
SDF_API SdfListOp()
Create an empty ListOp in non-explicit mode.
bool operator!=(const SdfListOp< T > &rhs) const
Definition: listOp.h:299
#define SDF_API
Definition: api.h:23
static size_t Combine(Args &&...args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:487
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
SDF_API void SetAddedItems(const ItemVector &items)
SDF_API void ApplyOperations(ItemVector *vec, const ApplyCallback &cb=ApplyCallback()) const
static SDF_API SdfListOp CreateExplicit(const ItemVector &explicitItems=ItemVector())
Create a ListOp in explicit mode with the given explicitItems.
SDF_API void SdfApplyListOrdering(std::vector< ItemType > *v, const std::vector< ItemType > &order)
GLuint index
Definition: glcorearb.h:786
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
std::vector< ItemType > ItemVector
Definition: listOp.h:72
static SDF_API SdfListOp Create(const ItemVector &prependedItems=ItemVector(), const ItemVector &appendedItems=ItemVector(), const ItemVector &deletedItems=ItemVector())
bool operator==(const SdfListOp< T > &rhs) const
Definition: listOp.h:289
std::function< std::optional< ItemType >SdfListOpType, const ItemType &) > ApplyCallback
Callback type for ApplyOperations.
Definition: listOp.h:195
std::less< T > ItemComparator
Definition: listOp.h:46
ItemType value_type
Definition: listOp.h:73
SDF_API bool HasItem(const T &item) const
Returns true if the given item is in any of the item lists.
bool IsExplicit() const
Returns true if the list is explicit.
Definition: listOp.h:115
friend size_t hash_value(const SdfListOp &op)
Definition: listOp.h:277