View source for BitClearString, BitFlipString, and BitSetString (String functions)

{{Template:String:BitSetString subtitle}}
These functions provide the ability to manipulate individual bits in a string via a bit number.
==Syntax==
{{Template:String:BitClearString syntax}}
{{Template:String:BitFlipString syntax}}
{{Template:String:BitSetString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%result</th><td>A copy of the input (method object) string with a single bit (possibly) modified.</td></tr>
<tr><th>string</th>
<td>The string for which a bit is to be modified.</td></tr>
<tr><th>bitNumber</th>
<td>The bit number in the input string that is to be modified. Note that this is a bit number not a bit offset. So the first bit in the string is bit number 1.</td></tr>
</table>
<ul>
<li><var>BitClearString</var> turns off the indicated bit. If it is already off, the bit stays off.</li>
<li><var>BitFlipString</var> changes the indicated bit. If it is on, the bit is turned off; if it is off, the bit is turned on.</li>
<li><var>BitSetString</var> turns on the indicated bit. If it is already on, the bit stays on.</li>
</ul>
==Usage notes==
<ul>
<li>Requesting a non-positive bit number, or a bit number past the the end of the string results in an [[InvalidBitNumber class|InvalidBitNumber exception]] being thrown.</li>
<li>Since each byte in a string has 8 bits, the valid bit numbers range from 1 to the length of the string times 8. So a null (zero-length) string has no valid bits.</li>
<li>The value of a bit in a string can be tested with the [[BitValueString (String function)|BitValueString function]].</li>
<li>Manipulating bits in a string provides an CPU and space efficient alternative to an array or [Arraylist Class|Arraylist]] when the possible values are always 0 or 1 or <var>True</var> or <var>False</var>. However, because the bit manipulation methods require the copying of the string value for each operation, this benefit tends to be blunted as the strings get longer. So while there is no restriction on the length of a string and bit number with the string that these methods will update &ndash; they can even update bit numbers greater than 2G since a 2G-1 longstring has 16G-8 bits</li> &ndash; it's probably not a good idea to use these functions heavily on strings longer than 255 bytes (2040 bits) or so.</li>
</ul>

==Examples==
This example creates a 128-byte string of null bytes, then sets every 3rd bit, clears every 4th bit, and then flips (inverts), every 5th bit, finally display the results in hexadecimal format:
<p class="code">%string        is string len 255
%i       is float
 ...
%string = '00':x:[[Left (String function)|left]](128, pad='00':x')

for %i from 1 to %string:length * 8 by 3
   %string = %string:bitSetString(%i)
end for

for %i from 1 to %string:length * 8 by 4
   %string = %string:bitClearString(%i)
end for

for %i from 1 to %string:length * 8 by 5
   %string = %string:bitFlipString(%i)
end for
</p>
==See also==
<table>
<tr>
<td>
<ul>
<li><var>[[BitAndString (String function)|BitAndString]]</var>
<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>[[BitCountString (String function)|BitCountString]]</var>
<li><var>[[BitValueString (String function)|BitValueString]]</var>
</ul>
</td>
</table>
{{Template:String:BitSetString footer}}