Branch data Line data Source code
1 : : // Copyright (c) 2009-2010 Satoshi Nakamoto
2 : : // Copyright (c) 2009-present The Bitcoin Core developers
3 : : // Distributed under the MIT software license, see the accompanying
4 : : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5 : :
6 : : /**
7 : : * Utilities for converting data from/to strings.
8 : : */
9 : : #ifndef BITCOIN_UTIL_STRENCODINGS_H
10 : : #define BITCOIN_UTIL_STRENCODINGS_H
11 : :
12 : : #include <crypto/hex_base.h>
13 : : #include <span.h>
14 : : #include <util/string.h>
15 : :
16 : : #include <algorithm>
17 : : #include <array>
18 : : #include <bit>
19 : : #include <charconv>
20 : : #include <cstddef>
21 : : #include <cstdint>
22 : : #include <limits>
23 : : #include <optional>
24 : : #include <string>
25 : : #include <string_view>
26 : : #include <system_error>
27 : : #include <type_traits>
28 : : #include <vector>
29 : :
30 : : /** Used by SanitizeString() */
31 : : enum SafeChars
32 : : {
33 : : SAFE_CHARS_DEFAULT, //!< The full set of allowed chars
34 : : SAFE_CHARS_UA_COMMENT, //!< BIP-0014 subset
35 : : SAFE_CHARS_FILENAME, //!< Chars allowed in filenames
36 : : SAFE_CHARS_URI, //!< Chars allowed in URIs (RFC 3986)
37 : : };
38 : :
39 : : /**
40 : : * Used by ParseByteUnits()
41 : : * Lowercase base 1000
42 : : * Uppercase base 1024
43 : : */
44 : : enum class ByteUnit : uint64_t {
45 : : NOOP = 1ULL,
46 : : k = 1000ULL,
47 : : K = 1024ULL,
48 : : m = 1'000'000ULL,
49 : : M = 1ULL << 20,
50 : : g = 1'000'000'000ULL,
51 : : G = 1ULL << 30,
52 : : t = 1'000'000'000'000ULL,
53 : : T = 1ULL << 40,
54 : : };
55 : :
56 : : /**
57 : : * Remove unsafe chars. Safe chars chosen to allow simple messages/URLs/email
58 : : * addresses, but avoid anything even possibly remotely dangerous like & or >
59 : : * @param[in] str The string to sanitize
60 : : * @param[in] rule The set of safe chars to choose (default: least restrictive)
61 : : * @return A new string without unsafe chars
62 : : */
63 : : std::string SanitizeString(std::string_view str, int rule = SAFE_CHARS_DEFAULT);
64 : : /** Parse the hex string into bytes (uint8_t or std::byte). Ignores whitespace. Returns nullopt on invalid input. */
65 : : template <typename Byte = std::byte>
66 : : std::optional<std::vector<Byte>> TryParseHex(std::string_view str);
67 : : /** Like TryParseHex, but returns an empty vector on invalid input. */
68 : : template <typename Byte = uint8_t>
69 : 5585 : std::vector<Byte> ParseHex(std::string_view hex_str)
70 : : {
71 : 5585 : return TryParseHex<Byte>(hex_str).value_or(std::vector<Byte>{});
72 : : }
73 : : /* Returns true if each character in str is a hex character, and has an even
74 : : * number of hex digits.*/
75 : : bool IsHex(std::string_view str);
76 : : std::optional<std::vector<unsigned char>> DecodeBase64(std::string_view str);
77 : : std::string EncodeBase64(std::span<const unsigned char> input);
78 : 1 : inline std::string EncodeBase64(std::span<const std::byte> input) { return EncodeBase64(MakeUCharSpan(input)); }
79 : 9 : inline std::string EncodeBase64(std::string_view str) { return EncodeBase64(MakeUCharSpan(str)); }
80 : : std::optional<std::vector<unsigned char>> DecodeBase32(std::string_view str);
81 : :
82 : : /**
83 : : * Base32 encode.
84 : : * If `pad` is true, then the output will be padded with '=' so that its length
85 : : * is a multiple of 8.
86 : : */
87 : : std::string EncodeBase32(std::span<const unsigned char> input, bool pad = true);
88 : :
89 : : /**
90 : : * Base32 encode.
91 : : * If `pad` is true, then the output will be padded with '=' so that its length
92 : : * is a multiple of 8.
93 : : */
94 : : std::string EncodeBase32(std::string_view str, bool pad = true);
95 : :
96 : : /**
97 : : * Splits socket address string into host string and port value.
98 : : * Validates port value.
99 : : *
100 : : * @param[in] in The socket address string to split.
101 : : * @param[out] portOut Port-portion of the input, if found and parsable.
102 : : * @param[out] hostOut Host-portion of the input, if found.
103 : : * @return true if port-portion is absent or within its allowed range, otherwise false
104 : : */
105 : : bool SplitHostPort(std::string_view in, uint16_t& portOut, std::string& hostOut);
106 : :
107 : : // LocaleIndependentAtoi is provided for backwards compatibility reasons.
108 : : //
109 : : // New code should use ToIntegral.
110 : : //
111 : : // The goal of LocaleIndependentAtoi is to replicate the defined behaviour of
112 : : // std::atoi as it behaves under the "C" locale, and remove some undefined
113 : : // behavior. If the parsed value is bigger than the integer type's maximum
114 : : // value, or smaller than the integer type's minimum value, std::atoi has
115 : : // undefined behavior, while this function returns the maximum or minimum
116 : : // values, respectively.
117 : : template <typename T>
118 : 106341 : T LocaleIndependentAtoi(std::string_view str)
119 : : {
120 : : static_assert(std::is_integral_v<T>);
121 : : T result;
122 : : // Emulate atoi(...) handling of white space and leading +/-.
123 [ + + ]: 106341 : std::string_view s = util::TrimStringView(str);
124 [ + + + + ]: 106341 : if (!s.empty() && s[0] == '+') {
125 [ + - + + ]: 24 : if (s.length() >= 2 && s[1] == '-') {
126 : : return 0;
127 : : }
128 : 18 : s = s.substr(1);
129 : : }
130 : 106335 : auto [_, error_condition] = std::from_chars(s.data(), s.data() + s.size(), result);
131 [ + + ]: 106335 : if (error_condition == std::errc::result_out_of_range) {
132 [ + - + + ]: 38 : if (s.length() >= 1 && s[0] == '-') {
133 : : // Saturate underflow, per strtoll's behavior.
134 : : return std::numeric_limits<T>::min();
135 : : } else {
136 : : // Saturate overflow, per strtoll's behavior.
137 : : return std::numeric_limits<T>::max();
138 : : }
139 [ + + ]: 106297 : } else if (error_condition != std::errc{}) {
140 : : return 0;
141 : : }
142 : 106211 : return result;
143 : : }
144 : :
145 : : /**
146 : : * Tests if the given character is a decimal digit.
147 : : * @param[in] c character to test
148 : : * @return true if the argument is a decimal digit; otherwise false.
149 : : */
150 : 326612 : constexpr bool IsDigit(char c)
151 : : {
152 [ + + + + : 326612 : return c >= '0' && c <= '9';
+ + # # #
# ][ + + +
- + + + -
+ - ]
153 : : }
154 : :
155 : : /**
156 : : * Tests if the given character is a whitespace character. The whitespace characters
157 : : * are: space, form-feed ('\f'), newline ('\n'), carriage return ('\r'), horizontal
158 : : * tab ('\t'), and vertical tab ('\v').
159 : : *
160 : : * This function is locale independent. Under the C locale this function gives the
161 : : * same result as std::isspace.
162 : : *
163 : : * @param[in] c character to test
164 : : * @return true if the argument is a whitespace character; otherwise false
165 : : */
166 : 470414 : constexpr inline bool IsSpace(char c) noexcept {
167 [ + + + + : 470414 : return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' || c == '\v';
+ + ]
168 : : }
169 : :
170 : : /**
171 : : * Convert string to integral type T. Leading whitespace, a leading +, or any
172 : : * trailing character fail the parsing. The required format expressed as regex
173 : : * is `-?[0-9]+` by default (or `-?[0-9a-fA-F]+` if base = 16).
174 : : * The minus sign is only permitted for signed integer types.
175 : : *
176 : : * @returns std::nullopt if the entire string could not be parsed, or if the
177 : : * parsed value is not in the range representable by the type T.
178 : : */
179 : : template <typename T>
180 : 13546 : std::optional<T> ToIntegral(std::string_view str, size_t base = 10)
181 : : {
182 : : static_assert(std::is_integral_v<T>);
183 : : T result;
184 : 13546 : const auto [first_nonmatching, error_condition] = std::from_chars(str.data(), str.data() + str.size(), result, base);
185 [ + + + + ]: 13546 : if (first_nonmatching != str.data() + str.size() || error_condition != std::errc{}) {
186 : 564 : return std::nullopt;
187 : : }
188 : 12982 : return result;
189 : : }
190 : :
191 : : /**
192 : : * Format a paragraph of text to a fixed width, adding spaces for
193 : : * indentation to any added line.
194 : : */
195 : : std::string FormatParagraph(std::string_view in, size_t width = 79, size_t indent = 0);
196 : :
197 : : /**
198 : : * Timing-attack-resistant comparison.
199 : : * Takes time proportional to length
200 : : * of first argument.
201 : : */
202 : : template <typename T>
203 [ - + ]: 14 : bool TimingResistantEqual(const T& a, const T& b)
204 : : {
205 [ + + ]: 18 : if (b.size() == 0) return a.size() == 0;
206 : 10 : size_t accumulator = a.size() ^ b.size();
207 [ + + ]: 28 : for (size_t i = 0; i < a.size(); i++)
208 : 18 : accumulator |= size_t(a[i] ^ b[i%b.size()]);
209 : 10 : return accumulator == 0;
210 : : }
211 : :
212 : : /** Parse number as fixed point according to JSON number syntax.
213 : : * @returns true on success, false on error.
214 : : * @note The result must be in the range (-10^18,10^18), otherwise an overflow error will trigger.
215 : : */
216 : : [[nodiscard]] bool ParseFixedPoint(std::string_view, int decimals, int64_t *amount_out);
217 : :
218 : : namespace {
219 : : /** Helper class for the default infn argument to ConvertBits (just returns the input). */
220 : : struct IntIdentity
221 : : {
222 : : [[maybe_unused]] int operator()(int x) const { return x; }
223 : : };
224 : :
225 : : } // namespace
226 : :
227 : : /** Convert from one power-of-2 number base to another. */
228 : : template<int frombits, int tobits, bool pad, typename O, typename It, typename I = IntIdentity>
229 : 6477 : bool ConvertBits(O outfn, It it, It end, I infn = {}) {
230 : 6477 : size_t acc = 0;
231 : 6477 : size_t bits = 0;
232 : 6477 : constexpr size_t maxv = (1 << tobits) - 1;
233 : 6477 : constexpr size_t max_acc = (1 << (frombits + tobits - 1)) - 1;
234 [ + + ]: 144703 : while (it != end) {
235 [ + + ]: 138238 : int v = infn(*it);
236 [ + + ]: 3274 : if (v < 0) return false;
237 : 138226 : acc = ((acc << frombits) | v) & max_acc;
238 : 138226 : bits += frombits;
239 [ + + ]: 351380 : while (bits >= tobits) {
240 : 213154 : bits -= tobits;
241 : 213154 : outfn((acc >> bits) & maxv);
242 : : }
243 : 138226 : ++it;
244 : : }
245 : : if (pad) {
246 [ + + ]: 6310 : if (bits) outfn((acc << (tobits - bits)) & maxv);
247 [ + + + + ]: 155 : } else if (bits >= frombits || ((acc << (tobits - bits)) & maxv)) {
248 : 6 : return false;
249 : : }
250 : : return true;
251 : : }
252 : :
253 : : /**
254 : : * Converts the given character to its lowercase equivalent.
255 : : * This function is locale independent. It only converts uppercase
256 : : * characters in the standard 7-bit ASCII range.
257 : : * This is a feature, not a limitation.
258 : : *
259 : : * @param[in] c the character to convert to lowercase.
260 : : * @return the lowercase equivalent of c; or the argument
261 : : * if no conversion is possible.
262 : : */
263 : 1939 : constexpr char ToLower(char c)
264 : : {
265 [ + + # # ]: 1939 : return (c >= 'A' && c <= 'Z' ? (c - 'A') + 'a' : c);
[ # # ]
266 : : }
267 : :
268 : : /**
269 : : * Returns the lowercase equivalent of the given string.
270 : : * This function is locale independent. It only converts uppercase
271 : : * characters in the standard 7-bit ASCII range.
272 : : * This is a feature, not a limitation.
273 : : *
274 : : * @param[in] str the string to convert to lowercase.
275 : : * @returns lowercased equivalent of str
276 : : */
277 : : std::string ToLower(std::string_view str);
278 : :
279 : : /**
280 : : * Converts the given character to its uppercase equivalent.
281 : : * This function is locale independent. It only converts lowercase
282 : : * characters in the standard 7-bit ASCII range.
283 : : * This is a feature, not a limitation.
284 : : *
285 : : * @param[in] c the character to convert to uppercase.
286 : : * @return the uppercase equivalent of c; or the argument
287 : : * if no conversion is possible.
288 : : */
289 : 31 : constexpr char ToUpper(char c)
290 : : {
291 [ + - + + ]: 31 : return (c >= 'a' && c <= 'z' ? (c - 'a') + 'A' : c);
292 : : }
293 : :
294 : : /**
295 : : * Returns the uppercase equivalent of the given string.
296 : : * This function is locale independent. It only converts lowercase
297 : : * characters in the standard 7-bit ASCII range.
298 : : * This is a feature, not a limitation.
299 : : *
300 : : * @param[in] str the string to convert to uppercase.
301 : : * @returns UPPERCASED EQUIVALENT OF str
302 : : */
303 : : std::string ToUpper(std::string_view str);
304 : :
305 : : /**
306 : : * Capitalizes the first character of the given string.
307 : : * This function is locale independent. It only converts lowercase
308 : : * characters in the standard 7-bit ASCII range.
309 : : * This is a feature, not a limitation.
310 : : *
311 : : * @param[in] str the string to capitalize.
312 : : * @returns string with the first letter capitalized.
313 : : */
314 : : std::string Capitalize(std::string str);
315 : :
316 : : /**
317 : : * Parse a string with suffix unit [k|K|m|M|g|G|t|T].
318 : : * Must be a whole integer, fractions not allowed (0.5t), no whitespace or +-
319 : : * Lowercase units are 1000 base. Uppercase units are 1024 base.
320 : : * Examples: 2m,27M,19g,41T
321 : : *
322 : : * @param[in] str the string to convert into bytes
323 : : * @param[in] default_multiplier if no unit is found in str use this unit
324 : : * @returns optional uint64_t bytes from str or nullopt
325 : : * if ToIntegral is false, str is empty, trailing whitespace or overflow
326 : : */
327 : : std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_multiplier);
328 : :
329 : : namespace util {
330 : : /** consteval version of HexDigit() without the lookup table. */
331 : : consteval uint8_t ConstevalHexDigit(const char c)
332 : : {
333 : : if (c >= '0' && c <= '9') return c - '0';
334 : : if (c >= 'a' && c <= 'f') return c - 'a' + 0xa;
335 : :
336 : : throw "Only lowercase hex digits are allowed, for consistency";
337 : : }
338 : :
339 : : namespace detail {
340 : : template <size_t N>
341 : : struct Hex {
342 : : std::array<std::byte, N / 2> bytes{};
343 : : consteval Hex(const char (&hex_str)[N])
344 : : // 2 hex digits required per byte + implicit null terminator
345 : : requires(N % 2 == 1)
346 : : {
347 : : if (hex_str[N - 1]) throw "null terminator required";
348 : : for (std::size_t i = 0; i < bytes.size(); ++i) {
349 : : bytes[i] = static_cast<std::byte>(
350 : : (ConstevalHexDigit(hex_str[2 * i]) << 4) |
351 : : ConstevalHexDigit(hex_str[2 * i + 1]));
352 : : }
353 : : }
354 : : };
355 : : } // namespace detail
356 : :
357 : : struct AsciiCaseInsensitiveKeyEqual {
358 : 16 : bool operator()(std::string_view s1, std::string_view s2) const
359 : : {
360 [ + - ]: 16 : return ToLower(s1) == ToLower(s2);
361 : : }
362 : : };
363 : :
364 : : struct AsciiCaseInsensitiveHash {
365 : 10 : size_t operator()(std::string_view s) const
366 : : {
367 [ - + ]: 20 : return std::hash<std::string>{}(ToLower(s));
368 : : }
369 : : };
370 : :
371 : : /**
372 : : * ""_hex is a compile-time user-defined literal returning a
373 : : * `std::array<std::byte>`, equivalent to ParseHex(). Variants provided:
374 : : *
375 : : * - ""_hex_v: Returns `std::vector<std::byte>`, useful for heap allocation or
376 : : * variable-length serialization.
377 : : *
378 : : * - ""_hex_u8: Returns `std::array<uint8_t>`, for cases where `std::byte` is
379 : : * incompatible.
380 : : *
381 : : * - ""_hex_v_u8: Returns `std::vector<uint8_t>`, combining heap allocation with
382 : : * `uint8_t`.
383 : : *
384 : : * @warning It could be necessary to use vector instead of array variants when
385 : : * serializing, or vice versa, because vectors are assumed to be variable-
386 : : * length and serialized with a size prefix, while arrays are considered fixed
387 : : * length and serialized with no prefix.
388 : : *
389 : : * @warning It may be preferable to use vector variants to save stack space when
390 : : * declaring local variables if hex strings are large. Alternatively variables
391 : : * could be declared constexpr to avoid using stack space.
392 : : *
393 : : * @warning Avoid `uint8_t` variants when not necessary, as the codebase
394 : : * migrates to use `std::byte` instead of `unsigned char` and `uint8_t`.
395 : : *
396 : : * @note One reason ""_hex uses `std::array` instead of `std::vector` like
397 : : * ParseHex() does is because heap-based containers cannot cross the compile-
398 : : * time/runtime barrier.
399 : : */
400 : : inline namespace hex_literals {
401 : :
402 : : template <util::detail::Hex str>
403 : : constexpr auto operator""_hex() { return str.bytes; }
404 : :
405 : : template <util::detail::Hex str>
406 : : constexpr auto operator""_hex_u8() { return std::bit_cast<std::array<uint8_t, str.bytes.size()>>(str.bytes); }
407 : :
408 : : template <util::detail::Hex str>
409 [ + - + - ]: 4 : constexpr auto operator""_hex_v() { return std::vector<std::byte>{str.bytes.begin(), str.bytes.end()}; }
410 : :
411 : : template <util::detail::Hex str>
412 [ + - ][ + - : 985 : inline auto operator""_hex_v_u8() { return std::vector<uint8_t>{UCharCast(str.bytes.data()), UCharCast(str.bytes.data() + str.bytes.size())}; }
+ - + - +
- + - + -
+ - + - +
- + - # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # ][ + -
+ - # # #
# # # # #
# # # # #
# # # ][ +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - + -
+ - + - +
- + - ]
413 : :
414 : : } // inline namespace hex_literals
415 : : } // namespace util
416 : :
417 : : #endif // BITCOIN_UTIL_STRENCODINGS_H
|
