Base64

Provides Base64 encoding and decoding functionality. Base64 encoding, as defined by the RFC 4648 and a few other RFCs, transforms arbitrary binary data into a sequence of printable characters.

For example, a sequence of bytes 0xC0 0xFF 0xEE will be transformed to a string "wP/u" using a Base64 encoding defined by the RFC 4648. Decoding that string will result in the original byte sequence.

Base64 is not an encryption scheme and should not be used when data needs to be secured or obfuscated.

Characters used by a particular Base64 scheme form an alphabet of 64 regular characters and an extra padding character.

Almost all Base64 encoding schemes share the same first 62 characters of an alphabet, which are 'A'..'Z' followed by 'a'..'z', but the last two characters may vary. RFC 4648 section 4 defines an alphabet that uses '+' and '/' as the last two characters, while the URL-safe alphabet defined in RFC 4648 section 5 uses '-' and '_' instead.

When decoding, a Base64 scheme usually accepts only characters from its alphabet, presence of any other characters is treated as an error (see Base64.Mime for an exception to this rule). That also implies that a Base64 scheme could not decode data encoded by another Base64 scheme if their alphabets differ.

In addition to 64 characters from the alphabet, Base64-encoded data may also contain one or two padding characters '=' at its end. Base64 splits data that needs to be encoded into chunks three bytes long, which are then transformed into a sequence of four characters (meaning that every character encodes six bits of data). If the number of bytes constituting input data is not a multiple of three (for instance, input consists of only five bytes), the data will be padded by zero bits first and only then transformed into Base64-alphabet characters. If padding takes place, the resulting string is augmented by '='. The padding could consist of zero, two or four bits, thus encoded data will contain zero, one or two padding characters ('='), respectively. The inclusion of padding characters in the resulting string depends on the PaddingOption set for the Base64 instance.

This class is not supposed to be inherited or instantiated by calling its constructor. However, predefined instances of this class are available for use. The companion object Base64.Default is the default instance of Base64. There are also Base64.UrlSafe and Base64.Mime instances. The padding option for all predefined instances is set to PaddingOption.PRESENT. New instances with different padding options can be created using the withPadding function.

Samples

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
}

Inheritors