$D2C: Difference between revisions

Revision as of 18:32, 11 September 2013

Binary byte representation of integer

Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $D2C function is FloatToString. For a full list of string and numeric conversion functions see List of String methods and List of Float methods.

The $D2C function returns a byte string which is the binary equivalent of an integer.

$D2C accepts one required and one optional argument and returns a byte string value.

The first argument is the integer to be converted. If it is omitted, or if after conversion to an integer it is outside the range -2,147,483,647..2,147,483,647, the null string is the result.

The second argument is the number of output bytes in the string. If it is omitted, the first argument must be non-negative, and as many bytes as necessary (1, 2, 3, or 4) are used as the result. If, after conversion to an integer, argument two is not in the range 0..255, the null string is the result.

The returned result is a byte string representing, in binary, the integer part of argument one. If argument two is omitted, the result has as many bytes needed to represent (the non-negative) argument one. Otherwise, the result is sign-extended to as many bytes as specified in argument two, or truncated. A null string is returned for invalid arguments.

Syntax

%result = $D2C(int_val, width)

%result is set to the width-char binary byte representation of int_val.

Usage notes

$D2C is similar to the standard $BINARY function, with some differences, such as being able to specify the output length in bytes rather than bits, and being able to specify results of lengths other than 2 or 4 bytes in length.
The inverse of $D2C is $C2D. See also the $D2X and $X2D functions and the $C2X and $X2C functions.

Example

The following program will print the value AB:

B PRINT $D2C(256 * $X2D('C1') + $X2D('C2')) END

Here are some other results, with the result shown as the hexadecimal representation of the returned byte string, or as to indicate the null string:

$D2C(9) -> X'09' $D2C(129) -> X'81' $D2C(129, 1) -> X'81' $D2C(129, 2) -> X'0081' $D2C(257, 1) -> X'01' $D2C(-127, 1) -> X'81' $D2C(-127, 2) -> X'FF81' $D2C(-127) -> $D2C(-1, 4) -> X'FFFFFFFF' $D2C(12, 0) ->

Products authorizing $D2C

@@ Line 4: / Line 4: @@
 <p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $D2C function is <var>[[FloatToString (Float function)|FloatToString]]</var>.  For a full list of string and numeric conversion functions see [[List of String methods]] and [[List of Float methods]].</p>
-The $D2C function returns a byte string which is the binary equivalent of an integer.
+The <var>$D2C</var> function returns a byte string which is the binary equivalent of an integer.
-$D2C accepts one required and one optional argument and returns a byte string value.
+<var>$D2C</var> accepts one required and one optional argument and returns a byte string value.
 The first argument is the integer to be converted. If it is omitted, or if after conversion to an integer it is outside the range -2,147,483,647..2,147,483,647, the null string is the result.
@@ Line 17: / Line 17: @@
 <p class="syntax"><span class="term">%result</span> = $D2C(int_val, width)
 </p>
-<p>
-</p>
-<p><var class="term">%result</var> is set to the width-char binary byte representation of int_val.</p>
-The following program will print the value <tt>AB</tt>:
+<p><var class="term">%result</var> is set to the width-char binary byte representation of <var class="term">int_val</var>.</p>
+==Usage notes==
+<ul>
+<li><var>$D2C</var> is similar to the standard <var>[[$BINARY]]</var> function, with some differences, such as being able to specify the output length in bytes rather than bits, and being able to specify results of lengths other than 2 or 4 bytes in length.
-<p class="code"> B
+<li>The inverse of <var>$D2C</var> is <var>[[$C2D]]</var>. See also the <var>[[$D2X]]</var> and <var>[[$X2D]]</var> functions and the <var>[[$C2X]]</var> and <var>[[$X2C]]</var> functions.
- PRINT $D2C(256 * $X2D('C1') + $X2D('C2'))
+</ul>
- END
-</p>
-Here are some other results, with the result shown as the hexadecimal representation of the returned byte string, or as "''" to indicate the null string:
+==Example==
+The following program will print the value <code>AB</code>:
-<p class="code"> $D2C(9) -> X'09'
+<p class="code">B
- $D2C(129) -> X'81'
+PRINT $D2C(256 * $X2D('C1') + $X2D('C2'))
- $D2C(129, 1) -> X'81'
+END
- $D2C(129, 2) -> X'0081'
- $D2C(257, 1) -> X'01'
- $D2C(-127, 1) -> X'81'
- $D2C(-127, 2) -> X'FF81'
- $D2C(-127) -> ''
- $D2C(-1, 4) -> X'FFFFFFFF'
- $D2C(12, 0) -> ''
 </p>
-$D2C is similar to the standard <var>$Binary</var> function (described in the <i>[http://www.rocketsoftware.com/m204/products/index/documentation/v7r4/M204-User-Language/view Rocket Model 204 User Language Manual]</i>), with some differences, such as being able to specify the output length in bytes rather than bits, and being able to specify results of lengths other than 2 or 4 bytes in length.
+Here are some other results, with the result shown as the hexadecimal representation of the returned byte string, or as <code>''</code> to indicate the null string:
-The inverse of $D2C is [[$C2D]]. See also the [[$D2X]] and [[$X2D]] functions and the $C2X and $X2C functions (in the <var class="product">[http://www.rocketsoftware.com/m204/products/index/documentation/v7r4/M204-User-Language/view Rocket Model 204 User Language Manual]</var>).
+<p class="code">$D2C(9) -> X'09'
+$D2C(129) -> X'81'
+$D2C(129, 1) -> X'81'
+$D2C(129, 2) -> X'0081'
+$D2C(257, 1) -> X'01'
+$D2C(-127, 1) -> X'81'
+$D2C(-127, 2) -> X'FF81'
+$D2C(-127) -> ''
+$D2C(-1, 4) -> X'FFFFFFFF'
+$D2C(12, 0) -> ''
+</p>
 ==Products authorizing {{PAGENAMEE}}==