std.base64

Support for Base64 encoding and decoding.

This module provides two default implementations of Base64 encoding,

Base64 with a standard encoding alphabet, and a variant Base64URL that has a modified encoding alphabet designed to be

safe for embedding in URLs and filenames.

Both variants are implemented as instantiations of the template

Base64Impl. Most users will not need to use this template

directly; however, it can be used to create customized Base64 encodings, such as one that omits padding characters, or one that is safe to embed inside a regular expression.

Example: ----- 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]); -----

The range API is supported for both encoding and decoding:

Example: ----- // 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); -----

References:

RFC 4648 - The Base16, Base32, and Base64

Data Encodings

Copyright

Masahiro Nakagawa 2010-.

License

Boost License 1.0.

Authors

Masahiro Nakagawa, Daniel Murphy (Single value Encoder and Decoder)

Source: std/base64.d

tmpl Base64Impl

alias Base64 Base64URL Base64URLNoPadding

class Base64Exception

Types 4

aliasBase64 = Base64Impl!('+', '/')

Implementation of standard _Base64 encoding.

See Base64Impl for a description of available methods.

aliasBase64URL = Base64Impl!('-', '_')

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

See Base64Impl for a description of available methods.

aliasBase64URLNoPadding = Base64Impl!('-', '_', Base64.NoPadding)

Unpadded variation of Base64 encoding that is safe for use in URLs and filenames, as used in RFCs 4648 and 7515 (JWS/JWT/JWE).

See Base64Impl for a description of available methods.

classBase64Exception : Exception

Exception thrown upon encountering Base64 encoding or decoding errors.

Constructors

this(string s, string fn = __FILE__, size_t ln = __LINE__)

Templates 1

tmplBase64Impl(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 default implementations: Base64, implementing basic Base64 encoding, and Base64URL and Base64URLNoPadding, that implement the Base64 variant for use in URLs and filenames, with and without padding, 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.

Functions

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

sourceLength Length of the source array.

Returns

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

char[] encode(R1, R2)(const scope R1 source, return scope R2 buffer) if (isArray!R1 && is(ElementType!R1 : ubyte) && is(R2 == char[]))

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

Parameters

`source`	The input range to _encode.
`buffer`	The `char[]` buffer to store the encoded result.

Returns

The slice of buffer that contains the encoded string.

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

ditto

size_t encode(E, R)(scope const(E)[] source, auto ref R range) if (is(E : ubyte) && isOutputRange!(R, char) && !is(R == char[]))

Encodes source into an

output range using

Base64 encoding.

Parameters

`source`	The input range to _encode.
`range`	The output range to store the encoded result.

Returns

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

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))

ditto

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

Encodes source to newly-allocated buffer.

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

Parameters

source The input range to _encode.

Returns

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

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

ditto

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 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); } -----

size_t decodeLength(in size_t sourceLength)

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

Parameters

sourceLength The length of the Base64 encoding.

Returns

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

length sourceLength.

size_t realDecodeLength(R)(R source)

ubyte[] decode(R1, R2)(in R1 source, return scope R2 buffer) if (isArray!R1 && is(ElementType!R1 : dchar) && is(R2 == ubyte[]) && isOutputRange!(R2, ubyte))

Decodes source into the given buffer.

Parameters

`source`	The input range to _decode.
`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.

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))

ditto

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))

Decodes source into a given

output range.

Parameters

`source`	The input range to _decode.
`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.

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))

ditto

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

Decodes source into newly-allocated buffer.

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

Parameters

source The input range to _decode.

Returns

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

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

ditto

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 An input range over the data to be decoded, or a char array. Will not accept wchar[] nor dchar[].

Returns

If range is a range or array of char, 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 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); } -----

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); } -----

Decoder!(const(ubyte)[]) decoder()(const(char)[] range)

ditto

int decodeChar()(char chr)

int decodeChar()(dchar chr)

Types

struct Encoder

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.

struct Encoder

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.

struct Decoder

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.

struct Decoder

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.