Chapter 29. Base64 encoding and decoding


#include <x/base64.H>

typedef x::base64<0> base64_t;

The x::base64 template class defines iterators and convenience functions that implement the base64 encoding, as defined in RFC 4648.

x::base64 takes two optional template parameters. The first parameter is the character that pads out the trailing partial base64-encoded sequence, which defaults to the '=' character. Explicitly setting the padding character to '\0', or just a 0, disables the padding. x::base64_nopad is a typedef for a standard base64 alphabet, without padding.

The second optional template parameter defaults to x::base64alphabet<>, and specifies the base64 alphabet.

x::base64alphabet itself has two optional template parameters, both are char values. They specify the characters for the 62nd and the 63rd position of the base64 alphabet, and they default to '+' and '/', the default base64 alphabet.

typedef x::base64alphabet<'-',','> alphabet_t;

typedef x::base64<'=', alphabet_t> base64_t;

This example implements a non-standard base64 alphabet with '-' and ',' as the 62nd and the 63rd alphabet character, and the default padding character of '='.


std::stringstream o;

typedef std::ostreambuf_iterator<char> o_iter;

auto enciter=base64_t::encoder<o_iter>(o_iter(o));


o_iter value=enciter.eof();

x::base64::encoder takes an output iterator over chars as its template parameter. The constructor takes an instance of this output iterator type, the underlying output iterator. x::base64::encoder is an output iterator over chars that base64-encodes the sequence and outputs the base64-encoded sequence to the underlying output iterator.

Invoke eof() after writing the entire sequence to the the encoder. eof() writes out any final, partial, base64 sequence, possibly padded, to the underlying output iterator and returns the current output iterator value.

auto enciter=base64_t::encoder<o_iter>(o_iter(o), 0);

There is a second, optional, parameter to x::base64::encoder's constructor. It sets the line size of the base64-encoded sequence. The default value of 76 writes a newline after every 76 base64 characters. The given line size gets rounded up to an even multiple of 4. Setting the line value to 0, as in this example, results in no newlines in the base64-encoded sequence. The input sequence gets base64-encoded without any line breaks.

auto enciter=base64_t::encoder<o_iter>(o_iter(o), 76, true);

Setting the third parameter to x::base64::encoder's constructor, also optional, to true uses "\r\n" instead of "\n" for the newline sequence.

size_t needed=base64_t::encoded_size(buffer.size());

For convenience, encoded_size() calculates the size of of the base64-encoded sequence that results from an input sequence with the size that's specified by the first parameter. encoded_size() takes the same two additional optional parameters that x::base64::encoder takes. They factor into the resulting size. Pass, or don't pass, the same values for the optional parameters, in order to calculate the correct result.

size_t needed=base64_t::encoded_size(buffer.begin(), buffer.end(), 64);

encoded_size() also takes a pair of iterators, a beginning iterator and an ending iterator, instead of an explicit size of the input sequence. encoded_size() uses std::distance() to measure them. It uses the result as the size of the input sequence for the purpose of this calculation.

iter=base64_t::encode(buffer.begin(), buffer.end(), iter);

This is a convenience function that takes a pair of iterators, a beginning input iterator, an ending input iterator; and an output iterator. encode() constructs a x::base64::encoder using the output iterator passed as the third parameter; iterates over the input sequence, passing it to the instantiated x::base64::encoder; then invokes its eof() and returns the new output iterator.

This example base64-encodes the buffer container into the iter output iterator, then updating it with the new iterator value. encode() takes two more optional parameters that are the same as x::base64::encoder's optional parameters, which get forwarded to them.