D Programming Language
Report a bug If you spot a problem with this page, click here to create a Bugzilla issue. Improve this page Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

# 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

License:
Boost License 1.0.
Authors:
Masahiro Nakagawa, Daniel Murphy (Single value Encoder and Decoder)

Source: std/base64.d

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.

  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:

        struct OutputRange
        {
            char[] result;
            void put(const(char) ch) { 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.

Masahiro Nakagawa 2010-. | Page generated by Ddoc on Wed Nov 11 10:38:06 2015