# base64

Dark Mode

- Manual
- Standard library
- Index

Search:
Group by:

This module implements a base64 encoder and decoder.

Unstable API.

Base64 is an encoding and decoding technique used to convert binary data to an ASCII string format. Each Base64 digit represents exactly 6 bits of data. Three 8-bit bytes (i.e., a total of 24 bits) can therefore be represented by four 6-bit Base64 digits.

# Basic usage

## Encoding data

    import base64
    let encoded = encode("Hello World")
    assert encoded == "SGVsbG8gV29ybGQ="

Apart from strings you can also encode lists of integers or characters:

    import base64
    let encodedInts = encode([1,2,3])
    assert encodedInts == "AQID"
    let encodedChars = encode(['h','e','y'])
    assert encodedChars == "aGV5"

## Decoding data

    import base64
    let decoded = decode("SGVsbG8gV29ybGQ=")
    assert decoded == "Hello World"

## URL Safe Base64

    import base64
    doAssert encode("c\xf7>", safe = true) == "Y_c-"
    doAssert encode("c\xf7>", safe = false) == "Y/c+"

# See also

- hashes module for efficient computations of hash values for diverse Nim types
- md5 module implements the MD5 checksum algorithm
- sha1 module implements a sha1 encoder and decoder

# Procs

    proc encode[T: SomeInteger | char](s: openArray[T]; safe = false): string

  Encodes `s` into base64 representation.

  This procedure encodes an openarray (array or sequence) of either integers or characters.

  If `safe` is `true` then it will encode using the URL-Safe and Filesystem-safe standard alphabet characters, which substitutes `-` instead of `+` and `_` instead of `/`.

  - https://en.wikipedia.org/wiki/Base64#URL_applications
  - https://tools.ietf.org/html/rfc4648#page-7

  See also:

  - encode proc for encoding a string
  - decode proc for decoding a string

  Examples:

      assert encode(['n', 'i', 'm']) == "bmlt"
      assert encode(@['n', 'i', 'm']) == "bmlt"
      assert encode([1, 2, 3, 4, 5]) == "AQIDBAU="

  Source Edit

    proc encode(s: string; safe = false): string {...}{.raises: [], tags: [].}

  Encodes `s` into base64 representation.

  This procedure encodes a string.

  If `safe` is `true` then it will encode using the URL-Safe and Filesystem-safe standard alphabet characters, which substitutes `-` instead of `+` and `_` instead of `/`.

  - https://en.wikipedia.org/wiki/Base64#URL_applications
  - https://tools.ietf.org/html/rfc4648#page-7

  See also:

  - encode proc for encoding an openarray
  - decode proc for decoding a string

  Examples:

      assert encode("Hello World") == "SGVsbG8gV29ybGQ="

  Source Edit

    proc encodeMime(s: string; lineLen = 75; newLine = "\c\n"): string {...}{.raises: [],
        tags: [].}

  Encodes `s` into base64 representation as lines. Used in email MIME format, use `lineLen` and `newline`.

  This procedure encodes a string according to MIME spec.

  See also:

  - encode proc for encoding a string
  - decode proc for decoding a string

  Examples:

      assert encodeMime("Hello World", 4, "\n") == "SGVs\nbG8g\nV29y\nbGQ="

  Source Edit

    proc initDecodeTable(): array[256, char] {...}{.raises: [], tags: [].}

  Source Edit

    proc decode(s: string): string {...}{.raises: [ValueError], tags: [].}

  Decodes string `s` in base64 representation back into its original form. The initial whitespace is skipped.

  See also:

  - encode proc for encoding an openarray
  - encode proc for encoding a string

  Examples:

      assert decode("SGVsbG8gV29ybGQ=") == "Hello World"
      assert decode("  SGVsbG8gV29ybGQ=") == "Hello World"

  Source Edit