<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2007</year><year>2023</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>base64</title>
    <prepared>Ingela Anderton Andin</prepared>
    <docno></docno>
    <date>2007-02-22</date>
    <rev></rev>
    <file>base64.xml</file>
  </header>
  <module since="">base64</module>
  <modulesummary>Provides base64 encode and decode, see
    RFC 2045.</modulesummary>
  <description>
    <p>Provides base64 encode and decode, see
      <url href="https://www.ietf.org/rfc/rfc2045.txt">RFC 2045</url>.</p>
  </description>

  <datatypes>
    <datatype>
      <name name="base64_alphabet"/>
      <desc><p>Base 64 Encoding alphabet, see
        <url href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</url>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="base64_mode"/>
      <desc>
        <p>Selector for the Base 64 Encoding alphabet used for
	<seemfa marker="#encode/2">encoding</seemfa> and
	<seemfa marker="#decode/2">decoding</seemfa>.
         See <url href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</url>
         Sections <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-4">4</url>
         and <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-5">5</url>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="options" />
      <desc>
        <p>Customises the behaviour of the encode and decode functions.
	Default value if omitted entirely or partially is
        <c>#{mode => standard, padding => true}</c>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="base64_string"/>
      <desc><p>Base 64 encoded string.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="base64_binary"/>
      <desc><p>Base 64 encoded binary.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="byte_string"/>
      <desc><p>Arbitrary sequences of octets.</p>
      </desc>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name name="decode" arity="1" since=""/>
      <name name="decode_to_string" arity="1" since=""/>
      <name name="mime_decode" arity="1" since=""/>
      <name name="mime_decode_to_string" arity="1" since=""/>
      <fsummary>Decode a base64 encoded string to data.</fsummary>
      <type variable="Base64"/>
      <type variable="Data" name_i="1"/>
      <type variable="DataString" name_i="2"/>
      <desc>
        <p>Decodes a base64 string encoded using the standard alphabet according
          to <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-4">RFC 4648
          Section 4</url> to plain ASCII.</p>
        <p><c>mime_decode/1</c> and <c>mime_decode_to_string/1</c> strip away
          illegal characters, while <c>decode/1</c> and
          <c>decode_to_string/1</c> only strip away whitespace characters.</p>
        <p>Checks the correct number of <c>=</c> padding characters
          at the end of the encoded string.</p>
      </desc>
    </func>

    <func>
      <name name="decode" arity="2" since="OTP 26.0"/>
      <name name="decode_to_string" arity="2" since="OTP 26.0"/>
      <name name="mime_decode" arity="2" since="OTP 26.0"/>
      <name name="mime_decode_to_string" arity="2" since="OTP 26.0"/>
      <fsummary>Decode a base64 encoded string to data.</fsummary>
      <type variable="Base64"/>
      <type variable="Options" name_i="1"/>
      <type variable="Data" name_i="1"/>
      <type variable="DataString" name_i="2"/>
      <desc>
        <p>Decodes a base64 string encoded using the alphabet indicated by the
          <c>mode</c> option to plain ASCII.</p>
        <p><c>mime_decode/2</c> and <c>mime_decode_to_string/2</c> strip away
          illegal characters, while <c>decode/2</c> and
          <c>decode_to_string/2</c> only strip away whitespace characters.</p>
        <p>The <c>mode</c> option can be one of the following:</p>
        <taglist>
          <tag><c>standard</c></tag>
          <item>Default. Decode the given string using the standard base64 alphabet according
            to <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-4">RFC 4648
            Section 4</url>, that is <c>"+"</c> and <c>"/"</c> are representing bytes <c>62</c>
            and <c>63</c> respectively, while <c>"-"</c> and <c>"_"</c> are illegal
            characters.</item>
          <tag><c>urlsafe</c></tag>
          <item>Decode the given string using the alternative "URL and Filename safe" base64
            alphabet according to
            <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-5">RFC 4648
            Section 5</url>, that is <c>"-"</c> and <c>"_"</c> are representing bytes <c>62</c>
            and <c>63</c> respectively, while <c>"+"</c> and <c>"/"</c> are illegal
            characters.</item>
        </taglist>
        <p>The <c>padding</c> option can be one of the following:</p>
        <taglist>
          <tag><c>true</c></tag>
          <item>Default. Checks the correct number of <c>=</c> padding characters
            at the end of the encoded string.</item>
          <tag><c>false</c></tag>
          <item>Accepts an encoded string with missing <c>=</c> padding characters
            at the end.</item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="encode" arity="1" since=""/>
      <name name="encode_to_string" arity="1" since=""/>
      <fsummary>Encode data into base64.</fsummary>
      <type variable="Data"/>
      <type variable="Base64" name_i="1"/>
      <type variable="Base64String"/>
      <desc>
        <p>Encodes a plain ASCII string into base64 using the standard alphabet
          according to <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-4">RFC 4648
          Section 4</url>. The result is 33% larger than the data.</p>
        <p>Always appends correct number of <c>=</c> padding characters
          to the encoded string.</p>
      </desc>
    </func>

    <func>
      <name name="encode" arity="2" since="OTP 26.0"/>
      <name name="encode_to_string" arity="2" since="OTP 26.0"/>
      <fsummary>Encode data into base64.</fsummary>
      <type variable="Data"/>
      <type variable="Options"/>
      <type variable="Base64" name_i="1"/>
      <type variable="Base64String"/>
      <desc>
        <p>Encodes a plain ASCII string into base64 using the alphabet indicated by
          the <c>mode</c> option. The result is 33% larger than the data.</p>
        <p>The <c>mode</c> option can be one of the following:</p>
        <taglist>
          <tag><c>standard</c></tag>
          <item>Default. Encode the given string using the standard base64 alphabet according
            to <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-4">RFC 4648
            Section 4</url>.</item>
          <tag><c>urlsafe</c></tag>
          <item>Encode the given string using the alternative "URL and Filename safe" base64
            alphabet according to
            <url href="https://datatracker.ietf.org/doc/html/rfc4648#section-5">RFC 4648
            Section 5</url>.</item>
        </taglist>
        <p>The <c>padding</c> option can be one of the following:</p>
        <taglist>
          <tag><c>true</c></tag>
          <item>Default. Appends correct number of <c>=</c> padding characters
            to the encoded string.</item>
          <tag><c>false</c></tag>
          <item>Skips appending <c>=</c> padding characters to the encoded string.</item>
        </taglist>
      </desc>
    </func>
  </funcs>
</erlref>
