kotlin-stdlib / kotlin.io.encoding / Base64 / PaddingOption

PaddingOption

Common

JVM

Native

1.0

enum class PaddingOption
(source)

An enumeration of the possible padding options for Base64 encoding and decoding.

Constants of this enum class can be passed to the withPadding function to create a new Base64 instance with the specified padding option. Each padding option affects the encode and decode operations of the Base64 instance in the following way:

| PaddingOption | On encode | On decode | |----------------------------------|--------------|--------------------------| | PaddingOption.PRESENT | Emit padding | Padding is required | | PaddingOption.ABSENT | Omit padding | Padding must not present | | PaddingOption.PRESENT_OPTIONAL | Emit padding | Padding is optional | | PaddingOption.ABSENT_OPTIONAL | Omit padding | Padding is optional |

These options provide flexibility in handling the padding characters ('=') and enable compatibility with various Base64 libraries and protocols.

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

fun main(args: Array<String>) {
//sampleStart
val format = HexFormat {
    upperCase = true
    bytes.byteSeparator = " "
}

val bytes = byteArrayOf(0xDE.toByte(), 0x2D, 0x02, 0xC0.toByte())

// The Base64.Default instance is configured with PaddingOption.PRESENT
println(Base64.Default.encode(bytes)) // 3i0CwA==
println(Base64.Default.decode("3i0CwA==").toHexString(format)) // DE 2D 02 C0
// PaddingOption.PRESENT requires the decode input to be properly padded
// Base64.Default.decode("3i0CwA") // will fail with IllegalArgumentException

// Create a new instance with PaddingOption.ABSENT that uses the Base64.Default alphabet
val base64AbsentPadding = Base64.Default.withPadding(Base64.PaddingOption.ABSENT)

println(base64AbsentPadding.encode(bytes)) // 3i0CwA
println(base64AbsentPadding.decode("3i0CwA").toHexString(format)) // DE 2D 02 C0
// PaddingOption.ABSENT requires the decode input not to be padded
// base64AbsentPadding.decode("3i0CwA==") // will fail with IllegalArgumentException

// Create a new instance with PaddingOption.PRESENT_OPTIONAL that uses the Base64.Default alphabet
val base64PresentOptionalPadding = Base64.Default.withPadding(Base64.PaddingOption.PRESENT_OPTIONAL)

println(base64PresentOptionalPadding.encode(bytes)) // 3i0CwA==
// PaddingOption.PRESENT_OPTIONAL allows both padded and unpadded decode inputs
println(base64PresentOptionalPadding.decode("3i0CwA==").toHexString(format)) // DE 2D 02 C0
println(base64PresentOptionalPadding.decode("3i0CwA").toHexString(format)) // DE 2D 02 C0
// However, partially padded input is prohibited
// base64PresentOptionalPadding.decode("3i0CwA=") // will fail with IllegalArgumentException

// Create a new instance with PaddingOption.ABSENT_OPTIONAL that uses the Base64.Default alphabet
val base64AbsentOptionalPadding = Base64.Default.withPadding(Base64.PaddingOption.ABSENT_OPTIONAL)

println(base64AbsentOptionalPadding.encode(bytes)) // 3i0CwA
// PaddingOption.ABSENT_OPTIONAL allows both padded and unpadded decode inputs
println(base64AbsentOptionalPadding.decode("3i0CwA").toHexString(format)) // DE 2D 02 C0
println(base64AbsentOptionalPadding.decode("3i0CwA==").toHexString(format)) // DE 2D 02 C0
// However, partially padded input is prohibited
// base64AbsentOptionalPadding.decode("3i0CwA=") // will fail with IllegalArgumentException
//sampleEnd
}

Enum Values

Common

JVM

Native

1.0

PRESENT

Pad on encode, require padding on decode.

Common

JVM

Native

1.0

ABSENT

Do not pad on encode, prohibit padding on decode.

Common

JVM

Native

1.0

PRESENT_OPTIONAL

Pad on encode, allow optional padding on decode.

Common

JVM

Native

1.0

ABSENT_OPTIONAL

Do not pad on encode, allow optional padding on decode.