std.base64

ubyte[] data = [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e];

const(char)[] encoded = Base64.encode(data);
assert(encoded == "FPucA9l+");

ubyte[] decoded = Base64.decode("FPucA9l+");
assert(decoded == [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e]);

// Create MIME Base64 with CRLF, per line 76.
File f = File("./text.txt", "r");
scope(exit) f.close();

Appender!string mime64 = appender!string;

foreach (encoded; Base64.encoder(f.byChunk(57)))
{
    mime64.put(encoded);
    mime64.put("\r\n");
}

writeln(mime64.data);

alias Base64 = Base64Impl!('+', '/', '=');

Implementation of standard Base64 encoding.

See Base64Impl for a description of available methods.

Examples:

ubyte[] data = [0x83, 0xd7, 0x30, 0x7a, 0x01, 0x3f];
assert(Base64.encode(data) == "g9cwegE/");
assert(Base64.decode("g9cwegE/") == data);

alias Base64URL = Base64Impl!('-', '_', '=');

Variation of Base64 encoding that is safe for use in URLs and filenames.

See Base64Impl for a description of available methods.

Examples:

ubyte[] data = [0x83, 0xd7, 0x30, 0x7a, 0x01, 0x3f];
assert(Base64URL.encode(data) == "g9cwegE_");
assert(Base64URL.decode("g9cwegE_") == data);

template Base64Impl(char Map62th, char Map63th, char Padding = '=')

Template for implementing Base64 encoding and decoding.

For most purposes, direct usage of this template is not necessary; instead, this module provides two default implementations: Base64 and Base64URL, that implement basic Base64 encoding and a variant intended for use in URLs and filenames, respectively.

Customized Base64 encoding schemes can be implemented by instantiating this template with the appropriate arguments. For example:

// Non-standard Base64 format for embedding in regular expressions.
alias Base64Re = Base64Impl!('!', '=', Base64.NoPadding);

NOTE: Encoded strings will not have any padding if the Padding parameter is set to NoPadding.

enum auto NoPadding;

represents no-padding encoding

pure nothrow @safe size_t encodeLength(in size_t sourceLength);

Calculates the length needed to store the encoded string corresponding to an input of the given length.

Parameters:

size_t sourceLength

Length of the source array.

Returns:

The length of a Base64 encoding of an array of the given length.

Examples:

ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e];

// Allocate a buffer large enough to hold the encoded string.
auto buf = new char[encodeLength(data.length)];

Base64.encode(data, buf);
assert(buf == "Gis8TV1u");

pure @trusted char[] encode(R1, R2)(in R1 source, R2 buffer)
if (isArray!R1 && is(ElementType!R1 : ubyte) && is(R2 == char[]));

char[] encode(R1, R2)(R1 source, R2 buffer)
if (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : ubyte) && hasLength!R1 && is(R2 == char[]));

Encode source into a char[] buffer using Base64 encoding.

Parameters:

R1 source	The input range to encode.
R2 buffer	The char[] buffer to store the encoded result.

Returns:

The slice of buffer that contains the encoded string.

Examples:

ubyte[] data = [0x83, 0xd7, 0x30, 0x7a, 0x01, 0x3f];
char[32] buffer;    // much bigger than necessary

// Just to be sure...
auto encodedLength = Base64.encodeLength(data.length);
assert(buffer.length >= encodedLength);

// encode() returns a slice to the provided buffer.
auto encoded = Base64.encode(data, buffer[]);
assert(encoded is buffer[0 .. encodedLength]);
assert(encoded == "g9cwegE/");

size_t encode(R1, R2)(in R1 source, auto ref R2 range)
if (isArray!R1 && is(ElementType!R1 : ubyte) && !is(R2 == char[]) && isOutputRange!(R2, char));

size_t encode(R1, R2)(R1 source, auto ref R2 range)
if (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : ubyte) && hasLength!R1 && !is(R2 == char[]) && isOutputRange!(R2, char));

Encodes source into an output range using Base64 encoding.

Parameters:

R1 source	The input range to encode.
R2 range	The output range to store the encoded result.

Returns:

The number of times the output range's put method was invoked.

Examples:

// @system because encode for OutputRange is @system
struct OutputRange
{
    char[] result;
    void put(const(char) ch) @safe { result ~= ch; }
}

ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e];

// This overload of encode() returns the number of calls to the output
// range's put method.
OutputRange output;
assert(Base64.encode(data, output) == 8);
assert(output.result == "Gis8TV1u");

