userver: userver/utils/encoding/hex.hpp Source File
Loading...
Searching...
No Matches
hex.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/utils/encoding/hex.hpp
4/// @brief Encoders, decoders and helpers for hexadecimal representations
5/// @ingroup userver_universal
6
7#include <cstdint>
8#include <string>
9
10USERVER_NAMESPACE_BEGIN
11
12namespace utils::encoding {
13
14/// @brief Converts number to hex character; number must be within range [0,16)
15/// @throws out_of_bounds exception if \p num is out of range
16char ToHexChar(int num);
17
18/// @brief Calculate expected length of input after being hex encoded
19/// @{
20
21constexpr size_t LengthInHexForm(size_t size) noexcept { return size * 2; }
22
23constexpr size_t LengthInHexForm(std::string_view data) noexcept {
24 return LengthInHexForm(data.size());
25}
26/// @}
27
28/// @brief Return upper limit on number of characters required
29/// to unhex input of given size.
30///
31/// For example:
32/// - FromHexUpperBound(1) = 0, because you can't really unhex one char,
33/// it is only half byte. Where is the second half?
34/// - FromHexUpperBound(2) = 1. Two chars will be converted into one byte
35/// - FromHexUpperBound(5) = 2. First 4 chars will be unhexed into 2 bytes,
36/// and there will be one left.
37constexpr size_t FromHexUpperBound(size_t size) noexcept {
38 // Although only even-sized input is valid, we have to support an odd
39 // number is well. Luckily for us, size / 2 will get us correct value
40 // anyway
41 return size / 2;
42}
43
44/// @brief Converts input to hex and writes data to output \p out
45/// @param input bytes to convert
46/// @param out string to write data. out will be cleared
47void ToHex(std::string_view input, std::string& out) noexcept;
48
49/// @brief Allocates std::string, converts input and writes into said string
50/// @param input range of input bytes
51inline std::string ToHex(std::string_view data) noexcept {
52 std::string result;
53 ToHex(data, result);
54 return result;
55}
56
57/// @brief Allocates std::string, converts input and writes into said string
58/// @param data start of continuous range in memory
59/// @param len size of that range
60inline std::string ToHex(const void* encoded, size_t len) noexcept {
61 const auto* chars = reinterpret_cast<const char*>(encoded);
62 return ToHex(std::string_view{chars, len});
63}
64
65/// @brief Converts as much of input from hex as possible and writes data
66/// into \p out.
67///
68/// To convert some range from hex, range
69/// must have even number of elements and every element must be hex character.
70/// To avoid throwing, algorithms consumes as much data as possible and returns
71/// how much it was able to process
72///
73/// @param encoded input range to convert
74/// @param out Result will be written into out. Previous value will be cleared.
75/// @returns Number of characters successfully parsed.
77
78/// @brief This FromHex overload allocates string and calls FromHex; if data
79/// is not fully a hex string, then it will be only partially processed.
80inline std::string FromHex(std::string_view encoded) noexcept {
81 std::string result;
82 FromHex(encoded, result);
83 return result;
84}
85
86/// Returns range that constitutes hex string - e.g. sub-view of encoded
87/// that could be fully interpreted as hex string.
88/// Basically, if you have string_view \p a and c = GetHexPart(a), then
89/// range FromHex(c) will be fully parsed.
90/// @param encoded input array of bytes.
92
93/// @brief Checks that given range is fully a hex string. That is, if passed to
94/// FromHex, it will be fully processed
95bool IsHexData(std::string_view encoded) noexcept;
96
97/// @brief iterprets uint64_t value as array of bytes and applies ToHex to it
98inline std::string ToHexString(uint64_t value) {
99 return ToHex(&value, sizeof(value));
100}
101
102} // namespace utils::encoding
103
104USERVER_NAMESPACE_END