FloatToString (Float function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (match syntax diagram to revised template; fix tags and links)
Line 1: Line 1:
{{Template:Float:FloatToString subtitle}}
{{Template:Float:FloatToString subtitle}}


This [[Intrinsic classes|intrinsic]] function converts a floating point number to a string with a specific
The <var>FloatToString</var> <var>[[Intrinsic classes|intrinsic]]</var> function converts a floating point number to a string with a specific length and number of decimal places.
length and number of decimal places.


The <var>FloatToString</var> function is available as of version 7.6 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:Float:FloatToString syntax}}
{{Template:Float:FloatToString syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%str</th>
<tr><th>%string</th>
<td>A string variable to receive the converted value of the method object number. </td></tr>
<td>A string variable to receive the converted value of the method object number.</td></tr>
<tr><th>[Length=]len</th>
<tr><th>float</th>
<td>This optional, name-required, argument (Length) specifies the output string length. The ''len'' value must be between 1 and 255, and it defaults to the minimum length required to represent the number. </td></tr>
<td>The (input) method object <var>float</var> value that will be converted to the output <var class="term">%string</var>.</td></tr>
<tr><th>[Dp=]num</th>
<tr><th>Length</th>
<td>This optional, name-required, argument (Dp) specifies the number of decimal places in the result. The ''num'' value defaults to 0, must be between 0 and 75, and must be less than the Length parameter (if a Length value is specified).</td></tr>
<td>This is an optional, but <var class="term">nameRequired</var>, parameter which specifies the output string length. The <i>number</i> value must be between 1 and 255, and it defaults to the minimum length required to represent the number.</td></tr>
<tr><th>DP</th>
<td>This is an optional, but <var class="term">nameRequired</var>, parameter which specifies the number of decimal places in the result. The <i>number</i> value defaults to 0, must be between 0 and 75, and must be less than any <var class="term">Length</var> parameter specified.</td></tr>
</table>
</table>
==Usage notes==
==Usage notes==
If the target length and number of decimal places would result in leading
<ul><li>If the target length and number of decimal places would result in leading non-zero digits being lost, the request is canceled. For example, specifying the following results in request cancellation:
non-zero digits being lost, the request is canceled.
<p class="code">13.1415926:FloatToString(length=6, dp=4)
For example, specifying the following results in request cancellation:
<p class="code">13.1415926:floatTo<var>String</var>(length=6, dp=4)
 
</p>
</p>
<var>FloatToString</var> neatly displays non-integer numeric values.
<li><var>FloatToString</var> neatly displays non-integer numeric values. <var>[[Round_(Float_function)|Round]]</var> is not a good way of doing this, since <var>Round</var> returns a <var>Float</var> value and strips trailing 0s when printing the value.
The Round method (:hdref refid=flround.) is not a good way of doing this,
<li><var>FloatToString</var> currently does not support E format (9.9E72) output.
since Round returns a <var>Float</var> value and strips trailing 0s when printing the value.
<li>A <var class="term">DP</var> value of 0 has a special result: no decimal point. There is no way to get a trailing decimal point without any digits after it unless you explicitly append a point character ('<code>.</code>') to a result for which <var class="term">DP</var>=0 is specified, as is shown in the last of the <var>[[PrintText statement|PrintText]]</var> statements in the example below, you <b><i>can</i></b> get a value with a leading decimal point and no digit before it.
 
<li>To produce the specified length or number of decimal places in the result, <var>FloatToString</var> uses truncation, not rounding, of the input, as you can see in the last two of the PrintText statements in the example below.
<var>FloatToString</var> currently does not support E format (9.9E72) output.
<li><var>FloatToString</var> is available as of <var class="product">[[Sirius Mods]]</var> Version 7.6.</ul>
 
A ''''Dp'''' value of 0 has a special result: no decimal point.
There is no way to get a trailing decimal point without any
digits after it unless you explicitly append a point character (''''.'''')
to a result for which ''''Dp=0'''' is specified, as is shown in the last of the [[PrintText statement|PrintText]] statements in the example below,
you '''can''' get a value with a leading decimal point and no digit before it.
 
To produce the specified length or number of decimal places in the result,
<var>FloatToString</var> uses truncation, not rounding, of the input, as you can see
in the last two of the PrintText statements in the example below.


==Examples==
==Examples==
The following program demonstrates the <var>FloatToString</var> method.
<ol><li>The following program demonstrates the <var>FloatToString</var> method.
<p class="code">begin
<p class="code">begin
  [[Intrinsic classes#printtext|printText]] {~} = {0.1415926:floatToString}
    printText {~} = {0.1415926:floatToString}
  printText {~} = {0.1415926:floatToString(dp=0)}
    printText {~} = {0.1415926:floatToString(dp=0)}
  printText {~} = {0.1415926:floatToString(dp=1)}
    printText {~} = {0.1415926:floatToString(dp=1)}
  printText {~} = {0.1415926:floatToString(dp=5)}
    printText {~} = {0.1415926:floatToString(dp=5)}
  printText {~} = {0.1415926:floatToString(length=10)}
    printText {~} = {0.1415926:floatToString(length=10)}
  printText {~} = {0.1415926:floatToString(length=10, dp=1)}
    printText {~} = {0.1415926:floatToString(length=10, dp=1)}
  printText {~} = {0.1415926:floatToString(length=10, dp=4)}
    printText {~} = {0.1415926:floatToString(length=10, dp=4)}
  printText {~} = {0.1415926:floatToString(length=5, dp=4)}
    printText {~} = {0.1415926:floatToString(length=5, dp=4)}
end
end
</p>
</p>
The result is:
The result is:
<p class="output">0.1415926:floatTo<var>String</var> = 0
<p class="output">0.1415926:floatToString = 0
0.1415926:floatTo<var>String</var>(dp=0) = 0
0.1415926:floatToString(dp=0) = 0
0.1415926:floatTo<var>String</var>(dp=1) = 0.1
0.1415926:floatToString(dp=1) = 0.1
0.1415926:floatTo<var>String</var>(dp=5) = 0.14159
0.1415926:floatToString(dp=5) = 0.14159
0.1415926:floatTo<var>String</var>(length=10) =          0
0.1415926:floatToString(length=10) =          0
0.1415926:floatTo<var>String</var>(length=10, dp=1) =        0.1
0.1415926:floatToString(length=10, dp=1) =        0.1
0.1415926:floatTo<var>String</var>(length=10, dp=4) =    0.1415
0.1415926:floatToString(length=10, dp=4) =    0.1415
0.1415926:floatTo<var>String</var>(length=5, dp=4) = .1415
0.1415926:floatToString(length=5, dp=4) = .1415
</p></ol>


</p>
==See also==
==See also==
<ul><li>For details of the <var>printtext</var> statement, please see <var>[[Intrinsic classes#printtext|printText]]</var>.
</ul>
{{Template:Float:FloatToString footer}}
{{Template:Float:FloatToString footer}}

Revision as of 07:17, 3 February 2011

Convert a number to a string (Float class)


The FloatToString intrinsic function converts a floating point number to a string with a specific length and number of decimal places.

Syntax

%string = float:FloatToString[( [Length= number], [DP= number])]

Syntax terms

%string A string variable to receive the converted value of the method object number.
float The (input) method object float value that will be converted to the output %string.
Length This is an optional, but nameRequired, parameter which specifies the output string length. The number value must be between 1 and 255, and it defaults to the minimum length required to represent the number.
DP This is an optional, but nameRequired, parameter which specifies the number of decimal places in the result. The number value defaults to 0, must be between 0 and 75, and must be less than any Length parameter specified.

Usage notes

  • If the target length and number of decimal places would result in leading non-zero digits being lost, the request is canceled. For example, specifying the following results in request cancellation:

    13.1415926:FloatToString(length=6, dp=4)

  • FloatToString neatly displays non-integer numeric values. Round is not a good way of doing this, since Round returns a Float value and strips trailing 0s when printing the value.
  • FloatToString currently does not support E format (9.9E72) output.
  • A DP value of 0 has a special result: no decimal point. There is no way to get a trailing decimal point without any digits after it unless you explicitly append a point character ('.') to a result for which DP=0 is specified, as is shown in the last of the PrintText statements in the example below, you can get a value with a leading decimal point and no digit before it.
  • To produce the specified length or number of decimal places in the result, FloatToString uses truncation, not rounding, of the input, as you can see in the last two of the PrintText statements in the example below.
  • FloatToString is available as of Sirius Mods Version 7.6.

Examples

  1. The following program demonstrates the FloatToString method.

    begin printText {~} = {0.1415926:floatToString} printText {~} = {0.1415926:floatToString(dp=0)} printText {~} = {0.1415926:floatToString(dp=1)} printText {~} = {0.1415926:floatToString(dp=5)} printText {~} = {0.1415926:floatToString(length=10)} printText {~} = {0.1415926:floatToString(length=10, dp=1)} printText {~} = {0.1415926:floatToString(length=10, dp=4)} printText {~} = {0.1415926:floatToString(length=5, dp=4)} end

    The result is:

    0.1415926:floatToString = 0 0.1415926:floatToString(dp=0) = 0 0.1415926:floatToString(dp=1) = 0.1 0.1415926:floatToString(dp=5) = 0.14159 0.1415926:floatToString(length=10) = 0 0.1415926:floatToString(length=10, dp=1) = 0.1 0.1415926:floatToString(length=10, dp=4) = 0.1415 0.1415926:floatToString(length=5, dp=4) = .1415

See also

  • For details of the printtext statement, please see printText.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=FloatToString_(Float_function)&oldid=3806"