Bitcoin Core  23.99.0
P2P Digital Currency
Enumerations | Functions
strencodings.h File Reference
#include <span.h>
#include <util/string.h>
#include <charconv>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <optional>
#include <string>
#include <string_view>
#include <system_error>
#include <type_traits>
#include <vector>
Include dependency graph for strencodings.h:

Go to the source code of this file.

Enumerations

enum  SafeChars { SAFE_CHARS_DEFAULT, SAFE_CHARS_UA_COMMENT, SAFE_CHARS_FILENAME, SAFE_CHARS_URI }
 Utilities for converting data from/to strings. More...
 
enum  ByteUnit : uint64_t {
  ByteUnit::NOOP = 1ULL, ByteUnit::k = 1000ULL, ByteUnit::K = 1024ULL, ByteUnit::m = 1'000'000ULL,
  ByteUnit::M = 1ULL << 20, ByteUnit::g = 1'000'000'000ULL, ByteUnit::G = 1ULL << 30, ByteUnit::t = 1'000'000'000'000ULL,
  ByteUnit::T = 1ULL << 40
}
 Used by ParseByteUnits() Lowercase base 1000 Uppercase base 1024. More...
 

Functions

std::string SanitizeString (std::string_view str, int rule=SAFE_CHARS_DEFAULT)
 Remove unsafe chars. More...
 
template<typename Byte = uint8_t>
std::vector< Byte > ParseHex (std::string_view str)
 Parse the hex string into bytes (uint8_t or std::byte). More...
 
signed char HexDigit (char c)
 
bool IsHex (std::string_view str)
 
bool IsHexNumber (std::string_view str)
 Return true if the string is a hex number, optionally prefixed with "0x". More...
 
std::optional< std::vector< unsigned char > > DecodeBase64 (std::string_view str)
 
std::string EncodeBase64 (Span< const unsigned char > input)
 
std::string EncodeBase64 (Span< const std::byte > input)
 
std::string EncodeBase64 (std::string_view str)
 
std::optional< std::vector< unsigned char > > DecodeBase32 (std::string_view str)
 
std::string EncodeBase32 (Span< const unsigned char > input, bool pad=true)
 Base32 encode. More...
 
std::string EncodeBase32 (std::string_view str, bool pad=true)
 Base32 encode. More...
 
void SplitHostPort (std::string_view in, uint16_t &portOut, std::string &hostOut)
 
template<typename T >
LocaleIndependentAtoi (std::string_view str)
 
constexpr bool IsDigit (char c)
 Tests if the given character is a decimal digit. More...
 
constexpr bool IsSpace (char c) noexcept
 Tests if the given character is a whitespace character. More...
 
template<typename T >
std::optional< T > ToIntegral (std::string_view str)
 Convert string to integral type T. More...
 
bool ParseInt32 (std::string_view str, int32_t *out)
 Convert string to signed 32-bit integer with strict parse error feedback. More...
 
bool ParseInt64 (std::string_view str, int64_t *out)
 Convert string to signed 64-bit integer with strict parse error feedback. More...
 
bool ParseUInt8 (std::string_view str, uint8_t *out)
 Convert decimal string to unsigned 8-bit integer with strict parse error feedback. More...
 
bool ParseUInt16 (std::string_view str, uint16_t *out)
 Convert decimal string to unsigned 16-bit integer with strict parse error feedback. More...
 
bool ParseUInt32 (std::string_view str, uint32_t *out)
 Convert decimal string to unsigned 32-bit integer with strict parse error feedback. More...
 
bool ParseUInt64 (std::string_view str, uint64_t *out)
 Convert decimal string to unsigned 64-bit integer with strict parse error feedback. More...
 
std::string HexStr (const Span< const uint8_t > s)
 Convert a span of bytes to a lower-case hexadecimal string. More...
 
std::string HexStr (const Span< const char > s)
 
std::string HexStr (const Span< const std::byte > s)
 
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. More...
 
template<typename T >
bool TimingResistantEqual (const T &a, const T &b)
 Timing-attack-resistant comparison. More...
 
bool ParseFixedPoint (std::string_view, int decimals, int64_t *amount_out)
 Parse number as fixed point according to JSON number syntax. More...
 
template<int frombits, int tobits, bool pad, typename O , typename It , typename I = IntIdentity>
bool ConvertBits (O outfn, It it, It end, I infn={})
 Convert from one power-of-2 number base to another. More...
 
constexpr char ToLower (char c)
 Converts the given character to its lowercase equivalent. More...
 
std::string ToLower (std::string_view str)
 Returns the lowercase equivalent of the given string. More...
 
constexpr char ToUpper (char c)
 Converts the given character to its uppercase equivalent. More...
 
std::string ToUpper (std::string_view str)
 Returns the uppercase equivalent of the given string. More...
 
std::string Capitalize (std::string str)
 Capitalizes the first character of the given string. More...
 
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]. More...
 

Enumeration Type Documentation

◆ ByteUnit

enum ByteUnit : uint64_t
strong

Used by ParseByteUnits() Lowercase base 1000 Uppercase base 1024.

Enumerator
NOOP 