pure @safe char[] encode(Range)(Range source)
if (isArray!Range && is(ElementType!Range : ubyte));

char[] encode(Range)(Range source)
if (!isArray!Range && isInputRange!Range && is(ElementType!Range : ubyte) && hasLength!Range);

Encodes source to newly-allocated buffer.

This convenience method alleviates the need to manually manage output buffers.

Parameters:

Range source

The input range to encode.

Returns:

A newly-allocated char[] buffer containing the encoded string.

Examples:

ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e];
assert(Base64.encode(data) == "Gis8TV1u");

struct Encoder(Range) if (isInputRange!Range && (is(ElementType!Range : const(ubyte)[]) || is(ElementType!Range : const(char)[])));

An input range that iterates over the respective Base64 encodings of a range of data items.

This range will be a forward range if the underlying data source is at least a forward range.

Note: This struct is not intended to be created in user code directly; use the encoder function instead.

@property @trusted bool empty();

Returns:

true if there is no more encoded data left.

nothrow @property @safe char[] front();

Returns:

The current chunk of encoded data.

void popFront();

Advance the range to the next chunk of encoded data.

Throws:

Base64Exception If invoked when empty returns true.

@property typeof(this) save();

Save the current iteration state of the range.

This method is only available if the underlying range is a forward range.

Returns:

A copy of this.

struct Encoder(Range) if (isInputRange!Range && is(ElementType!Range : ubyte));

An input range that iterates over the encoded bytes of the given source data.

It will be a forward range if the underlying data source is at least a forward range.

Note: This struct is not intended to be created in user code directly; use the encoder function instead.

const nothrow @property @safe bool empty();

Returns:

true if there are no more encoded characters to be iterated.

nothrow @property @safe ubyte front();

Returns:

The current encoded character.

void popFront();

Advance to the next encoded character.

Throws:

Base64Exception If invoked when empty returns true.

@property typeof(this) save();

Save the current iteration state of the range.

This method is only available if the underlying range is a forward range.

Returns:

A copy of this.

Encoder!Range encoder(Range)(Range range)
if (isInputRange!Range);

Construct an Encoder that iterates over the Base64 encoding of the given input range.

Parameters:

Range range

An input range over the data to be encoded.

Returns:

If range is a range of bytes, an Encoder that iterates over the bytes of the corresponding Base64 encoding.

If range is a range of ranges of bytes, an Encoder that iterates over the Base64 encoded strings of each element of the range.

In both cases, the returned Encoder will be a forward range if the given range is at least a forward range, otherwise it will be only an input range.

Example: This example encodes the input one line at a time.

File f = File("text.txt", "r");
scope(exit) f.close();

uint line = 0;
foreach (encoded; Base64.encoder(f.byLine()))
{
    writeln(++line, ". ", encoded);
}

Example: This example encodes the input data one byte at a time.

ubyte[] data = cast(ubyte[]) "0123456789";

// The ElementType of data is not aggregation type
foreach (encoded; Base64.encoder(data))
{
    writeln(encoded);
}

pure nothrow @safe size_t decodeLength(in size_t sourceLength);

Given a Base64 encoded string, calculates the length of the decoded string.

Parameters:

size_t sourceLength

The length of the Base64 encoding.

Returns:

The length of the decoded string corresponding to a Base64 encoding of length sourceLength.

Examples:

auto encoded = "Gis8TV1u";

// Allocate a sufficiently large buffer to hold to decoded result.
auto buffer = new ubyte[Base64.decodeLength(encoded.length)];

Base64.decode(encoded, buffer);
assert(buffer == [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]);

