std.base64

Поддержка кодирования и декодирования Base64.

Этот модуль предоставляет две стандартные реализации кодирования Base64, Base64 с стандартным алфавитом кодирования, и варианта Base64URL, который использует изменённый алфавит кодирования, предназначенный для безопасного использования в URL и именах файлов.

Оба варианта реализованы как экземпляры шаблона Base64Impl. Большинству пользователей не нужно использовать этот шаблон напрямую; однако, его можно использовать для создания настраиваемых схем кодирования 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);

Ссылки

RFC 4648 - Кодирования данных Base16, Base32 и Base64

Лицензия:

Лицензия Boost 1.0.

Авторы:

Masahiro Nakagawa, Daniel Murphy (Кодировщик и декодировщик для единственного значения)

Исходный код

std/base64.d

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

Реализация стандартного кодирования Base64.

См. Base64Impl для описания доступных методов.

Примеры:

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

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

Вариант кодирования Base64, безопасный для использования в URL и именах файлов.

См. Base64Impl для описания доступных методов.

Примеры:

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

alias Base64URLNoPadding = Base64Impl!('-', '_', '\x00');

Вариант кодирования Base64 без заполнения, безопасный для использования в URL и именах файлов, как используется в RFC 4648 и 7515 (JWS/JWT/JWE).

См. Base64Impl для описания доступных методов.

Примеры:

ubyte[] data = [0x83, 0xd7, 0x30, 0x7b, 0xef];
writeln(Base64URLNoPadding.encode(data)); // "g9cwe-8"
writeln(Base64URLNoPadding.decode("g9cwe-8")); // data

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

Шаблон для реализации кодирования и декодирования Base64.

Для большинства случаев прямое использование этого шаблона не требуется; вместо этого этот модуль предоставляет стандартные реализации: Base64, реализующую базовое кодирование Base64, и Base64URL и Base64URLNoPadding, реализующие варианты Base64 для использования в URL и именах файлов, с и без заполнения соответственно.

Настраиваемые схемы кодирования Base64 можно реализовать, инициализировав этот шаблон соответствующими аргументами. Например:

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

ПРИМЕЧАНИЕ

Строки, закодированные с помощью Base64, не будут содержать символов заполнения, если параметр Padding установлен на 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"

перечисление auto NoPadding;

представляет кодирование без заполнения

чистое без исключений @safe size_t encodeLength(in size_t sourceLength);

Вычисляет длину, необходимую для хранения закодированной строки, соответствующей вводу заданной длины.

Параметры:

size_t sourceLength

Длина исходного массива.

Возвращает:

Длина Base64 кодирования массива заданной длины.

Примеры:

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"

чистое @trusted char[] encode(R1, R2)(in R1 source, R2 buffer)
Ограничения: если (isArray!R1 && is(ElementType!R1 : ubyte) && is(R2 == char[]));

char[] encode(R1, R2)(R1 source, R2 buffer)
Ограничения: если (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : ubyte) && hasLength!R1 && is(R2 == char[]));

Кодирует source в char[] буфер с использованием Base64 кодирования.

Параметры:

R1 source	Входной диапазон для кодирования.
R2 buffer	char[] буфер для хранения закодированного результата.

Возвращает:

Срез buffer, содержащий закодированную строку.

Примеры:

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/"

size_t encode(E, R)(scope const(E)[] source, auto ref R range)
Ограничения: если (is(E : ubyte) && isOutputRange!(R, char) && !is(R == char[]));

size_t encode(R1, R2)(R1 source, auto ref R2 range)
Ограничения: если (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : ubyte) && hasLength!R1 && !is(R2 == char[]) && isOutputRange!(R2, char));

Кодирует source в выходной диапазон с использованием Base64 кодирования.

Параметры:

const(E)[] source	Входной диапазон для кодирования.
R range	Выходной диапазон для хранения закодированного результата.

Возвращает:

Количество вызовов метода put выходного диапазона.

Примеры:

import std.array : appender;

auto output = appender!string();
ubyte[] data = [0x1a, 0x2b, 0x3c, 0x4d, 0x5d, 0x6e];

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

