Fixposition SDK 0.0.0-heads/main-0-g5c7edb5
Collection of c++ libraries and apps for use with Fixposition products on Linux
Loading...
Searching...
No Matches
string.hpp
Go to the documentation of this file.
1/**
2 * \verbatim
3 * ___ ___
4 * \ \ / /
5 * \ \/ / Copyright (c) Fixposition AG (www.fixposition.com) and contributors
6 * / /\ \ License: see the LICENSE file
7 * /__/ \__\
8 * \endverbatim
9 *
10 * @file
11 * @brief Fixposition SDK: String utilities
12 *
13 * @page FPSDK_COMMON_STRING String utilities
14 *
15 * **API**: fpsdk_common/string.hpp and fpsdk::common::string
16 *
17 */
18#ifndef __FPSDK_COMMON_STRING_HPP__
19#define __FPSDK_COMMON_STRING_HPP__
20
21/* LIBC/STL */
22#include <cinttypes>
23#include <cstdarg>
24#include <cstdint>
25#include <functional>
26#include <string>
27#include <vector>
28
29/* EXTERNAL */
30
31/* PACKAGE */
32
33namespace fpsdk {
34namespace common {
35/**
36 * @brief String utilities
37 */
38namespace string {
39/* ****************************************************************************************************************** */
40
41/**
42 * @brief Helper macro for marking functions as taking printf() style formatting strings
43 *
44 * This helps the compiler to check that the number and types of the variable arguments match the format string.
45 */
46#ifndef PRINTF_ATTR
47# define PRINTF_ATTR(n) __attribute__((format(printf, n, n + 1)))
48#endif
49
50/**
51 * @brief Format string
52 *
53 * @param[in] fmt printf() style format string
54 * @param[in] ... Arguments to the format string
55 *
56 * @returns the formatted string
57 */
58std::string Sprintf(const char* const fmt, ...) PRINTF_ATTR(1);
59
60/**
61 * @brief Format string
62 *
63 * @param[in] fmt printf() style format string
64 * @param[in] args Arguments list to the format string
65 *
66 * @returns the formatted string
67 */
68std::string Vsprintf(const char* fmt, va_list args);
69
70/**
71 * @brief Format time
72 *
73 * @param[in] fmt Format, see strftime(3), can be NULL for a default "yyyy-mm-dd hh:mm:ss" format
74 * @param[in] ts Posix timestamp [s] (time_t), or 0 for "now"
75 * @param[in] utc Format as UTC (true) or localtime (false, default)
76 *
77 * @returns a string with the formatted time
78 */
79std::string Strftime(const char* const fmt, const int64_t ts = 0, const bool utc = false);
80
81/**
82 * @brief Search and replace
83 *
84 * @param[in,out] str The string to search and replace in
85 * @param[in] search The search term
86 * @param[in] replace The replacement
87 * @param[in] max Maximum number of replacements to do (or <= 0 for unlimited)
88 *
89 * @returns the number of matches
90 */
91int StrReplace(std::string& str, const std::string& search, const std::string& replace, const int max = 0);
92
93/**
94 * @brief Trim string left
95 *
96 * @param[in,out] str The string with all whitespace (" ", \\t, \\r, \\n) removed on the left
97 */
98void StrTrimLeft(std::string& str);
99
100/**
101 * @brief Trim string right
102 *
103 * @param[in,out] str The string with all whitespace (" ", \\t, \\r, \\n) removed on the right
104 */
105void StrTrimRight(std::string& str);
106
107/**
108 * @brief Trim string left and right
109 *
110 * @param[in,out] str The string with all whitespace (" ", \\t, \\r, \\n) removed on the left and the right
111 */
112void StrTrim(std::string& str);
113
114/**
115 * @brief Split string
116 *
117 * Splits a string using a separator string. All parts, including empty ones, are returned. An empty separator
118 * leads to only one part, that is equal to the input string.
119 *
120 * Examples:
121 * "foo,bar,baz" separated by "," --> [ "foo", "bar", "baz" ]
122 * "foo,bar,baz" separated by "," (max=2) --> [ "foo", "bar,baz" ]
123 * "foo,,baz,,," separated by "," --> [ "foo", "", "baz", "", "", "" ]
124 *
125 * @param[in] str The string
126 * @param[in] sep The separator, empty string is allowed
127 * @param[in] maxNum The maximum number of parts, or 0 (default) for as many as necessary
128 *
129 * @returns a vector with all parts
130 */
131std::vector<std::string> StrSplit(const std::string& str, const std::string& sep, const int maxNum = 0);
132
133/**
134 * @brief Join strings
135 *
136 * @param[in] strs List of strings to join
137 * @param[in] sep Separator
138 *
139 * @returns a string of all given parts separated by the given separator
140 */
141std::string StrJoin(const std::vector<std::string>& strs, const std::string& sep);
142
143/**
144 * @brief Map strings
145 *
146 * @param[in] strs List of strings to map
147 * @param[in] map Map function
148 *
149 * @returns the mapped list of strings
150 */
151std::vector<std::string> StrMap(
152 const std::vector<std::string>& strs, std::function<std::string(const std::string&)> map);
153
154/**
155 * @brief Remove duplicates
156 *
157 * @param[in] strs List of strings
158 */
159void MakeUnique(std::vector<std::string>& strs);
160
161/**
162 * @brief Format hexdump of data
163 *
164 * @param[in] data The data
165 *
166 * @returns one or more lines (strings) with a hexdump of the data
167 */
168std::vector<std::string> HexDump(const std::vector<uint8_t> data);
169
170/**
171 * @brief Format hexdump of data
172 *
173 * @param[in] data The data
174 * @param[in] size The size of the data
175 *
176 * @returns one or more lines (strings) with a hexdump of the data
177 */
178std::vector<std::string> HexDump(const uint8_t* data, const std::size_t size);
179
180/**
181 * @brief Format value to "bits string"
182 *
183 * @param[in] value The value
184 * @param[in] size The number of bits to format (clamped to 1-64)
185 *
186 * @returns a "0b...." string with the bits formatted as '0' and '1'
187 */
188std::string StrFormatBits(const uint64_t value, const std::size_t size = 64);
189
190/**
191 * @brief Check if one string starts with another string
192 *
193 * @param[in] str String to check
194 * @param[in] prefix Prefix to check, length must be >= length of str
195 *
196 * @returns true if string starts with the prefix, false otherwise (no match or empty string(s))
197 */
198bool StrStartsWith(const std::string& str, const std::string& prefix);
199
200/**
201 * @brief Check if one string ends with another string
202 *
203 * @param[in] str String to check
204 * @param[in] suffix Prefix to check, length must be >= length of str
205 *
206 * @returns true if string ends with the suffix, false otherwise (no match or empty string(s))
207 */
208bool StrEndsWith(const std::string& str, const std::string& suffix);
209
210/**
211 * @brief Check if one string is contained within another string string
212 *
213 * @param[in] str String to check
214 * @param[in] sub String to find
215 *
216 * @returns true if string contains the substriong, false otherwise(no match or empty string(s))
217 */
218bool StrContains(const std::string& str, const std::string& sub);
219
220/**
221 * @brief Convert string to value (int8_t)
222 *
223 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
224 * target value type result in a failure (return false). The output value is only modified on success.
225 *
226 * @param[in] str The string, decimal, hex ("0x...") or octal ("0..."), valid range: INT8_MIN..INT8_MAX
227 * @param[out] value The value
228 *
229 * @returns true if the string could be converted, false otherwise
230 */
231bool StrToValue(const std::string& str, int8_t& value);
232
233/**
234 * @brief Convert string to value (uint8_t)
235 *
236 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
237 * target value type result in a failure (return false). The output value is only modified on success.
238 *
239 * @param[in] str The string, decimal, hex ("0x..."), bin ("0b...") or octal ("0..."), valid range: 0..UINT8_MAX
240 * @param[out] value The value
241 *
242 * @returns true if the string could be converted, false otherwise
243 */
244bool StrToValue(const std::string& str, uint8_t& value);
245
246/**
247 * @brief Convert string to value (int16_t)
248 *
249 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
250 * target value type result in a failure (return false). The output value is only modified on success.
251 *
252 * @param[in] str The string, decimal, hex ("0x...") or octal ("0..."), valid range: INT16_MIN..INT16_MAX
253 * @param[out] value The value
254 *
255 * @returns true if the string could be converted, false otherwise
256 */
257bool StrToValue(const std::string& str, int16_t& value);
258
259/**
260 * @brief Convert string to value (uint16_t)
261 *
262 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
263 * target value type result in a failure (return false). The output value is only modified on success.
264 *
265 * @param[in] str The string, decimal, hex ("0x..."), bin ("0b...") or octal ("0..."), valid range: 0..UINT16_MAX
266 * @param[out] value The value
267 *
268 * @returns true if the string could be converted, false otherwise
269 */
270bool StrToValue(const std::string& str, uint16_t& value);
271
272/**
273 * @brief Convert string to value (int32_t)
274 *
275 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
276 * target value type result in a failure (return false). The output value is only modified on success.
277 *
278 * @param[in] str The string, decimal, hex ("0x...") or octal ("0..."), valid range: INT32_MIN..INT32_MAX
279 * @param[out] value The value
280 *
281 * @returns true if the string could be converted, false otherwise
282 */
283bool StrToValue(const std::string& str, int32_t& value);
284
285/**
286 * @brief Convert string to value (uint32_t)
287 *
288 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
289 * target value type result in a failure (return false). The output value is only modified on success.
290 *
291 * @param[in] str The string, decimal, hex ("0x..."), bin ("0b...") or octal ("0..."), valid range: 0..UINT32_MAX
292 * @param[out] value The value
293 *
294 * @returns true if the string could be converted, false otherwise
295 */
296bool StrToValue(const std::string& str, uint32_t& value);
297
298/**
299 * @brief Convert string to value (int64_t, long)
300 *
301 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
302 * target value type result in a failure (return false). The output value is only modified on success.
303 *
304 * @param[in] str The string, decimal, hex ("0x...") or octal ("0..."), valid range: (INT64_MIN+1)..(INT64_MAX-1)
305 * @param[out] value The value
306 *
307 * @returns true if the string could be converted, false otherwise
308 */
309bool StrToValue(const std::string& str, int64_t& value);
310
311/**
312 * @brief Convert string to value (uint64_t, unsigned long)
313 *
314 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
315 * target value type result in a failure (return false). The output value is only modified on success.
316 *
317 * @param[in] str The string, decimal, hex ("0x..."), bin ("0b...") or octal ("0..."), valid range: 0..(INT64_MAX-1)
318 * @param[out] value The value
319 *
320 * @returns true if the string could be converted, false otherwise
321 */
322bool StrToValue(const std::string& str, uint64_t& value);
323
324/**
325 * @brief Convert string to value (float)
326 *
327 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
328 * target value type result in a failure (return false). The output value is only modified on success.
329 *
330 * @param[in] str The string, anything %f understands (but not infinite or NaN)
331 * @param[out] value The value
332 *
333 * @returns true if the string could be converted, false otherwise
334 */
335bool StrToValue(const std::string& str, float& value);
336
337/**
338 * @brief Convert string to value (double)
339 *
340 * @note White-space or other spurious characters in the string or valid number strings that are out of range of the
341 * target value type result in a failure (return false). The output value is only modified on success.
342 *
343 * @param[in] str The string, anything %f understands (but not infinite or NaN)
344 * @param[out] value The value
345 *
346 * @returns true if the string could be converted, false otherwise
347 */
348bool StrToValue(const std::string& str, double& value);
349
350/**
351 * @brief Convert string to value (bool)
352 *
353 * The following strings (case insensitive) are considered true resp. false:
354 * - true: "true", "yes", "1"
355 * - false: "false", "no", "0"
356 *
357 * @note White-space or other spurious characters in the string result in a failure (return false). The output value is
358 * only modified on success.
359 *
360 * @param[in] str The string, anything %f understands (but not infinite or NaN)
361 * @param[out] value The value
362 *
363 * @returns true if the string could be converted, false otherwise
364 */
365bool StrToValue(const std::string& str, bool& value);
366
367/**
368 * @brief Convert string to all upper case
369 *
370 * @param[in] str The string
371 *
372 * @returns the string converted to all upper case
373 */
374std::string StrToUpper(const std::string& str);
375
376/**
377 * @brief Convert string to all lower case
378 *
379 * @param[in] str The string
380 *
381 * @returns the string converted to all lower case
382 */
383std::string StrToLower(const std::string& str);
384
385/**
386 * @brief Stringify glibc error
387 *
388 * This works much like strerror(3), but is a bit more detailed adding the errnum value and name to the description. For
389 * example: StrError(EAGAIN) returns "Resource temporarily unavailable (11, EAGAIN)".
390 *
391 * @param[in] errnum The error number, see errno(3)
392 *
393 * @returns a string describing the error
394 */
395std::string StrError(const int errnum);
396
397/**
398 * @brief Stringify value (bool)
399 *
400 * @param[in] value The value
401 *
402 * @returns a stringification of the value
403 */
404constexpr const char* ToStr(const bool value)
405{
406 return value ? "true" : "false";
407}
408
409/**
410 * @brief Convert string to buffer
411 *
412 * @param[in] str The string
413 *
414 * @returns a buffer with the string's data
415 */
416std::vector<uint8_t> StrToVec(const std::string& str);
417
418/* ****************************************************************************************************************** */
419} // namespace string
420} // namespace common
421} // namespace fpsdk
422#endif // __FPSDK_COMMON_STRING_HPP__
std::string Vsprintf(const char *fmt, va_list args)
Format string.
std::string Strftime(const char *const fmt, const int64_t ts=0, const bool utc=false)
Format time.
void StrTrimLeft(std::string &str)
Trim string left.
std::vector< std::string > StrSplit(const std::string &str, const std::string &sep, const int maxNum=0)
Split string.
std::string StrToUpper(const std::string &str)
Convert string to all upper case.
std::vector< std::string > HexDump(const std::vector< uint8_t > data)
Format hexdump of data.
void StrTrimRight(std::string &str)
Trim string right.
std::vector< std::string > StrMap(const std::vector< std::string > &strs, std::function< std::string(const std::string &)> map)
Map strings.
void StrTrim(std::string &str)
Trim string left and right.
constexpr const char * ToStr(const bool value)
Stringify value (bool)
Definition string.hpp:404
std::string StrToLower(const std::string &str)
Convert string to all lower case.
bool StrToValue(const std::string &str, int8_t &value)
Convert string to value (int8_t)
bool StrEndsWith(const std::string &str, const std::string &suffix)
Check if one string ends with another string.
std::string StrFormatBits(const uint64_t value, const std::size_t size=64)
Format value to "bits string".
std::vector< uint8_t > StrToVec(const std::string &str)
Convert string to buffer.
bool StrContains(const std::string &str, const std::string &sub)
Check if one string is contained within another string string.
std::string Sprintf(const char *const fmt,...) PRINTF_ATTR(1)
Format string.
bool StrStartsWith(const std::string &str, const std::string &prefix)
Check if one string starts with another string.
std::string StrJoin(const std::vector< std::string > &strs, const std::string &sep)
Join strings.
std::string StrError(const int errnum)
Stringify glibc error.
int StrReplace(std::string &str, const std::string &search, const std::string &replace, const int max=0)
Search and replace.
void MakeUnique(std::vector< std::string > &strs)
Remove duplicates.
Fixposition SDK.
#define PRINTF_ATTR(n)
Helper macro for marking functions as taking printf() style formatting strings.
Definition string.hpp:47