cppcodec

cppcodec

Header-only C++11 library to encode/decode base64, base64url, base32, base32hex and hex (a.k.a. base16) as specified in RFC 4648, plus Crockford's base32.

MIT licensed with consistent, flexible API. Supports raw pointers, std::string and (templated) character vectors without unnecessary allocations. Cross-platform with measured decent performance and without compiler warnings.

Contents

• Usage

• Variants

  • base64

  • base32

  • hex

• Philosophy and trade-offs

• API

  • Encoding

  • Decoding

Usage

1. Import cppcodec into your project (copy, git submodule, etc.)
2. Add the cppcodec root directory to your build system's list of include directories
3. Include headers and start using the API.

Since cppcodec is a header-only library, no extra build step is needed. Alternatively, you can install the headers and build extra tools/tests with CMake.

Variants

A number of codec variants exist for base64 and base32, defining different alphabets or specifying the use of padding and line breaks in different ways. cppcodec is designed to let you make a conscious choice about which one you're using, see below for a list of variants.

cppcodec's approach is to implement encoding/decoding algorithms in different classes for namespacing (e.g. cppcodec::base64_rfc4648), with classes and their associated header files named verbatim after the codec variants.

Here is an expected standard use of cppcodec:

#include 
#include 
#include 

int main() {
  using base32 = cppcodec::base32_crockford;
  using base64 = cppcodec::base64_rfc4648;

  std::vector decoded = base64::decode("YW55IGNhcm5hbCBwbGVhc3VyZQ==");
  std::cout `,
`std::string` or anything that supports:
* `.data()` and `.size()` for `T` (read-only) template parameters,
* for `Result` template parameters, also `.reserve(size_t)`, `.resize(size_t)`
  and `.push_back([uint8_t|char])`.

It's possible to support types lacking these functions, consult the code directly if you need this.

### Encoding

```C++
// Convenient version, returns an std::string.
std::string ::encode(const [uint8_t|char]* binary, size_t binary_size);
std::string ::encode(const T& binary);

// Convenient version with templated result type.
Result ::encode(const [uint8_t|char]* binary, size_t binary_size);
Result ::encode(const T& binary);

// Reused result container version. Resizes encoded_result before writing to it.
void ::encode(Result& encoded_result, const [uint8_t|char]* binary, size_t binary_size);
void ::encode(Result& encoded_result, const T& binary);

Encode binary data into an encoded (base64/base32/hex) string. Won't throw by itself, but the result type might throw on .resize().

size_t ::encode(char* encoded_result, size_t encoded_buffer_size, const [uint8_t|char]* binary, size_t binary_size) noexcept;
size_t ::encode(char* encoded_result, size_t encoded_buffer_size, const T& binary) noexcept;

…

C++
size_t ::encoded_size(size_t binary_size) noexcept;

Calculate the (exact) length of the encoded string based on binary size, excluding null termination but including padding (if specified by the codec variant).

Decoding

// Convenient version, returns an std::vector.
std::vector ::decode(const char* encoded, size_t encoded_size);
std::vector ::decode(const T& encoded);

// Convenient version with templated result type.
Result ::decode(const char* encoded, size_t encoded_size);
Result ::decode(const T& encoded);

// Reused result container version. Resizes binary_result before writing to it.
void ::decode(Result& binary_result, const char* encoded, size_t encoded_size);
void ::decode(Result& binary_result, const T& encoded);

Decode an encoded (base64/base32/hex) string into a binary buffer.

Throws a cppcodec::parse_error exception (inheriting from std::domain_error) if the input data does not conform to the codec variant specification. Also, the result type might throw on .resize().

size_t ::decode([uint8_t|char]* binary_result, size_t binary_buffer_size, const char* encoded, size_t encoded_size);
size_t ::decode([uint8_t|char]* binary_result, size_t binary_buffer_size, const T& encoded);

Decode an encoded string into pre-allocated memory with a buffer size of ::decoded_max_size(encoded_size) or larger.

Returns the byte size of the decoded binary data, which is less or equal to ::decoded_max_size(encoded_size).

Calls abort() if binary_buffer_size is insufficient, for consistency with encode(). Throws a cppcodec::parse_error exception (inheriting from std::domain_error) if the input data does not conform to the codec variant specification.

size_t ::decoded_max_size(size_t encoded_size) noexcept;

Calculate the maximum size of the decoded binary buffer based on the encoded string length.

If the codec variant does not allow padding or whitespace / line breaks, the maximum decoded size will be the exact decoded size.

If the codec variant allows padding or whitespace / line breaks, the actual decoded size might be smaller. If you're using the pre-allocated memory result call, make sure to take its return value (the actual decoded size) into account.