diff options
Diffstat (limited to 'lib/stdlib/doc/src/base64.xml')
| -rw-r--r-- | lib/stdlib/doc/src/base64.xml | 119 |
1 files changed, 111 insertions, 8 deletions
diff --git a/lib/stdlib/doc/src/base64.xml b/lib/stdlib/doc/src/base64.xml index bb45927c3f..a4ab294336 100644 --- a/lib/stdlib/doc/src/base64.xml +++ b/lib/stdlib/doc/src/base64.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2007</year><year>2021</year> + <year>2007</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -40,7 +40,27 @@ <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 + <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> @@ -67,15 +87,62 @@ <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> + <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 @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="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> @@ -87,10 +154,46 @@ <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> + <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 @OTP-18247@"/> + <name name="encode_to_string" arity="2" since="OTP @OTP-18247@"/> + <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> - |