Google OR-Tools v9.14
a fast and portable software suite for combinatorial optimization
Loading...
Searching...
No Matches
int_type.h
Go to the documentation of this file.
1// Copyright 2010-2025 Google LLC
2// Licensed under the Apache License, Version 2.0 (the "License");
3// you may not use this file except in compliance with the License.
4// You may obtain a copy of the License at
5//
6// http://www.apache.org/licenses/LICENSE-2.0
7//
8// Unless required by applicable law or agreed to in writing, software
9// distributed under the License is distributed on an "AS IS" BASIS,
10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11// See the License for the specific language governing permissions and
12// limitations under the License.
13
14// IntType is a simple template class mechanism for defining "logical"
15// integer-like class types that support many of the same functionalities
16// as native integer types, but which prevent assignment, construction, and
17// other operations from other similar integer-like types. Essentially, the
18// template class IntType<IntTypeName, ValueType> (where ValueType assumes
19// valid scalar types such as int, uint, int32_t, etc) has the additional
20// property that it cannot be assigned to or constructed from other IntTypes
21// or native integer types of equal or implicitly convertible type.
22//
23// The class is useful for preventing mingling of integer variables with
24// different logical roles or units. Unfortunately, C++ provides relatively
25// good type-safety for user-defined classes but not for integer types. It is
26// essentially up to the user to use nice variable names and comments to prevent
27// accidental mismatches, such as confusing a user-index with a group-index or a
28// time-in-milliseconds with a time-in-seconds. The use of typedefs are limited
29// in that regard as they do not enforce type-safety.
30//
31// USAGE -----------------------------------------------------------------------
32//
33// DEFINE_INT_TYPE(IntTypeName, ValueType);
34//
35// where:
36// IntTypeName: is the desired (unique) name for the "logical" integer type.
37// ValueType: is one of the integral types as defined by std::is_integral
38// (see <type_traits>).
39//
40// DISALLOWED OPERATIONS / TYPE-SAFETY ENFORCEMENT -----------------------------
41//
42// Consider these definitions and variable declarations:
43// DEFINE_INT_TYPE(GlobalDocID, int64_t);
44// DEFINE_INT_TYPE(LocalDocID, int64_t);
45// GlobalDocID global;
46// LocalDocID local;
47//
48// The class IntType prevents:
49//
50// 1) Assignments of other IntTypes with different IntTypeNames.
51//
52// global = local; <-- Fails to compile!
53// local = global; <-- Fails to compile!
54//
55// 2) Explicit/implicit conversion from an IntType to another IntType.
56//
57// LocalDocID l(global); <-- Fails to compile!
58// LocalDocID l = global; <-- Fails to compile!
59//
60// void GetGlobalDoc(GlobalDocID global) { }
61// GetGlobalDoc(global); <-- Compiles fine, types match!
62// GetGlobalDoc(local); <-- Fails to compile!
63//
64// 3) Implicit conversion from an IntType to a native integer type.
65//
66// void GetGlobalDoc(int64_t global) { ...
67// GetGlobalDoc(global); <-- Fails to compile!
68// GetGlobalDoc(local); <-- Fails to compile!
69//
70// void GetLocalDoc(int32_t local) { ...
71// GetLocalDoc(global); <-- Fails to compile!
72// GetLocalDoc(local); <-- Fails to compile!
73//
74//
75// SUPPORTED OPERATIONS --------------------------------------------------------
76//
77// The following operators are supported: unary: ++ (both prefix and postfix),
78// +, -, ! (logical not), ~ (one's complement); comparison: ==, !=, <, <=, >,
79// >=; numerical: +, -, *, /; assignment: =, +=, -=, /=, *=; stream: <<. Each
80// operator allows the same IntTypeName and the ValueType to be used on
81// both left- and right-hand sides.
82//
83// It also supports an accessor value() returning the stored value as ValueType,
84// and a templatized accessor value<T>() method that serves as syntactic sugar
85// for static_cast<T>(var.value()). These accessors are useful when assigning
86// the stored value into protocol buffer fields and using it as printf args.
87//
88// The class also defines a hash functor that allows the IntType to be used
89// as key to hashable containers such as hash_map and hash_set.
90//
91// We suggest using the IntTypeIndexedContainer wrapper around google3's
92// FixedArray and STL vector (see int-type-indexed-container.h) if an IntType is
93// intended to be used as an index into these containers. These wrappers are
94// indexed in a type-safe manner using IntTypes to ensure type-safety.
95//
96// NB: this implementation does not attempt to abide by or enforce dimensional
97// analysis on these scalar types.
98//
99// EXAMPLES --------------------------------------------------------------------
100//
101// DEFINE_INT_TYPE(GlobalDocID, int64_t);
102// GlobalDocID global = 3;
103// std::cout << global; <-- Prints 3 to stdout.
104//
105// for (GlobalDocID i(0); i < global; ++i) {
106// std::cout << i;
107// } <-- Print(ln)s 0 1 2 to stdout
108//
109// DEFINE_INT_TYPE(LocalDocID, int64_t);
110// LocalDocID local;
111// std::cout << local; <-- Prints 0 to stdout it
112// default
113// initializes the value to 0.
114//
115// local = 5;
116// local *= 2;
117// LocalDocID l(local);
118// std::cout << l + local; <-- Prints 20 to stdout.
119//
120// GenericSearchRequest request;
121// request.set_doc_id(global.value()); <-- Uses value() to extract the value
122// from the IntType class.
123//
124// REMARKS ---------------------------------------------------------------------
125//
126// The following bad usage is permissible although discouraged. Essentially, it
127// involves using the value*() accessors to extract the native integer type out
128// of the IntType class. Keep in mind that the primary reason for the IntType
129// class is to prevent *accidental* mingling of similar logical integer types --
130// and not type casting from one type to another.
131//
132// DEFINE_INT_TYPE(GlobalDocID, int64_t);
133// DEFINE_INT_TYPE(LocalDocID, int64_t);
134// GlobalDocID global;
135// LocalDocID local;
136//
137// global = local.value(); <-- Compiles fine.
138//
139// void GetGlobalDoc(GlobalDocID global) { ...
140// GetGlobalDoc(local.value()); <-- Compiles fine.
141//
142// void GetGlobalDoc(int64_t global) { ...
143// GetGlobalDoc(local.value()); <-- Compiles fine.
144
145#ifndef OR_TOOLS_BASE_INT_TYPE_H_
146#define OR_TOOLS_BASE_INT_TYPE_H_
147
148#include <stddef.h>
149
150#include <iosfwd>
151#include <ostream> // NOLINT
152#include <type_traits>
153
154#include "absl/base/attributes.h"
155#include "absl/strings/string_view.h"
156
157namespace gtl {
158
159template <typename IntTypeName, typename _ValueType>
160class IntType;
161
162// Defines the IntType using value_type and typedefs it to int_type_name.
163// The struct int_type_name ## _tag_ trickery is needed to ensure that a new
164// type is created per int_type_name.
165#define DEFINE_INT_TYPE(int_type_name, value_type) \
166 struct int_type_name##_tag_ { \
167 static constexpr absl::string_view TypeName() { return #int_type_name; } \
168 }; \
169 typedef ::gtl::IntType<int_type_name##_tag_, value_type> int_type_name;
170
171// Holds a integral value (of type ValueType) and behaves as a
172// ValueType by exposing assignment, unary, comparison, and arithmetic
173// operators.
174//
175// The template parameter IntTypeName defines the name for the int type and must
176// be unique within a binary (the convenient DEFINE_INT_TYPE macro at the end of
177// the file generates a unique IntTypeName). The parameter ValueType defines
178// the integer type value (see supported list above).
179//
180// This class is NOT thread-safe.
181template <typename IntTypeName, typename _ValueType>
182class IntType {
183 public:
184 typedef _ValueType ValueType; // for non-member operators
185 typedef IntType<IntTypeName, ValueType> ThisType; // Syntactic sugar.
186
187 static constexpr absl::string_view TypeName() {
188 return IntTypeName::TypeName();
189 }
190
191 // Note that this may change from time to time without notice.
192 // See .
193 struct Hasher {
194 size_t operator()(const IntType& arg) const {
195 return static_cast<size_t>(arg.value());
196 }
197 };
198
199 template <typename H>
200 friend H AbslHashValue(H h, const IntType& i) {
201 return H::combine(std::move(h), i.value());
202 }
203
204 public:
205 // Default constructor initializing value_ to 0.
206 constexpr IntType() : value_(0) {}
207 // C'tor explicitly initializing from a ValueType.
208 constexpr explicit IntType(ValueType value) : value_(value) {}
209
210 // IntType uses the default copy constructor, destructor and assign operator.
211 // The defaults are sufficient and omitting them allows the compiler to add
212 // the move constructor/assignment.
213
214 // -- ACCESSORS --------------------------------------------------------------
215 // The class provides a value() accessor returning the stored ValueType value_
216 // as well as a templatized accessor that is just a syntactic sugar for
217 // static_cast<T>(var.value());
218 constexpr ValueType value() const { return value_; }
219
220 template <typename ValType>
221 constexpr ValType value() const {
222 return static_cast<ValType>(value_);
223 }
224
225 // -- UNARY OPERATORS --------------------------------------------------------
226 ThisType& operator++() { // prefix ++
227 ++value_;
228 return *this;
229 }
230 const ThisType operator++(int v) { // postfix ++
231 ThisType temp(*this);
232 ++value_;
233 return temp;
234 }
235 ThisType& operator--() { // prefix --
236 --value_;
237 return *this;
238 }
239 const ThisType operator--(int v) { // postfix --
240 ThisType temp(*this);
241 --value_;
242 return temp;
243 }
244
245 constexpr bool operator!() const { return value_ == 0; }
246 constexpr const ThisType operator+() const { return ThisType(value_); }
247 constexpr const ThisType operator-() const { return ThisType(-value_); }
248 constexpr const ThisType operator~() const { return ThisType(~value_); }
249
250 // -- ASSIGNMENT OPERATORS ---------------------------------------------------
251 // We support the following assignment operators: =, +=, -=, *=, /=, <<=, >>=
252 // and %= for both ThisType and ValueType.
253#define INT_TYPE_ASSIGNMENT_OP(op) \
254 ThisType& operator op(const ThisType& arg_value) { \
255 value_ op arg_value.value(); \
256 return *this; \
257 } \
258 ThisType& operator op(ValueType arg_value) { \
259 value_ op arg_value; \
260 return *this; \
261 }
266 INT_TYPE_ASSIGNMENT_OP(<<=); // NOLINT
269#undef INT_TYPE_ASSIGNMENT_OP
270
272 value_ = arg_value;
273 return *this;
274 }
275
276 private:
277 // The integer value of type ValueType.
278 ValueType value_;
280
281// -- NON-MEMBER STREAM OPERATORS ----------------------------------------------
282// We provide the << operator, primarily for logging purposes. Currently, there
283// seems to be no need for an >> operator.
284template <typename IntTypeName, typename ValueType>
285std::ostream& operator<<(std::ostream& os, // NOLINT
287 return os << arg.value();
288}
289
290// -- NON-MEMBER ARITHMETIC OPERATORS ------------------------------------------
291// We support only the +, -, *, and / operators with the same IntType and
292// ValueType types. The reason is to allow simple manipulation on these IDs
293// when used as indices in vectors and arrays.
294//
295// NB: Although it is possible to do IntType * IntType and IntType / IntType,
296// it is probably non-sensical from a dimensionality analysis perspective.
297#define INT_TYPE_ARITHMETIC_OP(op) \
298 template <typename IntTypeName, typename ValueType> \
299 constexpr IntType<IntTypeName, ValueType> operator op( \
300 IntType<IntTypeName, ValueType> id_1, \
301 IntType<IntTypeName, ValueType> id_2) { \
302 return IntType<IntTypeName, ValueType>(id_1.value() op id_2.value()); \
303 } \
304 template <typename IntTypeName, typename ValueType> \
305 constexpr IntType<IntTypeName, ValueType> operator op( \
306 IntType<IntTypeName, ValueType> id, \
307 typename IntType<IntTypeName, ValueType>::ValueType arg_val) { \
308 return IntType<IntTypeName, ValueType>(id.value() op arg_val); \
309 } \
310 template <typename IntTypeName, typename ValueType> \
311 constexpr IntType<IntTypeName, ValueType> operator op( \
312 typename IntType<IntTypeName, ValueType>::ValueType arg_val, \
313 IntType<IntTypeName, ValueType> id) { \
314 return IntType<IntTypeName, ValueType>(arg_val op id.value()); \
315 }
320INT_TYPE_ARITHMETIC_OP(<<); // NOLINT
323#undef INT_TYPE_ARITHMETIC_OP
324
325// -- NON-MEMBER COMPARISON OPERATORS ------------------------------------------
326// Static inline comparison operators. We allow all comparison operators among
327// the following types (OP \in [==, !=, <, <=, >, >=]:
328// IntType<IntTypeName, ValueType> OP IntType<IntTypeName, ValueType>
329// IntType<IntTypeName, ValueType> OP ValueType
330// ValueType OP IntType<IntTypeName, ValueType>
331#define INT_TYPE_COMPARISON_OP(op) \
332 template <typename IntTypeName, typename ValueType> \
333 static inline constexpr bool operator op( \
334 IntType<IntTypeName, ValueType> id_1, \
335 IntType<IntTypeName, ValueType> id_2) { \
336 return id_1.value() op id_2.value(); \
337 } \
338 template <typename IntTypeName, typename ValueType> \
339 static inline constexpr bool operator op( \
340 IntType<IntTypeName, ValueType> id, \
341 typename IntType<IntTypeName, ValueType>::ValueType val) { \
342 return id.value() op val; \
343 } \
344 template <typename IntTypeName, typename ValueType> \
345 static inline constexpr bool operator op( \
346 typename IntType<IntTypeName, ValueType>::ValueType val, \
347 IntType<IntTypeName, ValueType> id) { \
348 return val op id.value(); \
349 }
352INT_TYPE_COMPARISON_OP(<); // NOLINT
354INT_TYPE_COMPARISON_OP(>); // NOLINT
356#undef INT_TYPE_COMPARISON_OP
357
358} // namespace gtl
359
360#endif // OR_TOOLS_BASE_INT_TYPE_H_
const ThisType operator++(int v)
Definition int_type.h:230
constexpr const ThisType operator~() const
Definition int_type.h:248
constexpr ValType value() const
Definition int_type.h:221
INT_TYPE_ASSIGNMENT_OP(+=)
constexpr const ThisType operator-() const
Definition int_type.h:247
INT_TYPE_ASSIGNMENT_OP * INT_TYPE_ASSIGNMENT_OP(/=);INT_TYPE_ASSIGNMENT_OP(<<=
INT_TYPE_ASSIGNMENT_OP(%=)
static constexpr absl::string_view TypeName()
Definition int_type.h:187
_ValueType ValueType
Definition int_type.h:184
INT_TYPE_ASSIGNMENT_OP(> >=)
constexpr ValueType value() const
Definition int_type.h:218
constexpr bool operator!() const
Definition int_type.h:245
friend H AbslHashValue(H h, const IntType &i)
Definition int_type.h:200
const ThisType operator--(int v)
Definition int_type.h:239
constexpr const ThisType operator+() const
Definition int_type.h:246
ThisType & operator++()
– UNARY OPERATORS -----------------------------------------------------—
Definition int_type.h:226
constexpr IntType(ValueType value)
C'tor explicitly initializing from a ValueType.
Definition int_type.h:208
ThisType & operator--()
Definition int_type.h:235
constexpr IntType()
Default constructor initializing value_ to 0.
Definition int_type.h:206
ThisType & operator=(ValueType arg_value)
Definition int_type.h:271
IntType< IntTypeName, ValueType > ThisType
Definition int_type.h:185
INT_TYPE_ASSIGNMENT_OP(-=)
#define INT_TYPE_ASSIGNMENT_OP(op)
Definition int_type.h:253
#define INT_TYPE_ARITHMETIC_OP(op)
Definition int_type.h:297
!
Definition array.h:26
INT_TYPE_COMPARISON_OP(==)
std::ostream & operator<<(std::ostream &os, IntType< IntTypeName, ValueType > arg)
Definition int_type.h:285
class gtl::IntType ABSL_ATTRIBUTE_PACKED
size_t operator()(const IntType &arg) const
Definition int_type.h:194