pure @trusted ubyte[] decode(R1, R2)(in R1 source, R2 buffer)
if (isArray!R1 && is(ElementType!R1 : dchar) && is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

ubyte[] decode(R1, R2)(R1 source, R2 buffer)
if (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : dchar) && hasLength!R1 && is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

Decodes source into the given buffer.

Parameters:

R1 source	The input range to decode.
R2 buffer	The buffer to store decoded result.

Returns:

The slice of buffer containing the decoded result.

Throws:

Base64Exception if source contains characters outside the base alphabet of the current Base64 encoding scheme.

Examples:

auto encoded = "Gis8TV1u";
ubyte[32] buffer;   // much bigger than necessary

// Just to be sure...
auto decodedLength = Base64.decodeLength(encoded.length);
assert(buffer.length >= decodedLength);

// decode() returns a slice of the given buffer.
auto decoded = Base64.decode(encoded, buffer[]);
assert(decoded is buffer[0 .. decodedLength]);
assert(decoded == [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]);

size_t decode(R1, R2)(in R1 source, auto ref R2 range)
if (isArray!R1 && is(ElementType!R1 : dchar) && !is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

size_t decode(R1, R2)(R1 source, auto ref R2 range)
if (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : dchar) && hasLength!R1 && !is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

Decodes source into a given output range.

Parameters:

R1 source	The input range to decode.
R2 range	The output range to store the decoded result.

Returns:

The number of times the output range's put method was invoked.

Throws:

Base64Exception if source contains characters outside the base alphabet of the current Base64 encoding scheme.

Examples:

struct OutputRange
{
    ubyte[] result;
    void put(ubyte b) { result ~= b; }
}
OutputRange output;

// This overload of decode() returns the number of calls to put().
assert(Base64.decode("Gis8TV1u", output) == 6);
assert(output.result == [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]);

pure @safe ubyte[] decode(Range)(Range source)
if (isArray!Range && is(ElementType!Range : dchar));

ubyte[] decode(Range)(Range source)
if (!isArray!Range && isInputRange!Range && is(ElementType!Range : dchar) && hasLength!Range);

Decodes source into newly-allocated buffer.

This convenience method alleviates the need to manually manage decoding buffers.

Parameters:

Range source

The input range to decode.

Returns:

A newly-allocated ubyte[] buffer containing the decoded string.

Examples:

auto data = "Gis8TV1u";
assert(Base64.decode(data) == [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]);

struct Decoder(Range) if (isInputRange!Range && (is(ElementType!Range : const(char)[]) || is(ElementType!Range : const(ubyte)[])));

An input range that iterates over the decoded data of a range of Base64 encodings.

This range will be a forward range if the underlying data source is at least a forward range.

Note: This struct is not intended to be created in user code directly; use the decoder function instead.

@property @trusted bool empty();

Returns:

true if there are no more elements to be iterated.

nothrow @property @safe ubyte[] front();

Returns:

The decoding of the current element in the input.

void popFront();

Advance to the next element in the input to be decoded.

Throws:

Base64Exception if invoked when empty returns true.

@property typeof(this) save();

Saves the current iteration state.

This method is only available if the underlying range is a forward range.

Returns:

A copy of this.

struct Decoder(Range) if (isInputRange!Range && is(ElementType!Range : char));

An input range that iterates over the bytes of data decoded from a Base64 encoded string.

This range will be a forward range if the underlying data source is at least a forward range.

Note: This struct is not intended to be created in user code directly; use the decoder function instead.

const nothrow @property @safe bool empty();

Returns:

true if there are no more elements to be iterated.

nothrow @property @safe ubyte front();

Returns:

The current decoded byte.

void popFront();

Advance to the next decoded byte.

Throws:

Base64Exception if invoked when empty returns true.

@property typeof(this) save();

Saves the current iteration state.

This method is only available if the underlying range is a forward range.

Returns:

A copy of this.

Decoder!Range decoder(Range)(Range range)
if (isInputRange!Range);

Construct a Decoder that iterates over the decoding of the given Base64 encoded data.

Parameters:

Range range

An input range over the data to be decoded.

Returns:

If range is a range of characters, a Decoder that iterates over the bytes of the corresponding Base64 decoding.

If range is a range of ranges of characters, a Decoder that iterates over the decoded strings corresponding to each element of the range. In this case, the length of each subrange must be a multiple of 4; the returned decoder does not keep track of Base64 decoding state across subrange boundaries.

In both cases, the returned Decoder will be a forward range if the given range is at least a forward range, otherwise it will be only an input range.

If the input data contains characters not found in the base alphabet of the current Base64 encoding scheme, the returned range may throw a Base64Exception.

Example: This example shows decoding over a range of input data lines.

foreach (decoded; Base64.decoder(stdin.byLine()))
{
    writeln(decoded);
}

Example: This example shows decoding one byte at a time.

auto encoded = Base64.encoder(cast(ubyte[])"0123456789");
foreach (n; map!q{a - '0'}(Base64.decoder(encoded)))
{
    writeln(n);
}

class Base64Exception: object.Exception;

Exception thrown upon encountering Base64 encoding or decoding errors.