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_TF_H
25 #define PXR_BASE_TF_TF_H
26
27 /// \file tf/tf.h
28 /// A file containing basic constants and definitions.
29
30 #if defined(__cplusplus) || defined(doxygen)
31
32 #include "pxr/pxr.h"
33
34 #include "pxr/base/arch/buildMode.h"
35 #include "pxr/base/arch/math.h"
36 #include "pxr/base/arch/inttypes.h"
37
38 #include <math.h>
39 #include <utility>
40
41 PXR_NAMESPACE_OPEN_SCOPE
42
43 // This constant will only be defined if not defined already. This is because
44 // many files need a higher limit and define this constant themselves before
45 // including anything else.
46
47 #ifndef TF_MAX_ARITY
48 # define TF_MAX_ARITY 7
49 #endif // TF_MAX_ARITY
50
51
52 /// This value may be used by functions that return a \c size_t to indicate
53 /// that a special or error condition has occurred.
54 /// \ingroup group_tf_TfError
55 #define TF_BAD_SIZE_T SIZE_MAX
56
57 /// \addtogroup group_tf_BasicMath
58 ///@{
59
60 /// Returns the absolute value of the given \c int value.
TfAbs(int v)61 inline int TfAbs(int v) {
62 return (v < 0 ? -v : v);
63 }
64
65 /// Returns the absolute value of the given \c double value.
TfAbs(double v)66 inline double TfAbs(double v) {
67 return fabs(v);
68 }
69
70 /// Returns the smaller of the two given \c values.
71 template <class T>
TfMin(const T & v1,const T & v2)72 inline T TfMin(const T& v1, const T& v2) {
73 return (v1 < v2 ? v1 : v2);
74 }
75
76 /// Returns the larger of the two given \c values.
77 template <class T>
TfMax(const T & v1,const T & v2)78 inline T TfMax(const T& v1, const T& v2) {
79 return (v1 > v2 ? v1 : v2);
80 }
81
82 ///@}
83
84 /// \struct TfDeleter
85 /// Function object for deleting any pointer.
86 ///
87 /// An STL collection of pointers does not automatically delete each
88 /// pointer when the collection itself is destroyed. Instead of writing
89 /// \code
90 /// for (list<Otter*>::iterator i = otters.begin(); i != otters.end(); ++i)
91 /// delete *i;
92 /// \endcode
93 /// you can use \c TfDeleter and simply write
94 /// \code
95 /// #include <algorithm>
96 ///
97 /// for_each(otters.begin(), otters.end(), TfDeleter());
98 /// \endcode
99 ///
100 /// \note \c TfDeleter calls the non-array version of \c delete.
101 /// Don't use \c TfDeleter if you allocated your space using \c new[]
102 /// (and consider using a \c vector<> in place of a built-in array).
103 /// Also, note that you need to put parenthesis after \c TfDeleter
104 /// in the call to \c for_each().
105 ///
106 /// Finally, \c TfDeleter also works for map-like collections.
107 /// Note that this works as follows: if \c TfDeleter is handed
108 /// a datatype of type \c std::pair<T1,T2*>, then the second element
109 /// of the pair is deleted, but the first (whether or not it is a pointer)
110 /// is left alone. In other words, if you give \c TfDeleter() a pair of
111 /// pointers, it only deletes the second, but never the first. This is the
112 /// desired behavior for maps.
113 ///
114 /// \ingroup group_tf_Stl
115 struct TfDeleter {
116 template <class T>
operatorTfDeleter117 void operator() (T* t) const {
118 delete t;
119 }
120
121 template <class T1, class T2>
operatorTfDeleter122 void operator() (std::pair<T1, T2*> p) const {
123 delete p.second;
124 }
125 };
126
127 /*
128 * The compile-time constants are not part of doxygen; if you know they're here,
129 * fine, but they should be used rarely, so we don't go out of our way to
130 * advertise them.
131 *
132 * Here's the idea: you may have an axiom or conditional check which is just too
133 * expensive to make part of a release build. Compilers these days will optimize
134 * away expressions they can evaluate at compile-time. So you can do
135 *
136 * if (TF_DEV_BUILD)
137 * TF_AXIOM(expensiveConditional);
138 *
139 * to get a condition axiom. You can even write
140 *
141 * TF_AXIOM(!TF_DEV_BUILD || expensiveConditional);
142 *
143 * What you CANNOT do is write
144 * #if defined(TF_DEV_BUILD)
145 * or
146 * #if TF_DEV_BUILD == 0
147 *
148 * The former compiles but always yields true; the latter doesn't compile.
149 * In other words, you can change the flow of control using these constructs,
150 * but we deliberately are prohibiting things like
151 *
152 * struct Bar {
153 * #if ...
154 * int _onlyNeededForChecks;
155 * #endif
156 * };
157 *
158 * or creating functions which only show up in some builds.
159 */
160
161 #define TF_DEV_BUILD ARCH_DEV_BUILD
162
163 PXR_NAMESPACE_CLOSE_SCOPE
164
165 #endif // defined(__cplusplus)
166
167 /// Stops compiler from producing unused argument or variable warnings.
168 /// This is useful mainly in C, because in C++ you can just leave
169 /// the variable unnamed. However, there are situations where this
170 /// can be useful even in C++, such as
171 /// \code
172 /// void
173 /// MyClass::Method( int foo )
174 /// {
175 /// #if defined(__APPLE__)
176 /// TF_UNUSED( foo );
177 /// // do something that doesn't need foo...
178 /// #else
179 /// // do something that needs foo
180 /// #endif
181 /// }
182 /// \endcode
183 ///
184 /// \ingroup group_tf_TfCompilerAids
185 #define TF_UNUSED(x) (void) x
186
187 #endif // TF_H
188