чистое @safe char[] encode(Range)(Range source)
Ограничения: если (isArray!Range && is(ElementType!Range : ubyte));

char[] encode(Range)(Range source)
Ограничения: если (!isArray!Range && isInputRange!Range && is(ElementType!Range : ubyte) && hasLength!Range);

Кодирует source в новый выделенный буфер.

Этот вспомогательный метод избавляет от необходимости вручную управлять выходными буферами.

Параметры:

Range source

Входной диапазон для кодирования.

Возвращает:

Новый выделенный char[] буфер, содержащий закодированную строку.

Примеры:

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

структура Encoder(Range) если (isInputRange!Range && (is(ElementType!Range : const(ubyte)[]) || is(ElementType!Range : const(char)[])));

Входной диапазон, который итерируется по соответствующим Base64 кодированиям элементов данных из диапазона.

Этот диапазон будет прямолинейным, если исходный источник данных по крайней мере прямолинейный.

Примечание

Эта структура не предназначена для непосредственного создания в коде пользователя; используйте функцию encoder вместо этого.

@property @trusted bool empty();

Возвращает:

true, если больше нет закодированных данных.

без исключений @property @safe char[] front();

Возвращает:

Текущий фрагмент закодированных данных.

void popFront();

Перемещает диапазон к следующему фрагменту закодированных данных.

Выбрасывает:

Base64Exception Если вызван, когда `empty` возвращает true.

@property typeof(this) save();

Сохранить текущее состояние итерации диапазона.

Этот метод доступен только если базовый диапазон является прямолинейным.

Возвращает:

Копию this.

структура Encoder(Range) если (isInputRange!Range && is(ElementType!Range : ubyte));

Входной диапазон, который итерируется по закодированным байтам заданных данных.

Это будет прямолинейный диапазон, если исходный источник данных по крайней мере прямолинейный.

Примечание

Эта структура не предназначена для непосредственного создания в коде пользователя; используйте функцию encoder вместо этого.

const без исключений @property @safe bool empty();

Возвращает:

true, если больше нет закодированных символов для итерации.

без исключений @property @safe ubyte front();

Возвращает:

Текущий закодированный символ.

void popFront();

Переход к следующему закодированному символу.

Выбрасывает:

Base64Exception Если вызван, когда ` empty` возвращает true.

@property typeof(this) save();

Сохранить текущее состояние итерации диапазона.

Этот метод доступен только если базовый диапазон является прямолинейным.

Возвращает:

Копию this.

Encoder!Range encoder(Range)(Range range)
Ограничения: если (isInputRange!Range);

Создаёт Encoder, который итерируется по Base64 кодированию данного входного диапазона.

Параметры:

Range range

Входной диапазон данных, подлежащих кодированию.

Возвращает:

Если range — это диапазон байтов, Encoder, который итерируется по байтам соответствующего Base64 кодирования. Если range — это диапазон диапазонов байтов, Encoder, который итерируется по Base64 закодированным строкам каждого элемента диапазона. В обоих случаях возвращённый Encoder будет прямолинейным, если заданный 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);
}

чистое без исключений @safe size_t decodeLength(in size_t sourceLength);

Для Base64 закодированной строки вычисляет длину декодированной строки.

Параметры:

size_t sourceLength

Длина Base64 кодирования.

Возвращает:

Длина декодированной строки, соответствующей Base64 кодированию длины 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]

чистое @trusted ubyte[] decode(R1, R2)(in R1 source, R2 buffer)
Ограничения: если (isArray!R1 && is(ElementType!R1 : dchar) && is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

ubyte[] decode(R1, R2)(R1 source, R2 buffer)
Ограничения: если (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : dchar) && hasLength!R1 && is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

Декодирует source в данный буфер.

Параметры:

R1 source	Входной диапазон для декодирования.
R2 buffer	Буфер для хранения декодированного результата.

Возвращает:

Срез buffer, содержащий декодированный результат.

Выбрасывает:

Base64Exception если source содержит символы вне базового алфавита текущей схемы Base64 кодирования.

Примеры:

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]

