base64: Add selectable alphabet

RFC 4648 defines two possible alphabets that may be used for
encoding and decoding, the standard alphabet in Section 4 and
an alternative URL and Filename safe alphabet in Section 5.

This commit adds the ability to specify one of the alphabets
for encoding and decoding.

Co-authored-by: Maria Scott <maria-12648430@hnc-agency.org>

lib/stdlib/doc/src/base64.xml

@@ -40,7 +40,17 @@
   <datatypes>
     <datatype>
       <name name="base64_alphabet"/>
-      <desc><p>Base 64 Encoding alphabet, see <url href="https://www.ietf.org/rfc/rfc4648.txt">RFC 4648</url>.</p>
+      <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 encoding and decoding,
+         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>
@@ -67,18 +77,54 @@
       <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" name_i="1"/>
+      <type variable="Base64"/>
       <type variable="Data" name_i="1"/>
       <type variable="DataString" name_i="2"/>
       <desc>
-        <p>Decodes a base64-encoded string to plain ASCII. See
-          <url href="https://www.ietf.org/html/rfc4648">RFC 4648</url>.</p>
+        <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>
       </desc>
     </func>
 
+    <func>
+      <name name="decode" arity="2" since="OTP @OTP-18247@"/>
+      <name name="decode_to_string" arity="2" since="OTP @OTP-18247@"/>
+      <name name="mime_decode" arity="2" since="OTP @OTP-18247@"/>
+      <name name="mime_decode_to_string" arity="2" since="OTP @OTP-18247@"/>
+      <fsummary>Decode a base64 encoded string to data.</fsummary>
+      <type variable="Base64"/>
+      <type variable="Mode" 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><anno>Mode</anno></c> parameter 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><anno>Mode</anno></c> parameter can be one of the following:</p>
+        <taglist>
+          <tag><c>standard</c></tag>
+          <item>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>
+      </desc>
+    </func>
+
     <func>
       <name name="encode" arity="1" since=""/>
       <name name="encode_to_string" arity="1" since=""/>
@@ -87,8 +133,35 @@
       <type variable="Base64" name_i="1"/>
       <type variable="Base64String"/>
       <desc>
-        <p>Encodes a plain ASCII string into base64. The result is 33% larger
-          than the data.</p>
+        <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>
+      </desc>
+    </func>
+
+    <func>
+      <name name="encode" arity="2" since="OTP @OTP-18247@"/>
+      <name name="encode_to_string" arity="2" since="OTP @OTP-18247@"/>
+      <fsummary>Encode data into base64.</fsummary>
+      <type variable="Data"/>
+      <type variable="Mode"/>
+      <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><anno>Mode</anno></c> parameter. The result is 33% larger than the data.</p>
+        <p>The <c><anno>Mode</anno></c> parameter can be one of the following:</p>
+        <taglist>
+          <tag><c>standard</c></tag>
+          <item>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>
       </desc>
     </func>
   </funcs>