$Base64 Encode: Difference between revisions

Latest revision as of 22:51, 20 September 2018

Convert byte string to base64

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Base64_Encode function is the StringToBase64 function.

This function converts a byte string into its base64 encoding. It is identical to $Lstr_Base64_Encode with the (hopefully obvious) exception that it is not longstring capable. As such, $Lstr_Base64_Encode is recommended over $Base64_Encode as it is a more flexible version of the latter.

The $Base64_Encode function accepts one argument and returns a string result which is the base64 encoding of that argument.

Syntax

%coded = $Base64_Encode(string)

%coded is a string result set to the base64 encoding of string.
%string is a byte string of length 189 or less. If this argument is longer than 189 bytes, the request is canceled.

Usage notes

Because the maximum length of the argument is 189 bytes, if you have a longer stream to encode, you can do it in pieces, where any piece is a multiple of 3 bytes long (3 bytes are evenly packed into 4 bytes of a base64 encoding). For example, if you have a byte string which is the concatenation of items in a Sirius $list, and you want to print the base64 encoding of that string, possibly producing multiple lines of length 80, you can use the following approach:
%S = FOR %I FROM 1 TO $ListCnt(%L) %T = $ListInf(%L, %I) REPEAT WHILE $LEN(%S) + $LEN(%T) > 60 %X = 60 - $LEN(%S) %U = %S WITH $SUBSTR(%T, 1, %X) PRINT $Base64_Encode(%U) %T = $SUBSTR(%T, %X + 1) %S = END REPEAT %S = %S WITH %T END FOR PRINT $Base64_Encode(%S)
As of Sirius Mods Version 6.8, you can do base64 encoding of strings longer than 255 bytes using $Lstr_Base64_Encode, but if, as in the example above, the intent is to break the result into smaller chunks, anyway, there probably wouldn't be a marked difference between using $Base64_Decode or its longstring equivalent.
$Base64_Decode is the inverse of $Base64_Encode.

Example

Given this argument of length 3:

%junk = $Base64_Encode($X2C('001083'))

%junk would be set to the byte string (of length 4) represented in character as ABCD.

Products authorizing $Base64_Encode

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:$Base64_Encode}}
-<span class="pageSubtitle">Convert byte string to base 64</span>
+<span class="pageSubtitle">Convert byte string to base64</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Base64_Encode function is the [[StringToBase64 (String function)]].</p>
+<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Base64_Encode function is the <var>[[StringToBase64 (String function)|StringToBase64]]</var> function.</p>
-This function converts a byte string into its base 64 encoding. It is identical to [[$Lstr_Base64_Encode]] with the (hopefully obvious) exception that it is not longstring capable. As such, $Lstr_Base64_Encode is recommended over <var>$Base64_Encode</var> as it is a more flexible version of the latter.
+This function converts a byte string into its base64 encoding. It is identical to <var>[[$Lstr_Base64_Encode]]</var> with the (hopefully obvious) exception that it is not [[Longstrings|longstring capable]]. As such, <var>$Lstr_Base64_Encode</var> is recommended over <var>$Base64_Encode</var> as it is a more flexible version of the latter.
-The <var>$Base64_Encode</var> function accepts one argument and returns a string result which is the base 64 encoding of that argument.
+The <var>$Base64_Encode</var> function accepts one argument and returns a string result which is the base64 encoding of that argument.
-The first argument is a byte string of length 189 or less. If this argument is longer than 189 bytes, the request is canceled.
-The returned value is the base 64 encoding of the argument string.
 ==Syntax==
-<p class="syntax">%CODED = $Base64_Encode(string)
+<p class="syntax"><span class="term">%coded</span> = <span class="literal">$Base64_Encode</span>(<span class="term">string</span>)
 </p>
-<p>
-</p>
-<p>%CODED is set to the base 64 encoding of string.</p>
+<ul>
+<li><var class="term">%coded</var> is a string result set to the base64 encoding of <var class="term">string</var>.
+<li><var class="term">%string</var> is a byte string of length 189 or less. If this argument is longer than 189 bytes, the request is canceled.
+</ul>
-For example, given the argument of length 3:
+==Usage notes==
-<p class="code"> %JUNK = $Base64_Encode($X2C('001083'))
+<ul>
-</p>
+<li>Because the maximum length of the argument is 189 bytes, if you have a longer stream to encode, you can do it in pieces, where any piece is a multiple of 3 bytes long (3 bytes are evenly packed into 4 bytes of a base64 encoding). For example, if you have a byte string which is the concatenation of items in a Sirius $list, and you want to print the base64 encoding of that string, possibly producing multiple lines of length 80, you can use the following approach:
-%JUNK would be set to the byte string (of length 4) represented in character as 'ABCD'.
-Because the maximum length of the argument is 189 bytes, if you have a longer stream to encode, you can do it in pieces, where any piece is a multiple of 3 bytes long (3 bytes are evenly packed into 4 bytes of a base 64 encoding). For example, if you have a byte string which is the concatenation of items in a Sirius $list and you wish to print the base 64 encoding of that string, possibly producing multiple lines of length 80, you can use the following approach:
 <p class="code"> %S = ''
   FOR %I FROM 1 TO $ListCnt(%L)
@@ Line 40: / Line 35: @@
 </p>
+<li>As of <var class="product">[[Sirius Mods]]</var> Version 6.8, you can do base64 encoding of strings longer than 255 bytes using [[$Lstr_Base64_Encode]], but if, as in the example above, the intent is to break the result into smaller chunks, anyway, there probably wouldn't be a marked difference between using <var>$Base64_Decode</var> or its longstring equivalent.
-As of <var class="product">[[Sirius Mods]]</var> Version 6.8, you can do base 64 encoding of strings longer than 255 bytes using [[$Lstr_Base64_Encode]], but if, as in the example above, the intent is to break the result into smaller chunks, anyway, there probably wouldn't be a marked difference between using <var>$Base64_Decode</var> or its longstring equivalent.
+<li>$Base64_Decode is the inverse of <var>$Base64_Encode</var>.
+</ul>
-$Base64_Decode is the inverse of <var>$Base64_Encode</var>.
+==Example==
+Given this argument of length 3:
+<p class="code">%junk = $Base64_Encode($X2C('001083'))
+</p>
+<code>%junk</code> would be set to the byte string (of length 4) represented in character as <code>ABCD</code>.
-This $function is new in Version 6.0 of the <var class="product">[[Sirius Mods]]</var>.
 ==Products authorizing {{PAGENAMEE}}==
 <ul class="smallAndTightList">
-<li>[[Sirius functions]]</li>
+<li>[[List of $functions|Sirius functions]]</li>
 <li>[[Fast/Unload User Language Interface]]</li>
-<li>[[Janus Open Client]]</li>
+<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
-<li>[[Janus Open Server]]</li>
+<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
 <li>[[Janus Sockets]]</li>
 <li>[[Janus Web Server]]</li>
-<li>[[Japanese functions]]</li>
+<li>Japanese functions</li>
-<li>[[Sir2000 Field Migration Facility]]</li>
+<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
 </ul>
-<p>64_Encode
-</p>
 [[Category:$Functions|$Base64_Encode]]