Base64

Начиная с Kotlin: 2.2

open class Base64

Предоставляет функции кодирования и декодирования Base64. Кодирование Base64, определённое в RFC 4648 и нескольких других RFC, преобразует произвольные двоичные данные в последовательность печатных символов.

Например, последовательность байтов 0xC0 0xFF 0xEE будет преобразована в строку "wP/u" с использованием кодирования Base64, определённого в RFC 4648. Декодирование этой строки вернёт исходную последовательность байтов.

Base64 — это не схема шифрования, и её не следует использовать, когда данные необходимо защитить или скрыть.

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

Почти все схемы кодирования Base64 используют первые 62 символа алфавита: 'A'..'Z', за которыми следуют 'a'..'z', однако последние два символа могут различаться. В RFC 4648 section 4 определён алфавит, в котором в качестве последних двух символов используются '+' и '/', тогда как в алфавите, безопасном для URL и определённом в RFC 4648 section 5, вместо них используются '-' и '_'.

При декодировании схема Base64 обычно принимает только символы из своего алфавита; наличие любых других символов считается ошибкой (исключение из этого правила см. в Base64.Mime). Это также означает, что схема Base64 не сможет декодировать данные, закодированные другой схемой Base64, если их алфавиты различаются.

Помимо 64 символов алфавита, закодированные в Base64 данные могут содержать в конце один или два символа заполнения '='. Base64 разбивает данные, которые необходимо закодировать, на блоки по три байта, а затем преобразует их в последовательность из четырёх символов (то есть каждый символ кодирует шесть бит данных). Если количество байтов во входных данных не кратно трём (например, входные данные состоят всего из пяти байтов), сначала данные дополняются нулевыми битами и только затем преобразуются в символы алфавита Base64. Если выполняется дополнение, результирующая строка дополняется символами '='. Заполнение может состоять из нуля, двух или четырёх бит, поэтому закодированные данные будут содержать соответственно ноль, один или два символа заполнения ('='). Наличие символов заполнения в результирующей строке зависит от параметра PaddingOption, заданного для экземпляра Base64.

Этот класс не предназначен для наследования или создания экземпляров с помощью вызова конструктора. Однако доступны предопределённые экземпляры этого класса. Объект-компаньон Base64.Default является экземпляром Base64 по умолчанию. Также доступны экземпляры Base64.UrlSafe и Base64.Mime. Для всех предопределённых экземпляров задан параметр заполнения PaddingOption.PRESENT. Новые экземпляры с другими параметрами заполнения можно создать с помощью функции withPadding.

Примеры

import kotlin.io.encoding.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val encoded = Base64.Default.encode("Hello, World!".encodeToByteArray())
println(encoded) // SGVsbG8sIFdvcmxkIQ==

val decoded = Base64.Default.decode(encoded)
println(decoded.decodeToString()) // Hello, World! 
   //sampleEnd
}

import kotlin.io.encoding.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Default encoding uses '/' and '+' as the last two characters of the Base64 alphabet
println(Base64.Default.encode(byteArrayOf(-1, 0, -2, 0))) // /wD+AA==
// Mime's alphabet is the same as Default's
println(Base64.Mime.encode(byteArrayOf(-1, 0, -2, 0))) // /wD+AA==
// UrlSafe encoding uses '_' and '-' as the last two Base64 alphabet characters
println(Base64.UrlSafe.encode(byteArrayOf(-1, 0, -2, 0))) // _wD-AA==

// UrlSafe uses `-` and `_`, so the following string could not be decoded
// Base64.UrlSafe.decode("/wD+AA==") // will fail with IllegalArgumentException 
   //sampleEnd
}

import kotlin.io.encoding.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // "base".length == 4, which is not multiple of 3;
// base64-encoded data padded with 4 bits
println(Base64.Default.encode("base".encodeToByteArray())) // YmFzZQ==
// "base6".length == 5, which is not multiple of 3;
// base64-encoded data padded with 2 bits
println(Base64.Default.encode("base6".encodeToByteArray())) // YmFzZTY=
// "base64".length == 6, which is the multiple of 3, so no padding is required
println(Base64.Default.encode("base64".encodeToByteArray())) // YmFzZTY0 
   //sampleEnd
}

Наследники