Definition at line 40 of file strencodings.h.

◆ SafeChars

enum SafeChars

Utilities for converting data from/to strings.

Used by SanitizeString()

Enumerator
SAFE_CHARS_DEFAULT 

The full set of allowed chars.

SAFE_CHARS_UA_COMMENT 

BIP-0014 subset.

SAFE_CHARS_FILENAME 

Chars allowed in filenames.

SAFE_CHARS_URI 

Chars allowed in URIs (RFC 3986)

Definition at line 27 of file strencodings.h.

Function Documentation

◆ Capitalize()

std::string Capitalize ( std::string  str)

Capitalizes the first character of the given string.

This function is locale independent. It only converts lowercase characters in the standard 7-bit ASCII range. This is a feature, not a limitation.

Parameters
[in]strthe string to capitalize.
Returns
string with the first letter capitalized.

Definition at line 452 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ConvertBits()

template<int frombits, int tobits, bool pad, typename O , typename It , typename I = IntIdentity>
bool ConvertBits ( outfn,
It  it,
It  end,
infn = {} 
)

Convert from one power-of-2 number base to another.

Definition at line 265 of file strencodings.h.

◆ DecodeBase32()

std::optional<std::vector<unsigned char> > DecodeBase32 ( std::string_view  str)

Definition at line 188 of file strencodings.cpp.

Here is the caller graph for this function:

◆ DecodeBase64()

std::optional<std::vector<unsigned char> > DecodeBase64 ( std::string_view  str)

Definition at line 133 of file strencodings.cpp.

Here is the caller graph for this function:

◆ EncodeBase32() [1/2]

std::string EncodeBase32 ( Span< const unsigned char >  input,
bool  pad = true 
)

Base32 encode.

If pad is true, then the output will be padded with '=' so that its length is a multiple of 8.

Definition at line 168 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ EncodeBase32() [2/2]

std::string EncodeBase32 ( std::string_view  str,
bool  pad = true 
)

Base32 encode.

If pad is true, then the output will be padded with '=' so that its length is a multiple of 8.

Definition at line 183 of file strencodings.cpp.

Here is the call graph for this function:

◆ EncodeBase64() [1/3]

std::string EncodeBase64 ( Span< const std::byte >  input)
inline

Definition at line 73 of file strencodings.h.

◆ EncodeBase64() [2/3]

std::string EncodeBase64 ( Span< const unsigned char >  input)

Definition at line 122 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ EncodeBase64() [3/3]

std::string EncodeBase64 ( std::string_view  str)
inline

Definition at line 74 of file strencodings.h.

◆ FormatParagraph()

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.

Definition at line 277 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ HexDigit()

signed char HexDigit ( char  c)

Definition at line 58 of file strencodings.cpp.

Here is the caller graph for this function:

◆ HexStr() [1/3]

std::string HexStr ( const Span< const char >  s)
inline

Definition at line 223 of file strencodings.h.

Here is the call graph for this function:

◆ HexStr() [2/3]

std::string HexStr ( const Span< const std::byte >  s)
inline

Definition at line 224 of file strencodings.h.

Here is the call graph for this function:

◆ HexStr() [3/3]

std::string HexStr ( const Span< const uint8_t >  s)

Convert a span of bytes to a lower-case hexadecimal string.

Definition at line 477 of file strencodings.cpp.

Here is the call graph for this function:

◆ IsDigit()

constexpr bool IsDigit ( char  c)
constexpr

Tests if the given character is a decimal digit.

Parameters
[in]ccharacter to test
Returns
true if the argument is a decimal digit; otherwise false.

Definition at line 137 of file strencodings.h.

Here is the caller graph for this function:

◆ IsHex()

bool IsHex ( std::string_view  str)

Definition at line 63 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ IsHexNumber()

bool IsHexNumber ( std::string_view  str)

Return true if the string is a hex number, optionally prefixed with "0x".

Definition at line 71 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ IsSpace()

constexpr bool IsSpace ( char  c)
inlineconstexprnoexcept

Tests if the given character is a whitespace character.

The whitespace characters are: space, form-feed ('\f'), newline ('
'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v').

This function is locale independent. Under the C locale this function gives the same result as std::isspace.

Parameters
[in]ccharacter to test
Returns
true if the argument is a whitespace character; otherwise false

Definition at line 153 of file strencodings.h.

Here is the caller graph for this function:

◆ LocaleIndependentAtoi()

template<typename T >
T LocaleIndependentAtoi ( std::string_view  str)

Definition at line 105 of file strencodings.h.

Here is the call graph for this function:

◆ ParseByteUnits()

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].

Must be a whole integer, fractions not allowed (0.5t), no whitespace or +- Lowercase units are 1000 base. Uppercase units are 1024 base. Examples: 2m,27M,19g,41T

Parameters
[in]strthe string to convert into bytes
[in]default_multiplierif no unit is found in str use this unit
Returns
optional uint64_t bytes from str or nullopt if ToIntegral is false, str is empty, trailing whitespace or overflow

Definition at line 493 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseFixedPoint()

bool ParseFixedPoint ( std::string_view  ,
int  decimals,
int64_t *  amount_out 
)

