Bitcoin Core  26.99.0
P2P Digital Currency
strencodings.h
Go to the documentation of this file.
1 // Copyright (c) 2009-2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2022 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 
9 #ifndef BITCOIN_UTIL_STRENCODINGS_H
10 #define BITCOIN_UTIL_STRENCODINGS_H
11 
12 #include <span.h>
13 #include <util/string.h>
14 
15 #include <charconv>
16 #include <cstddef>
17 #include <cstdint>
18 #include <limits>
19 #include <optional>
20 #include <string> // IWYU pragma: export
21 #include <string_view> // IWYU pragma: export
22 #include <system_error>
23 #include <type_traits>
24 #include <vector>
25 
28 {
33 };
34 
40 enum class ByteUnit : uint64_t {
41  NOOP = 1ULL,
42  k = 1000ULL,
43  K = 1024ULL,
44  m = 1'000'000ULL,
45  M = 1ULL << 20,
46  g = 1'000'000'000ULL,
47  G = 1ULL << 30,
48  t = 1'000'000'000'000ULL,
49  T = 1ULL << 40,
50 };
51 
59 std::string SanitizeString(std::string_view str, int rule = SAFE_CHARS_DEFAULT);
61 template <typename Byte = std::byte>
62 std::optional<std::vector<Byte>> TryParseHex(std::string_view str);
64 template <typename Byte = uint8_t>
65 std::vector<Byte> ParseHex(std::string_view hex_str)
66 {
67  return TryParseHex<Byte>(hex_str).value_or(std::vector<Byte>{});
68 }
69 signed char HexDigit(char c);
70 /* Returns true if each character in str is a hex character, and has an even
71  * number of hex digits.*/
72 bool IsHex(std::string_view str);
76 bool IsHexNumber(std::string_view str);
77 std::optional<std::vector<unsigned char>> DecodeBase64(std::string_view str);
78 std::string EncodeBase64(Span<const unsigned char> input);
79 inline std::string EncodeBase64(Span<const std::byte> input) { return EncodeBase64(MakeUCharSpan(input)); }
80 inline std::string EncodeBase64(std::string_view str) { return EncodeBase64(MakeUCharSpan(str)); }
81 std::optional<std::vector<unsigned char>> DecodeBase32(std::string_view str);
82 
88 std::string EncodeBase32(Span<const unsigned char> input, bool pad = true);
89 
95 std::string EncodeBase32(std::string_view str, bool pad = true);
96 
106 bool SplitHostPort(std::string_view in, uint16_t& portOut, std::string& hostOut);
107 
108 // LocaleIndependentAtoi is provided for backwards compatibility reasons.
109 //
110 // New code should use ToIntegral or the ParseInt* functions
111 // which provide parse error feedback.
112 //
113 // The goal of LocaleIndependentAtoi is to replicate the defined behaviour of
114 // std::atoi as it behaves under the "C" locale, and remove some undefined
115 // behavior. If the parsed value is bigger than the integer type's maximum
116 // value, or smaller than the integer type's minimum value, std::atoi has
117 // undefined behavior, while this function returns the maximum or minimum
118 // values, respectively.
119 template <typename T>
120 T LocaleIndependentAtoi(std::string_view str)
121 {
122  static_assert(std::is_integral<T>::value);
123  T result;
124  // Emulate atoi(...) handling of white space and leading +/-.
125  std::string_view s = TrimStringView(str);
126  if (!s.empty() && s[0] == '+') {
127  if (s.length() >= 2 && s[1] == '-') {
128  return 0;
129  }
130  s = s.substr(1);
131  }
132  auto [_, error_condition] = std::from_chars(s.data(), s.data() + s.size(), result);
133  if (error_condition == std::errc::result_out_of_range) {
134  if (s.length() >= 1 && s[0] == '-') {
135  // Saturate underflow, per strtoll's behavior.
136  return std::numeric_limits<T>::min();
137  } else {
138  // Saturate overflow, per strtoll's behavior.
139  return std::numeric_limits<T>::max();
140  }
141  } else if (error_condition != std::errc{}) {
142  return 0;
143  }
144  return result;
145 }
146 
152 constexpr bool IsDigit(char c)
153 {
154  return c >= '0' && c <= '9';
155 }
156 
168 constexpr inline bool IsSpace(char c) noexcept {
169  return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' || c == '\v';
170 }
171 
180 template <typename T>
181 std::optional<T> ToIntegral(std::string_view str)
182 {
183  static_assert(std::is_integral<T>::value);
184  T result;
185  const auto [first_nonmatching, error_condition] = std::from_chars(str.data(), str.data() + str.size(), result);
186  if (first_nonmatching != str.data() + str.size() || error_condition != std::errc{}) {
187  return std::nullopt;
188  }
189  return result;
190 }
191 
197 [[nodiscard]] bool ParseInt32(std::string_view str, int32_t *out);
198 
204 [[nodiscard]] bool ParseInt64(std::string_view str, int64_t *out);
205 
211 [[nodiscard]] bool ParseUInt8(std::string_view str, uint8_t *out);
212 
218 [[nodiscard]] bool ParseUInt16(std::string_view str, uint16_t* out);
219 
225 [[nodiscard]] bool ParseUInt32(std::string_view str, uint32_t *out);
226 
232 [[nodiscard]] bool ParseUInt64(std::string_view str, uint64_t *out);
233 
237 std::string HexStr(const Span<const uint8_t> s);
238 inline std::string HexStr(const Span<const char> s) { return HexStr(MakeUCharSpan(s)); }
239 inline std::string HexStr(const Span<const std::byte> s) { return HexStr(MakeUCharSpan(s)); }
240 
245 std::string FormatParagraph(std::string_view in, size_t width = 79, size_t indent = 0);
246 
252 template <typename T>
253 bool TimingResistantEqual(const T& a, const T& b)
254 {
255  if (b.size() == 0) return a.size() == 0;
256  size_t accumulator = a.size() ^ b.size();
257  for (size_t i = 0; i < a.size(); i++)
258  accumulator |= size_t(a[i] ^ b[i%b.size()]);
259  return accumulator == 0;
260 }
261 
266 [[nodiscard]] bool ParseFixedPoint(std::string_view, int decimals, int64_t *amount_out);
267 
268 namespace {
270 struct IntIdentity
271 {
272  [[maybe_unused]] int operator()(int x) const { return x; }
273 };
274 
275 } // namespace
276 
278 template<int frombits, int tobits, bool pad, typename O, typename It, typename I = IntIdentity>
279 bool ConvertBits(O outfn, It it, It end, I infn = {}) {
280  size_t acc = 0;
281  size_t bits = 0;
282  constexpr size_t maxv = (1 << tobits) - 1;
283  constexpr size_t max_acc = (1 << (frombits + tobits - 1)) - 1;
284  while (it != end) {
285  int v = infn(*it);
286  if (v < 0) return false;
287  acc = ((acc << frombits) | v) & max_acc;
288  bits += frombits;
289  while (bits >= tobits) {
290  bits -= tobits;
291  outfn((acc >> bits) & maxv);
292  }
293  ++it;
294  }
295  if (pad) {
296  if (bits) outfn((acc << (tobits - bits)) & maxv);
297  } else if (bits >= frombits || ((acc << (tobits - bits)) & maxv)) {
298  return false;
299  }
300  return true;
301 }
302 
313 constexpr char ToLower(char c)
314 {
315  return (c >= 'A' && c <= 'Z' ? (c - 'A') + 'a' : c);
316 }
317 
327 std::string ToLower(std::string_view str);
328 
339 constexpr char ToUpper(char c)
340 {
341  return (c >= 'a' && c <= 'z' ? (c - 'a') + 'A' : c);
342 }
343 
353 std::string ToUpper(std::string_view str);
354 
364 std::string Capitalize(std::string str);
365 
377 std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_multiplier);
378 
379 #endif // BITCOIN_UTIL_STRENCODINGS_H
#define T(expected, seed, data)
constexpr auto MakeUCharSpan(V &&v) -> decltype(UCharSpanCast(Span{std::forward< V >(v)}))
Like the Span constructor, but for (const) unsigned char member types only.
Definition: span.h:304
std::string EncodeBase32(Span< const unsigned char > input, bool pad=true)
Base32 encode.
std::string Capitalize(std::string str)
Capitalizes the first character of the given string.
bool IsHexNumber(std::string_view str)
Return true if the string is a hex number, optionally prefixed with "0x".
bool ParseInt32(std::string_view str, int32_t *out)
Convert string to signed 32-bit integer with strict parse error feedback.
std::string HexStr(const Span< const uint8_t > s)
Convert a span of bytes to a lower-case hexadecimal string.
bool ParseUInt16(std::string_view str, uint16_t *out)
Convert decimal string to unsigned 16-bit integer with strict parse error feedback.
std::optional< uint64_t > ParseByteUnits(std::string_view str, ByteUnit default_multiplier)
Parse a string with suffix unit [k|K|m|M|g|G|t|T].
constexpr char ToLower(char c)
Converts the given character to its lowercase equivalent.
Definition: strencodings.h:313
constexpr bool IsDigit(char c)
Tests if the given character is a decimal digit.
Definition: strencodings.h:152
std::string EncodeBase64(Span< const unsigned char > input)
constexpr char ToUpper(char c)
Converts the given character to its uppercase equivalent.
Definition: strencodings.h:339
T LocaleIndependentAtoi(std::string_view str)
Definition: strencodings.h:120
std::optional< T > ToIntegral(std::string_view str)
Convert string to integral type T.
Definition: strencodings.h:181
bool ParseInt64(std::string_view str, int64_t *out)
Convert string to signed 64-bit integer with strict parse error feedback.
ByteUnit
Used by ParseByteUnits() Lowercase base 1000 Uppercase base 1024.
Definition: strencodings.h:40
bool TimingResistantEqual(const T &a, const T &b)
Timing-attack-resistant comparison.
Definition: strencodings.h:253
bool ParseUInt8(std::string_view str, uint8_t *out)
Convert decimal string to unsigned 8-bit integer with strict parse error feedback.
bool ParseFixedPoint(std::string_view, int decimals, int64_t *amount_out)
Parse number as fixed point according to JSON number syntax.
bool ParseUInt64(std::string_view str, uint64_t *out)
Convert decimal string to unsigned 64-bit integer with strict parse error feedback.
constexpr bool IsSpace(char c) noexcept
Tests if the given character is a whitespace character.
Definition: strencodings.h:168
signed char HexDigit(char c)
bool IsHex(std::string_view str)
std::optional< std::vector< unsigned char > > DecodeBase64(std::string_view str)
bool SplitHostPort(std::string_view in, uint16_t &portOut, std::string &hostOut)
Splits socket address string into host string and port value.
bool ParseUInt32(std::string_view str, uint32_t *out)
Convert decimal string to unsigned 32-bit integer with strict parse error feedback.
bool ConvertBits(O outfn, It it, It end, I infn={})
Convert from one power-of-2 number base to another.
Definition: strencodings.h:279
std::string FormatParagraph(std::string_view in, size_t width=79, size_t indent=0)
Format a paragraph of text to a fixed width, adding spaces for indentation to any added line.
std::string SanitizeString(std::string_view str, int rule=SAFE_CHARS_DEFAULT)
Remove unsafe chars.
std::optional< std::vector< Byte > > TryParseHex(std::string_view str)
Parse the hex string into bytes (uint8_t or std::byte).
std::vector< Byte > ParseHex(std::string_view hex_str)
Like TryParseHex, but returns an empty vector on invalid input.
Definition: strencodings.h:65
SafeChars
Utilities for converting data from/to strings.
Definition: strencodings.h:28
@ SAFE_CHARS_DEFAULT
The full set of allowed chars.
Definition: strencodings.h:29
@ SAFE_CHARS_UA_COMMENT
BIP-0014 subset.
Definition: strencodings.h:30
@ SAFE_CHARS_URI
Chars allowed in URIs (RFC 3986)
Definition: strencodings.h:32
@ SAFE_CHARS_FILENAME
Chars allowed in filenames.
Definition: strencodings.h:31
std::optional< std::vector< unsigned char > > DecodeBase32(std::string_view str)
std::string_view TrimStringView(std::string_view str, std::string_view pattern=" \f\n\r\t\v")
Definition: string.h:31
bilingual_str _(const char *psz)
Translation function.
Definition: translation.h:74