size_t decode(R1, R2)(in R1 source, auto ref R2 range)
Ограничения: если (isArray!R1 && is(ElementType!R1 : dchar) && !is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

size_t decode(R1, R2)(R1 source, auto ref R2 range)
Ограничения: если (!isArray!R1 && isInputRange!R1 && is(ElementType!R1 : dchar) && hasLength!R1 && !is(R2 == ubyte[]) && isOutputRange!(R2, ubyte));

Декодирует source в заданный диапазон вывода.

Параметры:

R1 source	Диапазон ввода для декодирования.
R2 range	Диапазон вывода для хранения результата декодирования.

Возвращает:

Количество раз, когда метод put диапазона вывода был вызван.

Исключения:

Base64Exception если source содержит символы, не входящие в базовый алфавит текущей схемы кодирования Base64.

Примеры:

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]

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

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

Декодирует source в буфер с новым выделением памяти.

Этот удобный метод избавляет от необходимости вручную управлять буферами декодирования.

Параметры:

Range source

Диапазон ввода для декодирования.

Возвращает:

Буфер с новым выделением памяти ubyte[], содержащий декодированную строку.

Примеры:

auto data = "Gis8TV1u";
writeln(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)[])));

Диапазон ввода, который итерируется по декодированным данным диапазона Base64 кодировок.

Этот диапазон будет диапазоном вперёд, если исходный источник данных — по крайней мере, диапазон вперёд.

Примечание

Данный структуру не предназначено создавать напрямую в коде пользователя; используйте функцию decoder вместо этого.

@property @trusted bool empty();

Возвращает:

true, если больше нет элементов для итерации.

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

Возвращает:

Декодирование текущего элемента ввода.

void popFront();

Переход к следующему элементу ввода для декодирования.

Исключения:

Base64Exception если вызван, когда ` empty` возвращает true.

@property typeof(this) save();

Сохранение текущего состояния итерации.

Этот метод доступен только если базовый диапазон — диапазон вперёд.

Возвращает:

Копию this.

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

Диапазон ввода, который итерируется по байтам данных, декодированных из Base64 закодированной строки.

Этот диапазон будет диапазоном вперёд, если исходный источник данных — по крайней мере, диапазон вперёд.

Примечание

Данный структуру не предназначено создавать напрямую в коде пользователя; используйте функцию decoder вместо этого.

const nothrow @property @safe bool empty();

Возвращает:

true, если больше нет элементов для итерации.

nothrow @property @safe ubyte front();

Возвращает:

Текущий декодированный байт.

void popFront();

Переход к следующему декодированному байту.

Исключения:

Base64Exception если вызван, когда ` empty` возвращает true.

@property typeof(this) save();

Сохранение текущего состояния итерации.

Этот метод доступен только если базовый диапазон — диапазон вперёд.

Возвращает:

Копию this.

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

Конструирует Decoder, который итерируется по декодированию заданных данных Base64.

Параметры:

Range range

Диапазон ввода над данными, подлежащими декодированию.

Возвращает:

Если range — диапазон символов, a Decoder, который итерируется по байтам соответствующего Base64 декодирования. Если range — диапазон диапазонов символов, a Decoder, который итерируется по декодированным строкам, соответствующим каждому элементу диапазона. В этом случае длина каждого поддиапазона должна быть кратна 4; возвращаемый декодер не отслеживает состояние декодирования Base64 между границами поддиапазонов. В обоих случаях возвращаемый Decoder будет диапазоном вперёд, если заданный range — по крайней мере, диапазон вперёд, в противном случае он будет только диапазоном ввода. Если входные данные содержат символы, отсутствующие в базовом алфавите текущей схемы кодирования Base64, возвращаемый диапазон может выбросить Base64Exception.

Пример

Этот пример демонстрирует декодирование по диапазону строк входных данных.

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

class Base64Exception: object.Exception;

Исключение, выбрасываемое при обнаружении ошибок кодирования или декодирования Base64.

Примеры:

import std.exception : assertThrown;
assertThrown!Base64Exception(Base64.decode("ab|c"));