Parse number as fixed point according to JSON number syntax.

See https://json.org/number.gif

Returns
true on success, false on error.
Note
The result must be in the range (-10^18,10^18), otherwise an overflow error will trigger.

Definition at line 346 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ParseHex()

template<typename Byte = uint8_t>
std::vector<Byte> ParseHex ( std::string_view  str)

Parse the hex string into bytes (uint8_t or std::byte).

Ignores whitespace.

Definition at line 82 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ParseInt32()

bool ParseInt32 ( std::string_view  str,
int32_t *  out 
)

Convert string to signed 32-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if not the entire string could be parsed or when overflow or underflow occurred.

Definition at line 247 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseInt64()

bool ParseInt64 ( std::string_view  str,
int64_t *  out 
)

Convert string to signed 64-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if not the entire string could be parsed or when overflow or underflow occurred.

Definition at line 252 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseUInt16()

bool ParseUInt16 ( std::string_view  str,
uint16_t *  out 
)

Convert decimal string to unsigned 16-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if the entire string could not be parsed or if overflow or underflow occurred.

Definition at line 262 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseUInt32()

bool ParseUInt32 ( std::string_view  str,
uint32_t *  out 
)

Convert decimal string to unsigned 32-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if not the entire string could be parsed or when overflow or underflow occurred.

Definition at line 267 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseUInt64()

bool ParseUInt64 ( std::string_view  str,
uint64_t *  out 
)

Convert decimal string to unsigned 64-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if not the entire string could be parsed or when overflow or underflow occurred.

Definition at line 272 of file strencodings.cpp.

Here is the caller graph for this function:

◆ ParseUInt8()

bool ParseUInt8 ( std::string_view  str,
uint8_t *  out 
)

Convert decimal string to unsigned 8-bit integer with strict parse error feedback.

Returns
true if the entire string could be parsed as valid integer, false if not the entire string could be parsed or when overflow or underflow occurred.

Definition at line 257 of file strencodings.cpp.

Here is the caller graph for this function:

◆ SanitizeString()

std::string SanitizeString ( std::string_view  str,
int  rule = SAFE_CHARS_DEFAULT 
)

Remove unsafe chars.

Safe chars chosen to allow simple messages/URLs/email addresses, but avoid anything even possibly remotely dangerous like & or >

Parameters
[in]strThe string to sanitize
[in]ruleThe set of safe chars to choose (default: least restrictive)
Returns
A new string without unsafe chars

Definition at line 29 of file strencodings.cpp.

Here is the caller graph for this function:

◆ SplitHostPort()

void SplitHostPort ( std::string_view  in,
uint16_t &  portOut,
std::string &  hostOut 
)

Definition at line 101 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ TimingResistantEqual()

template<typename T >
bool TimingResistantEqual ( const T &  a,
const T &  b 
)

Timing-attack-resistant comparison.

Takes time proportional to length of first argument.

Definition at line 238 of file strencodings.h.

Here is the caller graph for this function:

◆ ToIntegral()

template<typename T >
std::optional<T> ToIntegral ( std::string_view  str)

Convert string to integral type T.

Leading whitespace, a leading +, or any trailing character fail the parsing. The required format expressed as regex is -?[0-9]+. The minus sign is only permitted for signed integer types.

Returns
std::nullopt if the entire string could not be parsed, or if the parsed value is not in the range representable by the type T.

Definition at line 166 of file strencodings.h.

◆ ToLower() [1/2]

constexpr char ToLower ( char  c)
constexpr

Converts the given character to its lowercase equivalent.

This function is locale independent. It only converts uppercase characters in the standard 7-bit ASCII range. This is a feature, not a limitation.

Parameters
[in]cthe character to convert to lowercase.
Returns
the lowercase equivalent of c; or the argument if no conversion is possible.

Definition at line 299 of file strencodings.h.

◆ ToLower() [2/2]

std::string ToLower ( std::string_view  str)

Returns the lowercase equivalent of the given string.

This function is locale independent. It only converts uppercase characters in the standard 7-bit ASCII range. This is a feature, not a limitation.

Parameters
[in]strthe string to convert to lowercase.
Returns
lowercased equivalent of str

Definition at line 438 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ToUpper() [1/2]

constexpr char ToUpper ( char  c)
constexpr

Converts the given character to its uppercase equivalent.

This function is locale independent. It only converts lowercase characters in the standard 7-bit ASCII range. This is a feature, not a limitation.

Parameters
[in]cthe character to convert to uppercase.
Returns
the uppercase equivalent of c; or the argument if no conversion is possible.

Definition at line 325 of file strencodings.h.

◆ ToUpper() [2/2]

std::string ToUpper ( std::string_view  str)

Returns the uppercase equivalent of the given string.

This function is locale independent. It only converts lowercase characters in the standard 7-bit ASCII range. This is a feature, not a limitation.

Parameters
[in]strthe string to convert to uppercase.
Returns
UPPERCASED EQUIVALENT OF str

Definition at line 445 of file strencodings.cpp.

Here is the call graph for this function:
Here is the caller graph for this function: