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 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_LIST_OP_H
25 #define PXR_USD_SDF_LIST_OP_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/sdf/api.h"
29 #include "pxr/base/tf/token.h"
30 #include "pxr/base/tf/hash.h"
31 
32 #include <functional>
33 #include <iosfwd>
34 #include <list>
35 #include <map>
36 #include <optional>
37 #include <string>
38 #include <vector>
39 
41 
42 /// \enum SdfListOpType
43 ///
44 /// Enum for specifying one of the list editing operation types.
45 ///
53 };
54 
55 /// \struct Sdf_ListOpTraits
56 ///
57 /// Trait classes for specializing behaviors of SdfListOp for a given item
58 /// type.
59 ///
60 template <class T>
62 {
63  typedef std::less<T> ItemComparator;
64 };
65 
66 /// \class SdfListOp
67 ///
68 /// Value type representing a list-edit operation.
69 ///
70 /// SdfListOp is a value type representing an operation that edits a list.
71 /// It may add or remove items, reorder them, or replace the list entirely.
72 ///
73 template <typename T>
74 class SdfListOp {
75 public:
76  typedef T ItemType;
77  typedef std::vector<ItemType> ItemVector;
80 
81  /// Create a ListOp in explicit mode with the given \p explicitItems.
82  SDF_API
84  const ItemVector& explicitItems = ItemVector());
85 
86  /// Create a ListOp in non-explicit mode with the given
87  /// \p prependedItems, \p appendedItems, and \p deletedItems
88  SDF_API
89  static SdfListOp Create(
90  const ItemVector& prependedItems = ItemVector(),
91  const ItemVector& appendedItems = ItemVector(),
92  const ItemVector& deletedItems = ItemVector());
93 
94  /// Create an empty ListOp in non-explicit mode.
96 
97  SDF_API void Swap(SdfListOp<T>& rhs);
98 
99  /// Returns \c true if the editor has an explicit list (even if it's
100  /// empty) or it has any added, prepended, appended, deleted,
101  /// or ordered keys.
102  bool HasKeys() const
103  {
104  if (IsExplicit()) {
105  return true;
106  }
107  if (_addedItems.size() != 0 ||
108  _prependedItems.size() != 0 ||
109  _appendedItems.size() != 0 ||
110  _deletedItems.size() != 0) {
111  return true;
112  }
113  return _orderedItems.size() != 0;
114  }
115 
116  /// Returns \c true if the given item is in any of the item lists.
117  SDF_API bool HasItem(const T& item) const;
118 
119  /// Returns \c true if the list is explicit.
120  bool IsExplicit() const
121  {
122  return _isExplicit;
123  }
124 
125  /// Returns the explicit items.
127  {
128  return _explicitItems;
129  }
130 
131  /// Returns the explicit items.
132  const ItemVector& GetAddedItems() const
133  {
134  return _addedItems;
135  }
136 
137  /// Returns the explicit items.
139  {
140  return _prependedItems;
141  }
142 
143  /// Returns the explicit items.
145  {
146  return _appendedItems;
147  }
148 
149  /// Returns the deleted items.
151  {
152  return _deletedItems;
153  }
154 
155  /// Returns the ordered items.
157  {
158  return _orderedItems;
159  }
160 
161  /// Return the item vector identified by \p type.
163 
164  /// Returns the effective list of items represented by the operations in
165  /// this list op. This function should be used to determine the final list
166  /// of items added instead of looking at the individual explicit, prepended,
167  /// and appended item lists.
168  ///
169  /// This is equivalent to calling ApplyOperations on an empty item vector.
171 
172  SDF_API void SetExplicitItems(const ItemVector &items);
173  SDF_API void SetAddedItems(const ItemVector &items);
174  SDF_API void SetPrependedItems(const ItemVector &items);
175  SDF_API void SetAppendedItems(const ItemVector &items);
176  SDF_API void SetDeletedItems(const ItemVector &items);
177  SDF_API void SetOrderedItems(const ItemVector &items);
178 
179  /// Sets the item vector for the given operation \p type.
180  SDF_API void SetItems(const ItemVector &items, SdfListOpType type);
181 
182  /// Removes all items and changes the list to be non-explicit.
183  SDF_API void Clear();
184 
185  /// Removes all items and changes the list to be explicit.
187 
188  /// Callback type for ApplyOperations.
189  typedef std::function<
190  std::optional<ItemType>(SdfListOpType, const ItemType&)
192 
193  /// Applies edit operations to the given ItemVector.
194  /// If supplied, \p cb will be called on each item in the operation vectors
195  /// before they are applied to \p vec. Consumers can use this to transform
196  /// the items stored in the operation vectors to match what's stored in
197  /// \p vec.
198  SDF_API
199  void ApplyOperations(ItemVector* vec,
200  const ApplyCallback& cb = ApplyCallback()) const;
201 
202  /// Applies edit operations to the given ListOp.
203  ///
204  /// The result is a ListOp that, when applied to a list, has the same
205  /// effect as applying \p inner and then \p this in sequence.
206  ///
207  /// The result will be empty if the result is not well defined.
208  /// The result is well-defined when \p inner and \p this do not
209  /// use the 'ordered' or 'added' item lists. In other words, only
210  /// the explicit, prepended, appended, and deleted portions of
211  /// SdfListOp are closed under composition with ApplyOperations().
212  SDF_API
213  std::optional<SdfListOp<T>>
214  ApplyOperations(const SdfListOp<T> &inner) const;
215 
216  /// Callback type for ModifyOperations.
217  typedef std::function<
218  std::optional<ItemType>(const ItemType&)
220 
221  /// Modifies operations specified in this object.
222  /// \p callback is called for every item in all operation vectors. If the
223  /// returned key is empty then the key is removed, otherwise it's replaced
224  /// with the returned key.
225  ///
226  /// If \p removeDuplicates is \c true and \p callback returns a key that was
227  /// previously returned for the current operation vector being processed,
228  /// the returned key will be removed.
229  ///
230  /// Returns true if a change was made, false otherwise.
231  SDF_API
232  bool ModifyOperations(const ModifyCallback& callback,
233  bool removeDuplicates = false);
234 
235  /// Replaces the items in the specified operation vector in the range
236  /// (index, index + n] with the given \p newItems. If \p newItems is empty
237  /// the items in the range will simply be removed.
238  SDF_API
239  bool ReplaceOperations(const SdfListOpType op, size_t index, size_t n,
240  const ItemVector& newItems);
241 
242  /// Composes a stronger SdfListOp's opinions for a given operation list
243  /// over this one.
244  SDF_API
245  void ComposeOperations(const SdfListOp<T>& stronger, SdfListOpType op);
246 
247  friend inline size_t hash_value(const SdfListOp &op) {
248  return TfHash::Combine(
249  op._isExplicit,
250  op._explicitItems,
251  op._addedItems,
252  op._prependedItems,
253  op._appendedItems,
254  op._deletedItems,
255  op._orderedItems
256  );
257  }
258 
259  bool operator==(const SdfListOp<T> &rhs) const {
260  return _isExplicit == rhs._isExplicit &&
261  _explicitItems == rhs._explicitItems &&
262  _addedItems == rhs._addedItems &&
263  _prependedItems == rhs._prependedItems &&
264  _appendedItems == rhs._appendedItems &&
265  _deletedItems == rhs._deletedItems &&
266  _orderedItems == rhs._orderedItems;
267  };
268 
269  bool operator!=(const SdfListOp<T> &rhs) const {
270  return !(*this == rhs);
271  };
272 
273 private:
274  void _SetExplicit(bool isExplicit);
275 
276  typedef typename Sdf_ListOpTraits<T>::ItemComparator _ItemComparator;
277  typedef std::list<ItemType> _ApplyList;
278  typedef std::map<ItemType, typename _ApplyList::iterator, _ItemComparator>
279  _ApplyMap;
280 
281  void _AddKeys(SdfListOpType, const ApplyCallback& cb,
282  _ApplyList* result, _ApplyMap* search) const;
283  void _PrependKeys(SdfListOpType, const ApplyCallback& cb,
284  _ApplyList* result, _ApplyMap* search) const;
285  void _AppendKeys(SdfListOpType, const ApplyCallback& cb,
286  _ApplyList* result, _ApplyMap* search) const;
287  void _DeleteKeys(SdfListOpType, const ApplyCallback& cb,
288  _ApplyList* result, _ApplyMap* search) const;
289  void _ReorderKeys(SdfListOpType, const ApplyCallback& cb,
290  _ApplyList* result, _ApplyMap* search) const;
291 
292 private:
293  bool _isExplicit;
294  ItemVector _explicitItems;
295  ItemVector _addedItems;
296  ItemVector _prependedItems;
297  ItemVector _appendedItems;
298  ItemVector _deletedItems;
299  ItemVector _orderedItems;
300 };
301 
302 // ADL swap.
303 template <class T>
305 {
306  x.Swap(y);
307 }
308 
309 // Helper function for applying an ordering operation described by \p orderVector
310 // to vector \p v.
311 template <class ItemType>
312 SDF_API
313 void SdfApplyListOrdering(std::vector<ItemType>* v,
314  const std::vector<ItemType>& order);
315 
316 // Ostream output methods for list values (useful for debugging and required
317 // for storing a list value in a VtValue).
318 template <typename T>
319 SDF_API
320 std::ostream & operator<<( std::ostream &, const SdfListOp<T> & );
321 
322 // Concrete, instantiated listop types.
323 typedef class SdfListOp<int> SdfIntListOp;
324 typedef class SdfListOp<unsigned int> SdfUIntListOp;
325 typedef class SdfListOp<int64_t> SdfInt64ListOp;
326 typedef class SdfListOp<uint64_t> SdfUInt64ListOp;
328 typedef class SdfListOp<std::string> SdfStringListOp;
329 typedef class SdfListOp<class SdfPath> SdfPathListOp;
330 typedef class SdfListOp<class SdfReference> SdfReferenceListOp;
331 typedef class SdfListOp<class SdfPayload> SdfPayloadListOp;
332 typedef class SdfListOp<class SdfUnregisteredValue> SdfUnregisteredValueListOp;
333 
335 
336 #endif // PXR_USD_SDF_LIST_OP_H
void swap(ArAssetInfo &lhs, ArAssetInfo &rhs)
Definition: assetInfo.h:74
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
ItemVector value_vector_type
Definition: listOp.h:79
const ItemVector & GetPrependedItems() const
Returns the explicit items.
Definition: listOp.h:138
SDF_API void ComposeOperations(const SdfListOp< T > &stronger, SdfListOpType op)
const ItemVector & GetExplicitItems() const
Returns the explicit items.
Definition: listOp.h:126
*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:623
const ItemVector & GetAppendedItems() const
Returns the explicit items.
Definition: listOp.h:144
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:330
SDF_API void ClearAndMakeExplicit()
Removes all items and changes the list to be explicit.
GLint y
Definition: glcorearb.h:103
**But if you need a result
Definition: thread.h:613
class SdfListOp< uint64_t > SdfUInt64ListOp
Definition: listOp.h:326
SDF_API void Swap(SdfListOp< T > &rhs)
class SdfListOp< class SdfPayload > SdfPayloadListOp
Definition: listOp.h:331
class SdfListOp< class SdfUnregisteredValue > SdfUnregisteredValueListOp
Definition: listOp.h:332
std::function< std::optional< ItemType >const ItemType &) > ModifyCallback
Callback type for ModifyOperations.
Definition: listOp.h:219
class SdfListOp< class SdfPath > SdfPathListOp
Definition: listOp.h:329
GLdouble n
Definition: glcorearb.h:2008
Definition: token.h:87
T ItemType
Definition: listOp.h:76
class SdfListOp< int > SdfIntListOp
Definition: listOp.h:323
const ItemVector & GetOrderedItems() const
Returns the ordered items.
Definition: listOp.h:156
const ItemVector & GetAddedItems() const
Returns the explicit items.
Definition: listOp.h:132
SdfListOpType
Definition: listOp.h:46
bool HasKeys() const
Definition: listOp.h:102
const ItemVector & GetDeletedItems() const
Returns the deleted items.
Definition: listOp.h:150
SDF_API ItemVector GetAppliedItems() const
GLdouble GLdouble GLint GLint order
Definition: glad.h:2676
class SdfListOp< std::string > SdfStringListOp
Definition: listOp.h:328
SDF_API void SetOrderedItems(const ItemVector &items)
SDF_API void SetExplicitItems(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:325
class SdfListOp< TfToken > SdfTokenListOp
Definition: listOp.h:327
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:324
SDF_API SdfListOp()
Create an empty ListOp in non-explicit mode.
bool operator!=(const SdfListOp< T > &rhs) const
Definition: listOp.h:269
#define SDF_API
Definition: api.h:40
static size_t Combine(Args &&...args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:492
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
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:91
SDF_API bool ModifyOperations(const ModifyCallback &callback, bool removeDuplicates=false)
std::vector< ItemType > ItemVector
Definition: listOp.h:77
SDF_API void SetDeletedItems(const ItemVector &items)
SDF_API void SetItems(const ItemVector &items, SdfListOpType type)
Sets the item vector for the given operation type.
static SDF_API SdfListOp Create(const ItemVector &prependedItems=ItemVector(), const ItemVector &appendedItems=ItemVector(), const ItemVector &deletedItems=ItemVector())
SDF_API void SetPrependedItems(const ItemVector &items)
bool operator==(const SdfListOp< T > &rhs) const
Definition: listOp.h:259
std::function< std::optional< ItemType >SdfListOpType, const ItemType &) > ApplyCallback
Callback type for ApplyOperations.
Definition: listOp.h:191
std::less< T > ItemComparator
Definition: listOp.h:63
ItemType value_type
Definition: listOp.h:78
type
Definition: core.h:1059
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:120
SDF_API void SetAppendedItems(const ItemVector &items)
friend size_t hash_value(const SdfListOp &op)
Definition: listOp.h:247