BitClearString, BitFlipString, and BitSetString (String functions): Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 20: | Line 20: | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>Requesting a non-positive bit number, or a bit number past the the end of the string results in | <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>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>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 – they can even update bit numbers greater than 2G since a 2G-1 longstring has 16G-8 bits</li> – it's probably not a good idea to use these functions heavily on strings longer than 255 bytes (2040 bits) or so.</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 – they can even update bit numbers greater than 2G since a 2G-1 longstring has 16G-8 bits</li> – it's probably not a good idea to use these functions heavily on strings longer than 255 bytes (2040 bits) or so.</li> | ||
</ul> | </ul> | ||
==Examples== | ==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: | 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: | ||
| Line 45: | Line 46: | ||
</p> | </p> | ||
==See also== | ==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}} | {{Template:String:BitSetString footer}} | ||
Latest revision as of 00:05, 22 March 2013
Set a bit in a string (String class)
[Introduced in Model 204 7.5]
These functions provide the ability to manipulate individual bits in a string via a bit number.
Syntax
%result = string:BitClearString( bitNumber) Throws InvalidBitNumber
%result = string:BitFlipString( bitNumber) Throws InvalidBitNumber
%result = string:BitSetString( bitNumber) Throws InvalidBitNumber
Syntax terms
| %result | A copy of the input (method object) string with a single bit (possibly) modified. |
|---|---|
| string | The string for which a bit is to be modified. |
| bitNumber | 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. |
- BitClearString turns off the indicated bit. If it is already off, the bit stays off.
- BitFlipString changes the indicated bit. If it is on, the bit is turned off; if it is off, the bit is turned on.
- BitSetString turns on the indicated bit. If it is already on, the bit stays on.
Usage notes
- Requesting a non-positive bit number, or a bit number past the the end of the string results in an InvalidBitNumber exception being thrown.
- 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.
- The value of a bit in a string can be tested with the BitValueString function.
- 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 True or False. 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 – they can even update bit numbers greater than 2G since a 2G-1 longstring has 16G-8 bits – it's probably not a good idea to use these functions heavily on strings longer than 255 bytes (2040 bits) or so.
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:
%string is string len 255 %i is float ... %string = '00':x: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