This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
listOp.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_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
23PXR_NAMESPACE_OPEN_SCOPE
24
29enum SdfListOpType {
30 SdfListOpTypeExplicit,
31 SdfListOpTypeAdded,
32 SdfListOpTypeDeleted,
33 SdfListOpTypeOrdered,
34 SdfListOpTypePrepended,
35 SdfListOpTypeAppended
36};
37
43template <class T>
44struct Sdf_ListOpTraits
45{
46 typedef std::less<T> ItemComparator;
47};
48
67
68template <typename T>
69class SdfListOp {
70public:
71 typedef T ItemType;
72 typedef std::vector<ItemType> ItemVector;
73 typedef ItemType value_type;
74 typedef ItemVector value_vector_type;
75
77 SDF_API
79 const ItemVector& explicitItems = ItemVector());
80
83 SDF_API
85 const ItemVector& prependedItems = ItemVector(),
86 const ItemVector& appendedItems = ItemVector(),
87 const ItemVector& deletedItems = ItemVector());
88
90 SDF_API SdfListOp();
91
92 SDF_API void Swap(SdfListOp<T>& rhs);
93
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
112 SDF_API bool HasItem(const T& item) const;
113
115 bool IsExplicit() const
116 {
117 return _isExplicit;
118 }
119
121 const ItemVector& GetExplicitItems() const
122 {
123 return _explicitItems;
124 }
125
127 const ItemVector& GetPrependedItems() const
128 {
129 return _prependedItems;
130 }
131
133 const ItemVector& GetAppendedItems() const
134 {
135 return _appendedItems;
136 }
137
139 const ItemVector& GetDeletedItems() const
140 {
141 return _deletedItems;
142 }
143
145 SDF_API const ItemVector& GetItems(SdfListOpType type) const;
146
153 SDF_API ItemVector GetAppliedItems() const;
154
157 SDF_API void SetExplicitItems(const ItemVector &items);
158
161 SDF_API void SetPrependedItems(const ItemVector &items);
162
165 SDF_API void SetAppendedItems(const ItemVector &items);
166
169 SDF_API void SetDeletedItems(const ItemVector &items);
170
173 SDF_API void SetItems(const ItemVector &items, SdfListOpType type);
174
176 SDF_API void Clear();
177
179 SDF_API void ClearAndMakeExplicit();
180
182 typedef std::function<
183 std::optional<ItemType>(SdfListOpType, const ItemType&)
185
191 SDF_API
192 void ApplyOperations(ItemVector* vec,
193 const ApplyCallback& cb = ApplyCallback()) const;
194
205 SDF_API
206 std::optional<SdfListOp<T>>
207 ApplyOperations(const SdfListOp<T> &inner) const;
208
210 typedef std::function<
211 std::optional<ItemType>(const ItemType&)
213
224 SDF_API
225 bool ModifyOperations(const ModifyCallback& callback);
226
229 SDF_API
230 bool ModifyOperations(const ModifyCallback& callback,
231 bool unusedRemoveDuplicates);
232
236 SDF_API
237 bool ReplaceOperations(const SdfListOpType op, size_t index, size_t n,
238 const ItemVector& newItems);
239
242 SDF_API
243 void ComposeOperations(const SdfListOp<T>& stronger, SdfListOpType op);
244
247 const ItemVector& GetAddedItems() const
248 {
249 return _addedItems;
250 }
251
254 const ItemVector& GetOrderedItems() const
255 {
256 return _orderedItems;
257 }
260 SDF_API void SetAddedItems(const ItemVector &items);
261
264 SDF_API void SetOrderedItems(const ItemVector &items);
265
266 friend inline size_t hash_value(const SdfListOp &op) {
267 return TfHash::Combine(
268 op._isExplicit,
269 op._explicitItems,
270 op._addedItems,
271 op._prependedItems,
272 op._appendedItems,
273 op._deletedItems,
274 op._orderedItems
275 );
276 }
277
278 bool operator==(const SdfListOp<T> &rhs) const {
279 return _isExplicit == rhs._isExplicit &&
280 _explicitItems == rhs._explicitItems &&
281 _addedItems == rhs._addedItems &&
282 _prependedItems == rhs._prependedItems &&
283 _appendedItems == rhs._appendedItems &&
284 _deletedItems == rhs._deletedItems &&
285 _orderedItems == rhs._orderedItems;
286 };
287
288 bool operator!=(const SdfListOp<T> &rhs) const {
289 return !(*this == rhs);
290 };
291
292private:
293 void _SetExplicit(bool isExplicit);
294
295 typedef typename Sdf_ListOpTraits<T>::ItemComparator _ItemComparator;
296 typedef std::list<ItemType> _ApplyList;
297 typedef std::map<ItemType, typename _ApplyList::iterator, _ItemComparator>
298 _ApplyMap;
299
300 void _PrependKeys(const ApplyCallback& cb,
301 _ApplyList* result, _ApplyMap* search) const;
302 void _AppendKeys(const ApplyCallback& cb,
303 _ApplyList* result, _ApplyMap* search) const;
304 void _DeleteKeys(const ApplyCallback& cb,
305 _ApplyList* result, _ApplyMap* search) const;
306
309 void _AddKeys(SdfListOpType, const ApplyCallback& cb,
310 _ApplyList* result, _ApplyMap* search) const;
311
314 void _ReorderKeys(const ApplyCallback& cb,
315 _ApplyList* result, _ApplyMap* search) const;
316 static void _ReorderKeysHelper(ItemVector order, const ApplyCallback& cb,
317 _ApplyList *result, _ApplyMap *search);
318 template <class ItemType>
319 friend void SdfApplyListOrdering(std::vector<ItemType> *v,
320 const std::vector<ItemType> &order);
321
322private:
323 bool _isExplicit;
324 ItemVector _explicitItems;
325 ItemVector _addedItems;
326 ItemVector _prependedItems;
327 ItemVector _appendedItems;
328 ItemVector _deletedItems;
329 ItemVector _orderedItems;
330};
331
332// ADL swap.
333template <class T>
334void swap(SdfListOp<T> &x, SdfListOp<T> &y)
335{
336 x.Swap(y);
337}
338
339// Helper function for applying an ordering operation described by \p orderVector
340// to vector \p v.
341template <class ItemType>
342SDF_API
343void SdfApplyListOrdering(std::vector<ItemType>* v,
344 const std::vector<ItemType>& order);
345
346// Ostream output methods for list values (useful for debugging and required
347// for storing a list value in a VtValue).
348template <typename T>
349SDF_API
350std::ostream & operator<<( std::ostream &, const SdfListOp<T> & );
351
352// Concrete, instantiated listop types.
353typedef class SdfListOp<int> SdfIntListOp;
354typedef class SdfListOp<unsigned int> SdfUIntListOp;
355typedef class SdfListOp<int64_t> SdfInt64ListOp;
356typedef class SdfListOp<uint64_t> SdfUInt64ListOp;
357typedef class SdfListOp<TfToken> SdfTokenListOp;
358typedef class SdfListOp<std::string> SdfStringListOp;
359typedef class SdfListOp<class SdfPath> SdfPathListOp;
360typedef class SdfListOp<class SdfReference> SdfReferenceListOp;
361typedef class SdfListOp<class SdfPayload> SdfPayloadListOp;
362typedef class SdfListOp<class SdfUnregisteredValue> SdfUnregisteredValueListOp;
363
364PXR_NAMESPACE_CLOSE_SCOPE
365
366#endif // PXR_USD_SDF_LIST_OP_H
SdfListOp is a value type representing an operation that edits a list.
Definition: listOp.h:69
SDF_API bool HasItem(const T &item) const
Returns true if the given item is in any of the item lists.
static SDF_API SdfListOp CreateExplicit(const ItemVector &explicitItems=ItemVector())
Create a ListOp in explicit mode with the given explicitItems.
SDF_API void SetAppendedItems(const ItemVector &items)
Sets the appended items.
SDF_API std::optional< SdfListOp< T > > ApplyOperations(const SdfListOp< T > &inner) const
Applies edit operations to the given ListOp.
SDF_API bool ModifyOperations(const ModifyCallback &callback, bool unusedRemoveDuplicates)
SDF_API void SetOrderedItems(const ItemVector &items)
std::function< std::optional< ItemType >(const ItemType &) > ModifyCallback
Callback type for ModifyOperations.
Definition: listOp.h:212
SDF_API bool ModifyOperations(const ModifyCallback &callback)
Modifies operations specified in this object.
SDF_API void SetAddedItems(const ItemVector &items)
SDF_API void SetExplicitItems(const ItemVector &items)
Sets the explicit items.
SDF_API void SetPrependedItems(const ItemVector &items)
Sets the prepended items.
SDF_API void SetDeletedItems(const ItemVector &items)
Sets the deleted items.
const ItemVector & GetOrderedItems() const
Definition: listOp.h:254
static SDF_API SdfListOp Create(const ItemVector &prependedItems=ItemVector(), const ItemVector &appendedItems=ItemVector(), const ItemVector &deletedItems=ItemVector())
Create a ListOp in non-explicit mode with the given prependedItems, appendedItems,...
const ItemVector & GetDeletedItems() const
Returns the deleted items.
Definition: listOp.h:139
SDF_API const ItemVector & GetItems(SdfListOpType type) const
Return the item vector identified by type.
bool IsExplicit() const
Returns true if the list is explicit.
Definition: listOp.h:115
SDF_API void Clear()
Removes all items and changes the list to be non-explicit.
const ItemVector & GetPrependedItems() const
Returns the explicit items.
Definition: listOp.h:127
const ItemVector & GetExplicitItems() const
Returns the explicit items.
Definition: listOp.h:121
SDF_API bool ReplaceOperations(const SdfListOpType op, size_t index, size_t n, const ItemVector &newItems)
Replaces the items in the specified operation vector in the range (index, index + n] with the given n...
SDF_API SdfListOp()
Create an empty ListOp in non-explicit mode.
SDF_API void SetItems(const ItemVector &items, SdfListOpType type)
Sets the item vector for the given operation type.
SDF_API void ApplyOperations(ItemVector *vec, const ApplyCallback &cb=ApplyCallback()) const
Applies edit operations to the given ItemVector.
SDF_API void ClearAndMakeExplicit()
Removes all items and changes the list to be explicit.
SDF_API void ComposeOperations(const SdfListOp< T > &stronger, SdfListOpType op)
Composes a stronger SdfListOp's opinions for a given operation list over this one.
bool HasKeys() const
Returns true if the editor has an explicit list (even if it's empty) or it has any added,...
Definition: listOp.h:97
const ItemVector & GetAppendedItems() const
Returns the explicit items.
Definition: listOp.h:133
SDF_API ItemVector GetAppliedItems() const
Returns the effective list of items represented by the operations in this list op.
std::function< std::optional< ItemType >(SdfListOpType, const ItemType &) > ApplyCallback
Callback type for ApplyOperations.
Definition: listOp.h:184
const ItemVector & GetAddedItems() const
Definition: listOp.h:247
static size_t Combine(Args &&... args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:475
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...