BitAndString (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (printtext)
 
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:String:BitAndString subtitle}}
{{Template:String:BitAndString subtitle}}
<var>BitAndString</var> does a logical AND of the bits in two strings.  
<var>BitAndString</var> does a logical AND of the bits in two strings.  


==Syntax==
==Syntax==
{{Template:String:BitAndString syntax}}
{{Template:String:BitAndString syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%result</th><td>A string to receive the result of ANDing together the bits in <var class="term">string</var> and <var class="term">andBits</var>.</td></tr>
<tr><th>%result</th><td>A string to receive the result of ANDing together the bits in <var class="term">string</var> and <var class="term">andBits</var>.</td></tr>
<tr><th>string</th>
<tr><th>string</th>
<td>One of the strings to be ANDed.</td></tr>
<td>One of the strings to be ANDed.</td></tr>
<tr><th>andBits</th>
<tr><th>andBits</th>
<td>The other string to be ANDed.</td></tr>
<td>The other string to be ANDed.</td></tr>
<tr><th>Pad</th>
 
<td>A single character that indicates the character with which the shorter of the two input strings is to be extended. As many copies of <var class="term">pad</var> are used as is required to make the shorter string as long as the longer. If both strings are of equal length, no padding is required. The default value of <var class="term">pad</var> is <code>'00':x</code>.</td></tr>
<tr><th><var>Pad</var></th>
<td>This [[Notation conventions for methods#Named parameters|name required]] parameter is a single character that indicates the character with which the shorter of the two input strings is to be extended. As many copies of <var class="term">c</var> are used as is required to make the shorter string as long as the longer. If both strings are of equal length, no padding is required. The default value of <var class="term">c</var> is <code>'00':x</code>.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Using a null <var class="term">string</var> or <var class="term">andBits</var> is an easy way of ANDing each byte in a string with a specific byte value (the <var class="term">pad</var> value).
<li>Using a null <var class="term">string</var> for <var class="term">andBits</var> is an easy way of ANDing each byte in a string with a specific byte value (the <var>Pad</var> value).
 
<li><var>BitAndString</var> is most useful for working with binary data, for example binary data being sent or received with <var class="product">[[Janus Sockets]]</var>.
<li><var>BitAndString</var> is most useful for working with binary data, for example binary data being sent or received with <var class="product">[[Janus Sockets]]</var>.
<li><var>BitAndString</var> was introduced in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> version 7.9.
</ul>
</ul>


==Examples==
==Examples==
<ol><li>The following example turns off the low order bit of a numeric value's string representation, rounding every digit down to an even number (because EBCDIC binary digits map 0-9 to hex values X'F0'-X'F9'):
<ol>
<p class="pre">%evenDigits = %digits:bitAndString('', pad='FE':x)
<li>The following example turns off the low order bit of a numeric value's string representation, rounding every digit down to an even number (because EBCDIC binary digits map 0-9 to hex values X'F0'-X'F9'):
<p class="code">%evenDigits = %digits:bitAndString(&#39;', pad='FE':x)
</p>
</p>
In, the above code, if <code>%digits</code> were <code>'31415926'</code>, <code>%evenDigits</code> would be set to <code class="output">'20404826'</code>.
In the above code, if <code>%digits</code> were <code>'31415926'</code>, <code>%evenDigits</code> would be set to <code class="output">'20404826'</code>.


<li>The following example:
<li>The following example:
Line 35: Line 39:
<p class="output">'Red':bitAndString('Green', pad='FF':x)=Aaden
<p class="output">'Red':bitAndString('Green', pad='FF':x)=Aaden
</p>
</p>
To see why this is correct run the following:
To see why this is correct, run the following:
<p class="pre">printText {~='Red':stringToHex}
<p class="pre">printText {~='Red':stringToHex}
printText {~='Green':stringToHex}
printText {~='Green':stringToHex}
printText {~='Red':bitAndString('Green', pad='FF':x):stringToHex}
printText {~='Red':bitAndString('Green', pad='FF':x):stringToHex}
</p>
</p>
which outputs
This is the result:
<p class="output">'Red':stringToHex=D98584
<p class="output">'Red':stringToHex=D98584
'Green':stringToHex=C799858595
'Green':stringToHex=C799858595
Line 47: Line 51:


==See also==
==See also==
<table>
<tr>
<td>
<ul>
<li><var>[[BitOffString (String function)|BitOffString]]</var>
<li><var>[[BitOnString (String function)|BitOnString]]</var>
<li><var>[[BitOrString (String function)|BitOrString]]</var>
<li><var>[[BitXorString (String function)|BitXorString]]</var>
</ul>
</td>
<td>
<ul>
<li><var>[[BitClearString, BitFlipString, and BitSetString (String functions)|BitClearString, BitFlipString, and BitSetString]]</var>
<li><var>[[BitValueString (String function)|BitValueString]]</var>
<li><var>[[BitCountString (String function)|BitCountString]]</var>
</ul>
</td>
</table>[[Category:Bit manipulation methods]]
{{Template:String:BitAndString footer}}
{{Template:String:BitAndString footer}}

Latest revision as of 20:09, 3 September 2015

Do bitwise And of strings (String class)

[Introduced in Sirius Mods 7.9]

BitAndString does a logical AND of the bits in two strings.

Syntax

%result = string:BitAndString( andBits, [Pad= c])

Syntax terms

%resultA string to receive the result of ANDing together the bits in string and andBits.
string One of the strings to be ANDed.
andBits The other string to be ANDed.
Pad This name required parameter is a single character that indicates the character with which the shorter of the two input strings is to be extended. As many copies of c are used as is required to make the shorter string as long as the longer. If both strings are of equal length, no padding is required. The default value of c is '00':x.

Usage notes

  • Using a null string for andBits is an easy way of ANDing each byte in a string with a specific byte value (the Pad value).
  • BitAndString is most useful for working with binary data, for example binary data being sent or received with Janus Sockets.

Examples

  1. The following example turns off the low order bit of a numeric value's string representation, rounding every digit down to an even number (because EBCDIC binary digits map 0-9 to hex values X'F0'-X'F9'):

    %evenDigits = %digits:bitAndString('', pad='FE':x)

    In the above code, if %digits were '31415926', %evenDigits would be set to '20404826'.

  2. The following example:

    printText {~='Red':bitAndString('Green', pad='FF':x)}

    outputs

    'Red':bitAndString('Green', pad='FF':x)=Aaden

    To see why this is correct, run the following:

    printText {~='Red':stringToHex} printText {~='Green':stringToHex} printText {~='Red':bitAndString('Green', pad='FF':x):stringToHex}

    This is the result:

    'Red':stringToHex=D98584 'Green':stringToHex=C799858595 'Red':bitAndString('Green', pad='FF':x):stringToHex=C181848595

See also