Inside Bitcoin

251 * @param[in] c     the character to convert to lowercase.
252 * @return          the lowercase equivalent of c; or the argument
253 *                  if no conversion is possible.
254 */
255constexpr char ToLower(char c)
256{
257    return (c >= 'A' && c <= 'Z' ? (c - 'A') + 'a' : c);
258}
259
260/**
261 * Returns the lowercase equivalent of the given string.
262 * This function is locale independent. It only converts uppercase
263 * characters in the standard 7-bit ASCII range.
264 * This is a feature, not a limitation.
265 *
266 * @param[in] str   the string to convert to lowercase.
267 * @returns         lowercased equivalent of str
268 */
269std::string ToLower(std::string_view str);
270
271/**
272 * Converts the given character to its uppercase equivalent.
273 * This function is locale independent. It only converts lowercase
274 * characters in the standard 7-bit ASCII range.
275 * This is a feature, not a limitation.
276 *
277 * @param[in] c     the character to convert to uppercase.
278 * @return          the uppercase equivalent of c; or the argument
279 *                  if no conversion is possible.
280 */
281constexpr char ToUpper(char c)
282{
283    return (c >= 'a' && c <= 'z' ? (c - 'a') + 'A' : c);
284}
285
286/**
287 * Returns the uppercase equivalent of the given string.
288 * This function is locale independent. It only converts lowercase
289 * characters in the standard 7-bit ASCII range.
290 * This is a feature, not a limitation.
291 *
292 * @param[in] str   the string to convert to uppercase.
293 * @returns         UPPERCASED EQUIVALENT OF str
294 */
295std::string ToUpper(std::string_view str);
296
297/**
298 * Capitalizes the first character of the given string.
299 * This function is locale independent. It only converts lowercase
300 * characters in the standard 7-bit ASCII range.
301 * This is a feature, not a limitation.
302 *
303 * @param[in] str   the string to capitalize.
304 * @returns         string with the first letter capitalized.
305 */
306std::string Capitalize(std::string str);
307
308/**
309 * Parse a string with suffix unit [k|K|m|M|g|G|t|T].
310 * Must be a whole integer, fractions not allowed (0.5t), no whitespace or +-
311 * Lowercase units are 1000 base. Uppercase units are 1024 base.
312 * Examples: 2m,27M,19g,41T
313 *
314 * @param[in] str                  the string to convert into bytes
315 * @param[in] default_multiplier   if no unit is found in str use this unit
316 * @returns                        optional uint64_t bytes from str or nullopt
317 *                                 if ToIntegral is false, str is empty, trailing whitespace or overflow
318 */
319std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_multiplier);
320
321/**
322 *  Locale-independent, ASCII-only comparator
323 *  @param[in] s1 a string to compare
324 *  @param[in] s2 another string to compare
325 *  @returns true if s1 == s2 when both strings are converted to lowercase
326 */
327bool CaseInsensitiveEqual(std::string_view s1, std::string_view s2);
328
329namespace util {
330/** consteval version of HexDigit() without the lookup table. */
331consteval 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
339namespace detail {
340template <size_t N>
341struct 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/**
358 * ""_hex is a compile-time user-defined literal returning a
359 * `std::array<std::byte>`, equivalent to ParseHex(). Variants provided:
360 *
361 * - ""_hex_v: Returns `std::vector<std::byte>`, useful for heap allocation or
362 *   variable-length serialization.
363 *
364 * - ""_hex_u8: Returns `std::array<uint8_t>`, for cases where `std::byte` is
365 *   incompatible.
366 *
367 * - ""_hex_v_u8: Returns `std::vector<uint8_t>`, combining heap allocation with
368 *   `uint8_t`.
369 *
370 * @warning It could be necessary to use vector instead of array variants when
371 *   serializing, or vice versa, because vectors are assumed to be variable-
372 *   length and serialized with a size prefix, while arrays are considered fixed
373 *   length and serialized with no prefix.
374 *
375 * @warning It may be preferable to use vector variants to save stack space when
376 *   declaring local variables if hex strings are large. Alternatively variables
377 *   could be declared constexpr to avoid using stack space.
378 *
379 * @warning Avoid `uint8_t` variants when not necessary, as the codebase
380 *   migrates to use `std::byte` instead of `unsigned char` and `uint8_t`.
381 *
382 * @note One reason ""_hex uses `std::array` instead of `std::vector` like
383 *   ParseHex() does is because heap-based containers cannot cross the compile-
384 *   time/runtime barrier.
385 */
386inline namespace hex_literals {
387
388template <util::detail::Hex str>
389constexpr auto operator""_hex() { return str.bytes; }
390
391template <util::detail::Hex str>
392constexpr auto operator""_hex_u8() { return std::bit_cast<std::array<uint8_t, str.bytes.size()>>(str.bytes); }
393
394template <util::detail::Hex str>
395constexpr auto operator""_hex_v() { return std::vector<std::byte>{str.bytes.begin(), str.bytes.end()}; }
396
397template <util::detail::Hex str>
398inline auto operator""_hex_v_u8() { return std::vector<uint8_t>{UCharCast(str.bytes.data()), UCharCast(str.bytes.data() + str.bytes.size())}; }
399
400} // inline namespace hex_literals
401} // namespace util
402
403#endif // BITCOIN_UTIL_STRENCODINGS_H
404