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.
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: // 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);
Implementation of standard Base64 encoding.
See Base64Impl for a description of available methods.
ubyte[] data = [0x83, 0xd7, 0x30, 0x7a, 0x01, 0x3f];
writeln(Base64.encode(data)); // "g9cwegE/"
writeln(Base64.decode("g9cwegE/")); // data
Variation of Base64 encoding that is safe for use in URLs and filenames.
See Base64Impl for a description of available methods.
ubyte[] data = [0x83, 0xd7, 0x30, 0x7a, 0x01, 0x3f];
writeln(Base64URL.encode(data)); // "g9cwegE_"
writeln(Base64URL.decode("g9cwegE_")); // data
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.
ubyte[] data = [0x83, 0xd7, 0x30, 0x7b, 0xef];
writeln(Base64URLNoPadding.encode(data)); // "g9cwe-8"
writeln(Base64URLNoPadding.decode("g9cwe-8")); // data
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);
Padding parameter is set to NoPadding.import std.string : representation;
// pre-defined: alias Base64 = Base64Impl!('+', '/');
ubyte[] emptyArr;
writeln(Base64.encode(emptyArr)); // ""
writeln(Base64.encode("f".representation)); // "Zg=="
writeln(Base64.encode("foo".representation)); // "Zm9v"
alias Base64Re = Base64Impl!('!', '=', Base64.NoPadding);
writeln(Base64Re.encode("f".representation)); // "Zg"
writeln(Base64Re.encode("foo".representation)); // "Zm9v"
represents no-padding encoding
Calculates the length needed to store the encoded string corresponding to an input of the given length.
size_t sourceLength
| Length of the source array. |
ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]; // Allocate a buffer large enough to hold the encoded string. auto buf = new char[Base64.encodeLength(data.length)]; Base64.encode(data, buf); writeln(buf); // "Gis8TV1u"
Encode source into a char[] buffer using Base64 encoding.
R1 source
| The input range to encode. |
R2 buffer
| The char[] buffer to store the encoded result. |
buffer that contains the encoded string.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]); writeln(encoded); // "g9cwegE/"
Encodes source into an output range using Base64 encoding.
R1 source
| The input range to encode. |
R2 range
| The output range to store the encoded result. |
range's put method was invoked.// @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;
writeln(Base64.encode(data, output)); // 8
writeln(output.result); // "Gis8TV1u"
Encodes source to newly-allocated buffer.
This convenience method alleviates the need to manually manage output buffers.
Range source
| The input range to encode. |
char[] buffer containing the encoded string.ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]; writeln(Base64.encode(data)); // "Gis8TV1u"
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.
encoder function instead.true if there is no more encoded data left.Advance the range to the next chunk of encoded data.
Base64Exception If invoked when empty returns true.Save the current iteration state of the range.
This method is only available if the underlying range is a forward range.
this.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.
encoder function instead.true if there are no more encoded characters to be iterated.Advance to the next encoded character.
Base64Exception If invoked when empty returns true.Save the current iteration state of the range.
This method is only available if the underlying range is a forward range.
this.Construct an Encoder that iterates over the Base64 encoding of the given input range.
Range range
| An input range over the data to be encoded. |
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. File f = File("text.txt", "r");
scope(exit) f.close();
uint line = 0;
foreach (encoded; Base64.encoder(f.byLine()))
{
writeln(++line, ". ", encoded);
}
ubyte[] data = cast(ubyte[]) "0123456789";
// The ElementType of data is not aggregation type
foreach (encoded; Base64.encoder(data))
{
writeln(encoded);
}
Given a Base64 encoded string, calculates the length of the decoded string.
size_t sourceLength
| The length of the Base64 encoding. |
sourceLength.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); writeln(buffer); // [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]
Decodes source into the given buffer.
R1 source
| The input range to decode. |
R2 buffer
| The buffer to store decoded result. |
buffer containing the decoded result. Base64Exception if source contains characters outside the base alphabet of the current Base64 encoding scheme.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]); writeln(decoded); // [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]
Decodes source into a given output range.
R1 source
| The input range to decode. |
R2 range
| The output range to store the decoded result. |
range's put method was invoked. Base64Exception if source contains characters outside the base alphabet of the current Base64 encoding scheme.struct OutputRange
{
ubyte[] result;
void put(ubyte b) { result ~= b; }
}
OutputRange output;
// This overload of decode() returns the number of calls to put().
writeln(Base64.decode("Gis8TV1u", output)); // 6
writeln(output.result); // [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]
Decodes source into newly-allocated buffer.
This convenience method alleviates the need to manually manage decoding buffers.
Range source
| The input range to decode. |
ubyte[] buffer containing the decoded string.auto data = "Gis8TV1u"; writeln(Base64.decode(data)); // [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e]
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.
decoder function instead.true if there are no more elements to be iterated.Advance to the next element in the input to be decoded.
Base64Exception if invoked when empty returns true.Saves the current iteration state.
This method is only available if the underlying range is a forward range.
this.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.
decoder function instead.true if there are no more elements to be iterated.Advance to the next decoded byte.
Base64Exception if invoked when empty returns true.Saves the current iteration state.
This method is only available if the underlying range is a forward range.
this.Construct a Decoder that iterates over the decoding of the given Base64 encoded data.
Range range
| An input range over the data to be decoded. |
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. range of input data lines. foreach (decoded; Base64.decoder(stdin.byLine()))
{
writeln(decoded);
}
auto encoded = Base64.encoder(cast(ubyte[])"0123456789");
foreach (n; map!q{a - '0'}(Base64.decoder(encoded)))
{
writeln(n);
}
Exception thrown upon encountering Base64 encoding or decoding errors.
import std.exception : assertThrown;
assertThrown!Base64Exception(Base64.decode("ab|c"));
© 1999–2017 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_base64.html