1 /* ScummVM - Graphic Adventure Engine
2 *
3 * ScummVM is the legal property of its developers, whose names
4 * are too numerous to list here. Please refer to the COPYRIGHT
5 * file distributed with this source distribution.
6 *
7 * This program is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU General Public License
9 * as published by the Free Software Foundation; either version 2
10 * of the License, or (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 *
21 */
22
23 #ifndef COMMON_UTIL_H
24 #define COMMON_UTIL_H
25
26 #include "common/scummsys.h"
27 #include "common/str.h"
28
29 /**
30 * @defgroup common_util Util
31 * @ingroup common
32 *
33 * @brief Various utility functions.
34 *
35 * @{
36 */
37
38 /**
39 * Check whether a given pointer is aligned correctly.
40 * Note that 'alignment' must be a power of two!
41 */
42 #define IS_ALIGNED(value, alignment) \
43 ((((size_t)value) & ((alignment) - 1)) == 0)
44
45 #ifdef ABS
46 #undef ABS
47 #endif
48
49 #ifdef MIN
50 #undef MIN
51 #endif
52
53 #ifdef MAX
54 #undef MAX
55 #endif
56
57 /** Template method to return the absolute value of @p x. */
ABS(T x)58 template<typename T> inline T ABS(T x) { return (x >= 0) ? x : -x; }
59
60 /** Template method to return the smallest of its parameters. */
MIN(T a,T b)61 template<typename T> inline T MIN(T a, T b) { return (a < b) ? a : b; }
62
63 /** Template method to return the largest of its parameters. */
MAX(T a,T b)64 template<typename T> inline T MAX(T a, T b) { return (a > b) ? a : b; }
65
66 /** Template method to clip the value @p v so that it remains between @p amin and @p amax. */
CLIP(T v,T amin,T amax)67 template<typename T> inline T CLIP(T v, T amin, T amax)
68 {
69 #if !defined(RELEASE_BUILD)
70 // Debug builds use this assert to pinpoint
71 // any problematic cases, where amin and amax
72 // are incorrectly ordered
73 // and thus CLIP() would return an invalid result.
74 assert(amin <= amax);
75 #endif
76 if (v < amin) return amin;
77 else if (v > amax) return amax;
78 return v;
79 }
80
81 /**
82 * Template method to swap the values of its two parameters.
83 */
SWAP(T & a,T & b)84 template<typename T> inline void SWAP(T &a, T &b) { T tmp = a; a = b; b = tmp; }
85
86 #ifdef ARRAYSIZE
87 #undef ARRAYSIZE
88 #endif
89
90 /**
91 * Determine the number of entries in a fixed size array.
92 */
93 #define ARRAYSIZE(x) ((int)(sizeof(x) / sizeof(x[0])))
94
95 /**
96 * Compute a pointer to one past the last element of an array.
97 */
98 #define ARRAYEND(x) ((x) + ARRAYSIZE((x)))
99
100 /**
101 * Clear an array using the default or provided value.
102 */
103 template<typename T, size_t N> inline void ARRAYCLEAR(T (&array) [N], const T &value = T()) {
104 T * ptr = array;
105 size_t n = N;
106 while(n--)
107 *ptr++ = value;
108 }
109
110 /**
111 * Evaluate the name of the current function on compilers supporting this.
112 */
113 #if defined(__GNUC__)
114 # define SCUMMVM_CURRENT_FUNCTION __PRETTY_FUNCTION__
115 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
116 # define SCUMMVM_CURRENT_FUNCTION __func__
117 #elif defined(_MSC_VER)
118 # define SCUMMVM_CURRENT_FUNCTION __FUNCTION__
119 #else
120 # define SCUMMVM_CURRENT_FUNCTION "<unknown>"
121 #endif
122
123 /** @} */
124
125 namespace Common {
126
127 /**
128 * @addtogroup common_util
129 * @{
130 */
131
132 /**
133 * Print a hexdump of the data passed in. The number of bytes per line is
134 * customizable.
135 *
136 * @param data The data to be dumped.
137 * @param len Length of that data.
138 * @param bytesPerLine Number of bytes to print per line (default: 16).
139 * @param startOffset Shift the shown offsets by the starting offset (default: 0).
140 */
141 extern void hexdump(const byte * data, int len, int bytesPerLine = 16, int startOffset = 0);
142
143
144 /**
145 * Parse a string for a boolean value.
146 *
147 * The strings "true", "yes", and "1" are interpreted as true.
148 * The strings "false", "no", and "0" are interpreted as false.
149 * This function ignores case.
150 *
151 * @param[in] val The string to parse.
152 * @param[out] valAsBool Parsing result.
153 *
154 * @return True if the string has been parsed correctly, false if an error occurred.
155 */
156 bool parseBool(const String &val, bool &valAsBool);
157
158
159 /**
160 * Test whether the given character is alphanumeric (a-z, A-Z, 0-9).
161 *
162 * If the parameter is outside the range of a signed or unsigned char, then
163 * false is returned.
164 *
165 * @param c The character to test.
166 *
167 * @return True if the character is alphanumeric, false otherwise.
168 */
169 bool isAlnum(int c);
170
171 /**
172 * Test whether the given character is an alphabetic letter (a-z, A-Z).
173 *
174 * If the parameter is outside the range of a signed or unsigned char, then
175 * false is returned.
176 *
177 * @param c The character to test.
178 *
179 * @return True if the character is alphabetic, false otherwise.
180 */
181 bool isAlpha(int c);
182
183 /**
184 * Test whether the given character is a decimal digit (0-9).
185 *
186 * If the parameter is outside the range of a signed or unsigned char, then
187 * false is returned.
188 *
189 * @param c The character to test.
190 *
191 * @return True if the character is a decimal digit, false otherwise.
192 */
193 bool isDigit(int c);
194
195 /**
196 * Test whether the given character is a hexadecimal digit (0-9 or A-F).
197 *
198 * If the parameter is outside the range of a signed or unsigned char, then
199 * false is returned.
200 *
201 * @param c The character to test.
202 *
203 * @return True if the character is a hexadecimal digit, false otherwise.
204 */
205 bool isXDigit(int c);
206
207 /**
208 * Test whether the given character is a lowercase letter (a-z).
209 *
210 * If the parameter is outside the range of a signed or unsigned char, then
211 * false is returned.
212 *
213 * @param c The character to test.
214 *
215 * @return True if the character is a lowercase letter, false otherwise.
216 */
217 bool isLower(int c);
218
219 /**
220 * Test whether the given character is a whitespace.
221 *
222 * The following characters are considered a whitespace:
223 * @code
224 * ' ', '\t', '\r', '\n', '\v', '\f'
225 * @endcode
226 *
227 * If the parameter is outside the range of a signed or unsigned char, then
228 * false is returned.
229 *
230 * @param c The character to test.
231 *
232 * @return True if the character is a whitespace, false otherwise.
233 */
234 bool isSpace(int c);
235
236 /**
237 * Test whether the given character is an uppercase letter (A-Z).
238 *
239 * If the parameter is outside the range of a signed or unsigned char, then
240 * false is returned.
241 *
242 * @param c The character to test.
243 *
244 * @return True if the character is an uppercase letter, false otherwise.
245 */
246 bool isUpper(int c);
247
248 /**
249 * Test whether the given character is printable. This includes the space
250 * character (' ').
251 *
252 * If the parameter is outside the range of a signed or unsigned char, then
253 * false is returned.
254 *
255 * @param c The character to test.
256 *
257 * @return True if the character is printable, false otherwise.
258 */
259 bool isPrint(int c);
260
261 /**
262 * Test whether the given character is a punctuation character,
263 * (i.e. not alphanumeric).
264 *
265 * @param c The character to test.
266 *
267 * @return True if the character is punctuation, false otherwise.
268 */
269 bool isPunct(int c);
270
271 /**
272 * Test whether the given character is a control character.
273 *
274 * @param c The character to test.
275 *
276 * @return True if the character is a control character, false otherwise.
277 */
278 bool isCntrl(int c);
279
280 /**
281 * Test whether the given character has a graphical representation.
282 *
283 * @param c The character to test.
284 *
285 * @return True if the character is a graphic, false otherwise.
286 */
287 bool isGraph(int c);
288
289 /**
290 * Test whether the given character is blank.
291 *
292 * The following characters are considered blank:
293 * @code
294 * ' ', '\t'
295 * @endcode
296 *
297 * If the parameter is outside the range of a signed or unsigned char, then
298 * false is returned.
299 *
300 * @param c The character to test.
301 *
302 * @return True if the character is blank, false otherwise.
303 */
304 bool isBlank(int c);
305
306
307 /**
308 * Represent the size of a file in bytes as a number with floating point and
309 * largest suitable units. For example, 1474560 bytes as 1.4 MB.
310 *
311 * @param[in] bytes Size in bytes to be represented.
312 * @param[out] unitsOut String with units.
313 *
314 * @note Use @c _() to translate units correctly.
315 *
316 * @return String with a floating point number representing the given size.
317 */
318 Common::String getHumanReadableBytes(uint64 bytes, Common::String &unitsOut);
319
320 /** @} */
321
322 } // End of namespace Common
323
324 #endif
325