HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stl.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_BASE_TF_STL_H
25 #define PXR_BASE_TF_STL_H
26 
27 /// \file tf/stl.h
28 /// \ingroup group_tf_Stl
29 
30 #include "pxr/pxr.h"
31 
32 #include "pxr/base/tf/api.h"
33 #include "pxr/base/tf/tf.h"
34 #include "pxr/base/tf/hashmap.h"
35 #include "pxr/base/tf/hashset.h"
36 #include "pxr/base/tf/iterator.h"
37 
38 #include <hboost/call_traits.hpp>
39 
40 #include <algorithm>
41 #include <iterator>
42 #include <map>
43 #include <set>
44 #include <utility>
45 
47 
48 // Helper for TfMapLookup(). Uses std::map API to get a value by key.
49 template <class T>
51  typedef T Container;
52 
53  template <class Key, class Result>
54  static bool Lookup(Container const& map, Key const &key, Result* valuePtr)
55  {
56  typename Container::const_iterator i = map.find(key);
57  if (i == map.end()) {
58  return false;
59  }
60  else {
61  *valuePtr = i->second;
62  return true;
63  }
64  }
65 };
66 
67 /// Checks if an item exists in a \c map or a \c TfHashMap.
68 ///
69 /// If \p key exists in \p map, then this function returns \c true and the
70 /// value indexed by \p key is copied into \p *valuePtr. Otherwise,
71 /// \p *valuePtr is not modified, and \c false is returned.
72 ///
73 /// Example:
74 /// \code
75 /// TfHashMap<string, int, TfHash> m = ...;
76 /// int value;
77 ///
78 ///
79 /// if (TfMapLookup(m, "someKey", &value))
80 /// printf("Value found: %d\n", value);
81 /// else
82 /// printf("Value not found\n");
83 /// ...
84 /// \endcode
85 ///
86 /// \ingroup group_tf_Stl
87 template <class Container, class Key, class Result>
88 bool TfMapLookup(Container const &map, Key const &key, Result* valuePtr)
89 {
90  return Tf_MapLookupHelper<Container>::Lookup(map, key, valuePtr);
91 }
92 
93 /// Checks if an item exists in a \c map or a \c TfHashMap.
94 ///
95 /// If \p key exists in \p map, then this function returns the value index by
96 /// \p key. Otherwise, \p defaultValue is returned. Note that the result is
97 /// returned by value, so this is best used for types that are quick to copy.
98 ///
99 /// Example:
100 /// \code
101 /// TfHashMap<string, int, TfHash> m;
102 /// m["foo"] = 1;
103 ///
104 /// int value = TfMapLookupByValue(m, "someKey", -1);
105 /// TF_AXIOM(value == -1);
106 ///
107 /// int value = TfMapLookupByValue(m, "foo", -1);
108 /// TF_AXIOM(value == 1);
109 ///
110 /// \endcode
111 ///
112 /// \ingroup group_tf_Stl
113 template <class Container, class Key, class Result>
114 const Result TfMapLookupByValue(Container const &map,
115  Key const &key, const Result &defaultValue)
116 {
117  typename Container::const_iterator i = map.find(key);
118  if (i == map.end()) {
119  return defaultValue;
120  } else {
121  return i->second;
122  }
123 }
124 
125 /// Checks if an item exists in a \c map or \c TfHashMap, without copying it.
126 ///
127 /// If \p key exists in the \p map, then this function returns a pointer to
128 /// the value indexed by \p key. Otherwise, NULL is returned.
129 ///
130 /// Example:
131 /// \code
132 /// TfHashMap<string, BigData, TfHash> m = ...;
133 ///
134 /// if (BigData* bigPtr = TfMapLookupPtr(m, "someKey"))
135 /// bigPtr->ModifyStuff();
136 /// else
137 /// printf("Value not found\n");
138 /// \endcode
139 ///
140 /// \ingroup group_tf_Stl
141 template <class Container, class Key>
142 typename Container::mapped_type *
143 TfMapLookupPtr(Container &map, Key const &key)
144 {
145  typename Container::iterator i = map.find(key);
146  return (i != map.end()) ? &(i->second) : NULL;
147 }
148 
149 template <class Container, class Key>
150 typename Container::mapped_type const *
151 TfMapLookupPtr(Container const &map, Key const &key)
152 {
153  typename Container::const_iterator i = map.find(key);
154  return (i != map.end()) ? &(i->second) : NULL;
155 }
156 
157 /// Return an \c std::pair in sorted order.
158 ///
159 /// This call is a useful helper for maps whose key is an unordered pair of
160 /// elements. One can either define a new data type such that (a,b) is deemed
161 /// equivalent to (b,a), or more simply, adopt the convention that a key is
162 /// always written (a,b) with a < b.
163 ///
164 /// \ingroup group_tf_Stl
165 template <typename T>
166 inline std::pair<T,T>
168  return (a < b) ? std::pair<T,T>(a,b) : std::pair<T,T>(b,a);
169 }
170 
171 /// Reset \a obj to be an empty, space-optimized object.
172 ///
173 /// This can be used to clear c++ containers and reclaim their memory. For
174 /// instance, std::vector::clear() will not reclaim any memory, even if the
175 /// vector previously had a large number of elements. Often, this is what you
176 /// want because the vector is later filled again. But sometimes you want to
177 /// reclaim the memory, and this function will do that.
178 ///
179 /// As another example, gcc's hash_map and hash_set do not clear their bucket
180 /// lists when they themselves are cleared. This can lead to poor performance
181 /// due to ever-growing bucket lists for hashes that are repeatedly filled,
182 /// cleared, and filled again. TfReset will avoid this by effectively
183 /// clearing the bucket list.
184 ///
185 /// This function requires that the expression T().swap(obj) where obj is of
186 /// type T& be valid. This is true for many classes, including the standard
187 /// containers.
188 template <class T>
189 inline void TfReset(T &obj) {
190  T().swap(obj);
191 }
192 
194 
195 /// Specialize for TfHashMap to make minimally sized hashes.
196 template <class Key, class Value, class Hash, class Equal, class Alloc>
198  // If the implementation of the hash map allocates buckets when
199  // constructed asking for zero then only swap a constructed object
200  // if \p hash has more than that many buckets already, otherwise
201  // we just clear(). Note that this assumes that the number of
202  // buckets does not depend on the template parameter types which
203  // is reasonable.
204  static size_t emptyCount = Tf_GetEmptyHashMapBucketCount();
205 
206  if (hash.bucket_count() > emptyCount)
208  else if (!hash.empty())
209  hash.clear();
210 }
211 
213 
214 /// Specialize for TfHashSet to make minimally sized hashes.
215 template <class Value, class Hash, class Equal, class Alloc>
217  static size_t emptyCount = Tf_GetEmptyHashSetBucketCount();
218 
219  // See comment above about issues with TfHashSet(0).
220  if (hash.bucket_count() > emptyCount)
222  else if (!hash.empty())
223  hash.clear();
224 }
225 
226 
227 /// An unary function that represents the identity function; it takes a single
228 /// argument \a arg, and returns \a arg.
229 ///
230 /// This is similar to the sgi extension std::identity<T>.
231 template <class T>
232 inline typename hboost::call_traits<T>::param_type
233 TfIdentity(typename hboost::call_traits<T>::param_type arg) {
234  return arg;
235 }
236 
237 /// Produce a sequence consisting of the set difference of [\a first1, \a
238 /// last1) and [\a first2, \a last2), while maintaining the relative order of
239 /// the first sequence. No particular order is required for either range, but
240 /// elements must have a strict weak order provided by operator<.
241 ///
242 /// If an element appears multiple times in either the first or second
243 /// sequence, the number of occurrences in the output is the difference
244 /// between the first sequence and the second (or zero if there are more
245 /// occurrences in the second sequence). For example, if the first sequence
246 /// is (1, 3, 3, 1) and the second sequence is (2, 3, 2), the result will be
247 /// (1, 3, 1).
248 template <class InputIterator1, class InputIterator2, class OutputIterator>
249 void
250 TfOrderedSetDifference(InputIterator1 first1, InputIterator1 last1,
251  InputIterator2 first2, InputIterator2 last2,
252  OutputIterator result)
253 {
254  typedef std::multiset<typename InputIterator2::value_type> SetType;
255  SetType set2(first2, last2);
256 
257  // Walk [first1, last1). If the element is in set2, skip it, and remove one
258  // of those elements from set2, otherwise output it.
259  for (InputIterator1 i = first1; i != last1; ++i) {
260  typename SetType::iterator j = set2.find(*i);
261  if (j != set2.end())
262  set2.erase(j);
263  else
264  *result++ = *i;
265  }
266 }
267 
268 /// Produce a sequence consisting of the set difference of [\a first1, \a
269 /// last1) and [\a first2, \a last2), while maintaining the relative order of
270 /// the first sequence. No particular order is required for either range, but
271 /// elements must have a strict weak order provided by operator<.
272 ///
273 /// If an element appears multiple times in either the first or second
274 /// sequence, the number of occurrences in the output is the difference
275 /// between the first sequence and the second (or zero if there are more
276 /// occurrences in the second sequence). For example, if the first sequence
277 /// is (1, 3, 3, 1) and the second sequence is (2, 3, 2), the result will be
278 /// (1, 3, 1).
279 template <class BackInsertionSequence,
280  class InputIterator1, class InputIterator2>
281 BackInsertionSequence
282 TfOrderedSetDifferenceToContainer(InputIterator1 first1, InputIterator1 last1,
283  InputIterator2 first2, InputIterator2 last2)
284 {
285  BackInsertionSequence result;
286  TfOrderedSetDifference(first1, last1, first2, last2,
287  std::back_inserter(result));
288  return result;
289 }
290 
291 /// Produce a sequence consisting of the set difference of the unique elements
292 /// in [\a first1, \a last1) and [\a first2, \a last2), while maintaining the
293 /// relative order of the first sequence. No particular order is required for
294 /// either range, but elements must have a strict weak order provided by
295 /// operator<.
296 ///
297 /// If an element appears multiple times in the first sequence, it appears
298 /// either zero or one times in the output. It appears zero times if it
299 /// appears in the second sequence, and one time if it does not. For example,
300 /// if the first sequence is (1, 3, 3, 1) and the second sequence is (2, 3,
301 /// 2), the result will be (1).
302 template <class InputIterator1, class InputIterator2, class OutputIterator>
303 void
304 TfOrderedUniquingSetDifference(InputIterator1 first1, InputIterator1 last1,
305  InputIterator2 first2, InputIterator2 last2,
306  OutputIterator result)
307 {
308  typedef std::set<typename InputIterator1::value_type> Set1Type;
309  typedef std::set<typename InputIterator2::value_type> Set2Type;
310 
311  Set1Type set1;
312  Set2Type set2(first2, last2);
313 
314  // Walk [first1, last1). If the element is in set1, skip it. Else insert
315  // it into set1, and if the element is not in set2, output it.
316  for (InputIterator1 i = first1; i != last1; ++i)
317  if (set1.insert(*i).second && !set2.count(*i))
318  *result++ = *i;
319 }
320 
321 /// Produce a sequence consisting of the set difference of the unique elements
322 /// in [\a first1, \a last1) and [\a first2, \a last2), while maintaining the
323 /// relative order of the first sequence. No particular order is required for
324 /// either range, but elements must have a strict weak order provided by
325 /// operator<.
326 ///
327 /// If an element appears multiple times in the first sequence, it appears
328 /// either zero or one times in the output. It appears zero times if it
329 /// appears in the second sequence, and one time if it does not. For example,
330 /// if the first sequence is (1, 3, 3, 1) and the second sequence is (2, 3,
331 /// 2), the result will be (1).
332 template <class BackInsertionSequence,
333  class InputIterator1, class InputIterator2>
334 BackInsertionSequence
336  InputIterator1 last1,
337  InputIterator2 first2,
338  InputIterator2 last2)
339 {
340  BackInsertionSequence result;
341  TfOrderedUniquingSetDifference(first1, last1, first2, last2,
342  std::back_inserter(result));
343  return result;
344 }
345 
346 /// A version of binary search that finds the boundary in a partitioned
347 /// sequence. The Predicate pred should return true for objects on the
348 /// 'first' side (or left-hand) side of the boundary.
349 ///
350 /// More precisely, given a range [first, last) and a Predicate pred for which
351 /// there is exactly one iterator called mid in that range such that pred(x)
352 /// is true for every x in [first, mid) and false for every x in [mid, last),
353 /// return mid.
354 template <class ForwardIterator, class Predicate>
355 static inline ForwardIterator
356 TfFindBoundary(ForwardIterator first, ForwardIterator last,
357  Predicate const &pred)
358 {
359  size_t len = std::distance(first, last);
360  size_t half;
361  ForwardIterator middle;
362 
363  while (len > 0) {
364  half = len >> 1;
365  middle = first;
366  std::advance(middle, half);
367  if (pred(*middle)) {
368  first = middle;
369  ++first;
370  len = len - half - 1;
371  }
372  else
373  len = half;
374  }
375  return first;
376 }
377 
378 /// Function object for retrieving the N'th element of a std::pair
379 /// or std::tuple. This is similar to std::get<N>, but wrapped up in a
380 /// function object suitable for use with STL algorithms.
381 ///
382 /// Example:
383 /// \code
384 /// const std::vector<std::pair<int, std::string>> pairs = { ... }
385 /// std::vector<int> intsOnly(pairs.size());
386 /// std::transform(pairs.begin(), pairs.end(), intsOnly.begin(), TfGet<0>());
387 /// \endcode
388 ///
389 /// \ingroup group_tf_Stl
390 template <size_t N>
391 class TfGet
392 {
393 public:
394  template <class PairOrTuple>
396 
397  template <class PairOrTuple>
398  constexpr return_type<PairOrTuple>& operator()(PairOrTuple& p) const
399  {
400  return std::get<N>(p);
401  }
402 
403  template <class PairOrTuple>
405  const PairOrTuple& p) const
406  {
407  return std::get<N>(p);
408  }
409 
410  template <class PairOrTuple>
411  constexpr return_type<PairOrTuple>&& operator()(PairOrTuple&& p) const
412  {
413  return std::get<N>(std::move(p));
414  }
415 };
416 
418 
419 #endif // PXR_BASE_TF_STL_H
static bool Lookup(Container const &map, Key const &key, Result *valuePtr)
Definition: stl.h:54
void TfReset(T &obj)
Definition: stl.h:189
#define TF_API
Definition: api.h:40
void swap(TfHashMap &other)
Definition: hashmap.h:348
internal::named_arg< T, char > arg(string_view name, const T &arg)
Definition: core.h:1393
GLboolean GLboolean GLboolean GLboolean a
Definition: glew.h:9477
void swap(TfHashSet &other)
Definition: hashset.h:343
TF_API size_t Tf_GetEmptyHashSetBucketCount()
const GLint * first
Definition: glew.h:1528
std::pair< T, T > TfOrderedPair(T a, T b)
Definition: stl.h:167
GLhandleARB obj
Definition: glew.h:6236
void TfOrderedSetDifference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result)
Definition: stl.h:250
constexpr return_type< PairOrTuple > && operator()(PairOrTuple &&p) const
Definition: stl.h:411
BackInsertionSequence TfOrderedSetDifferenceToContainer(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2)
Definition: stl.h:282
hboost::call_traits< T >::param_type TfIdentity(typename hboost::call_traits< T >::param_type arg)
Definition: stl.h:233
bool TfMapLookup(Container const &map, Key const &key, Result *valuePtr)
Definition: stl.h:88
constexpr const return_type< PairOrTuple > & operator()(const PairOrTuple &p) const
Definition: stl.h:404
BackInsertionSequence TfOrderedUniquingSetDifferenceToContainer(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2)
Definition: stl.h:335
void TfOrderedUniquingSetDifference(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result)
Definition: stl.h:304
Container::mapped_type * TfMapLookupPtr(Container &map, Key const &key)
Definition: stl.h:143
GLsizei GLsizei GLfloat distance
Definition: glew.h:13640
Definition: stl.h:391
GLdouble GLdouble GLdouble b
Definition: glew.h:9122
GLfloat GLfloat p
Definition: glew.h:16321
constexpr return_type< PairOrTuple > & operator()(PairOrTuple &p) const
Definition: stl.h:398
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
GLuint64EXT * result
Definition: glew.h:14007
typename std::tuple_element< N, PairOrTuple >::type return_type
Definition: stl.h:395
Definition: half.h:91
TF_API size_t Tf_GetEmptyHashMapBucketCount()
type
Definition: core.h:528
const Result TfMapLookupByValue(Container const &map, Key const &key, const Result &defaultValue)
Definition: stl.h:114
GLenum GLsizei len
Definition: glew.h:7752