TOSTR$: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:_TOSTR$}} The '''_TOSTR$''' function returns the STRING representation of a numerical value. It's a successor of the legacy STR$ function. {{PageSyntax}} : result$ = _TOSTR$({{Parameter|value}}[, {{Parameter|digits}}]) {{PageParameters}} * {{Parameter|value}} is any numerical type value to convert. * {{Parameter|digits}} is optional, if given it determines the desired number of significant digits for floating point values. This argument has...")
 
No edit summary
(5 intermediate revisions by the same user not shown)
Line 8: Line 8:


{{PageParameters}}
{{PageParameters}}
* {{Parameter|value}} is any numerical type value to convert.
* {{Parameter|value}} is any [[Variable Types|numerical type]] value to convert, literal or variable.
* {{Parameter|digits}} is optional, if given it determines the desired number of significant digits for floating point values. This argument has no effect for integer values and is silently ignored then.
* {{Parameter|digits}} is optional, if given it determines the maximum number of significant digits to convert for floating point values.
** This argument has no effect for integer values and is silently ignored, if given.
** For [[SINGLE]] values 1-7 digits are possible, for [[DOUBLE]] values 1-16 digits and for [[_FLOAT]] values 1-19 digits.
** For [[SINGLE]] values 1-7 digits are possible, for [[DOUBLE]] values 1-16 digits and for [[_FLOAT]] values 1-19 digits.
** Digit numbers exceeding the possible range are clipped to either the minimum or maximum possible.
** Digit numbers exceeding the possible range are clipped to either the minimum or maximum possible.
** Negative digit numbers will cause an "Illegal function call" error.
** Negative digit numbers will cause an "'''Illegal function call'''" error.
** The digits exceeding the given maximum are not simply cut off, but rounded to the final position converted.
*** If rounding results into a trailing ''zero(0)'', then it is omitted.




Line 38: Line 41:
{{Text|<nowiki>'min/max values for SINGLE, DOUBLE and _FLOAT</nowiki>|#919191}}
{{Text|<nowiki>'min/max values for SINGLE, DOUBLE and _FLOAT</nowiki>|#919191}}
smi! = {{Text|-3.402823E|#F580B1}}+{{Text|38|#F580B1}}
smi! = {{Text|-3.402823E|#F580B1}}+{{Text|38|#F580B1}}
smf! = {{Text|1.175494E|#F580B1}}-{{Text|38|#F580B1}}
sma! = {{Text|3.402823E|#F580B1}}+{{Text|38|#F580B1}}
sma! = {{Text|3.402823E|#F580B1}}+{{Text|38|#F580B1}}
dmi# = {{Text|-1.797693134862315D|#F580B1}}+{{Text|308|#F580B1}}
dmi# = {{Text|-1.797693134862315D|#F580B1}}+{{Text|308|#F580B1}}
dmf# = {{Text|2.225073858507201D|#F580B1}}-{{Text|308|#F580B1}}
dma# = {{Text|1.797693134862315D|#F580B1}}+{{Text|308|#F580B1}}
dma# = {{Text|1.797693134862315D|#F580B1}}+{{Text|308|#F580B1}}
fmi## = {{Text|-1.189731495357231765F|#F580B1}}+{{Text|4932|#F580B1}}
fmi## = {{Text|-1.189731495357231765F|#F580B1}}+{{Text|4932|#F580B1}}
fmf## = {{Text|3.362103143112093506F|#F580B1}}-{{Text|4932|#F580B1}}
fma## = {{Text|1.189731495357231765F|#F580B1}}+{{Text|4932|#F580B1}}
fma## = {{Text|1.189731495357231765F|#F580B1}}+{{Text|4932|#F580B1}}


{{Cl|PRINT}} {{Text|<nowiki>"Values enclosed by () to show there's no leading/trailing space."</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"Values enclosed by () to show there's no leading/trailing space."</nowiki>|#FFB100}}
{{Cl|PRINT}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(smi!); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min.  SINGLE: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(smi!); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(sma!); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min. fraction: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(smf!); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"max.  SINGLE: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(sma!); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(dmi#); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min.  DOUBLE: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(dmi#); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(dma#); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min. fraction: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(dmf#); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"max.  DOUBLE: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(dma#); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(fmi##); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min.  _FLOAT: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(fmi##); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(fma##); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"min. fraction: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(fmf##); {{Text|<nowiki>")"</nowiki>|#FFB100}}
{{Cl|PRINT}} {{Text|<nowiki>"max.  _FLOAT: ("</nowiki>|#FFB100}}; {{Cl|_TOSTR$}}(fma##); {{Text|<nowiki>")"</nowiki>|#FFB100}}


{{Cl|END}}
{{Cl|END}}
Line 60: Line 69:
Values enclosed by () to show there's no leading/trailing space.
Values enclosed by () to show there's no leading/trailing space.


(-3.402823E+38)
min.  SINGLE: (-3.402823E+38)
(3.402823E+38)
min. fraction: (1.175494E-38)
max.  SINGLE: (3.402823E+38)


(-1.797693134862315D+308)
min.  DOUBLE: (-1.797693134862315D+308)
(1.797693134862315D+308)
min. fraction: (2.225073858507201D-308)
max.  DOUBLE: (1.797693134862315D+308)


(-1.189731495357231765F+4932)
min.  _FLOAT: (-1.189731495357231765F+4932)
(1.189731495357231765F+4932)
min. fraction: (3.362103143112093506F-4932)
max.  _FLOAT: (1.189731495357231765F+4932)
{{OutputEnd}}
{{OutputEnd}}


Line 87: Line 99:
         {{Cl|PRINT}} {{Text|<nowiki>"(cropped to max. digits for "</nowiki>|#FFB100}}; typ$; {{Text|<nowiki>")"</nowiki>|#FFB100}}
         {{Cl|PRINT}} {{Text|<nowiki>"(cropped to max. digits for "</nowiki>|#FFB100}}; typ$; {{Text|<nowiki>")"</nowiki>|#FFB100}}
     {{Cl|ELSEIF}} x% > {{Text|1|#F580B1}} {{Cl|_ANDALSO}} {{Cl|INSTR}}(num$, {{Text|<nowiki>"."</nowiki>|#FFB100}}) > {{Text|0|#F580B1}} {{Cl|_ANDALSO}} {{Cl|LEN}}(num$) < x% + {{Text|1|#F580B1}} {{Cl|THEN}}
     {{Cl|ELSEIF}} x% > {{Text|1|#F580B1}} {{Cl|_ANDALSO}} {{Cl|INSTR}}(num$, {{Text|<nowiki>"."</nowiki>|#FFB100}}) > {{Text|0|#F580B1}} {{Cl|_ANDALSO}} {{Cl|LEN}}(num$) < x% + {{Text|1|#F580B1}} {{Cl|THEN}}
         {{Cl|PRINT}} {{Text|<nowiki>"(rounding eliminated digit(s))"</nowiki>|#FFB100}}
         {{Cl|PRINT}} {{Text|<nowiki>"(trailing zero (rounding) omitted)"</nowiki>|#FFB100}}
     {{Cl|ELSE}}
     {{Cl|ELSE}}
         {{Cl|PRINT}}
         {{Cl|PRINT}}
Line 111: Line 123:
11 digits:  31.415926536             
11 digits:  31.415926536             
12 digits:  31.4159265359           
12 digits:  31.4159265359           
13 digits:  31.4159265359          (rounding eliminated digit(s))
13 digits:  31.4159265359          (trailing zero (rounding) omitted)
14 digits:  31.415926535898         
14 digits:  31.415926535898         
15 digits:  31.4159265358979         
15 digits:  31.4159265358979         

Revision as of 23:01, 21 November 2024

The _TOSTR$ function returns the STRING representation of a numerical value. It's a successor of the legacy STR$ function.


Syntax

result$ = _TOSTR$(value[, digits])


Parameters

  • value is any numerical type value to convert, literal or variable.
  • digits is optional, if given it determines the maximum number of significant digits to convert for floating point values.
    • This argument has no effect for integer values and is silently ignored, if given.
    • For SINGLE values 1-7 digits are possible, for DOUBLE values 1-16 digits and for _FLOAT values 1-19 digits.
    • Digit numbers exceeding the possible range are clipped to either the minimum or maximum possible.
    • Negative digit numbers will cause an "Illegal function call" error.
    • The digits exceeding the given maximum are not simply cut off, but rounded to the final position converted.
      • If rounding results into a trailing zero(0), then it is omitted.


Description

  • Different from the legacy STR$ this function will not add a leading space to positive values, hence you can waive to the usual trimming using LTRIM$ or _TRIM$.
  • While the legacy STR$ can only handle _FLOAT values as long as they not exceed the DOUBLE range, this function supports the full _FLOAT range.


Availability

  • none

    none

  • v4.0.0

    v4.0.0

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes


Examples

Example 1
Showing the minimum and maximum of different floating point types.
'min/max values for SINGLE, DOUBLE and _FLOAT
smi! = -3.402823E+38
smf! = 1.175494E-38
sma! = 3.402823E+38
dmi# = -1.797693134862315D+308
dmf# = 2.225073858507201D-308
dma# = 1.797693134862315D+308
fmi## = -1.189731495357231765F+4932
fmf## = 3.362103143112093506F-4932
fma## = 1.189731495357231765F+4932

PRINT "Values enclosed by () to show there's no leading/trailing space."
PRINT
PRINT "min.   SINGLE: ("; _TOSTR$(smi!); ")"
PRINT "min. fraction: ("; _TOSTR$(smf!); ")"
PRINT "max.   SINGLE: ("; _TOSTR$(sma!); ")"
PRINT
PRINT "min.   DOUBLE: ("; _TOSTR$(dmi#); ")"
PRINT "min. fraction: ("; _TOSTR$(dmf#); ")"
PRINT "max.   DOUBLE: ("; _TOSTR$(dma#); ")"
PRINT
PRINT "min.   _FLOAT: ("; _TOSTR$(fmi##); ")"
PRINT "min. fraction: ("; _TOSTR$(fmf##); ")"
PRINT "max.   _FLOAT: ("; _TOSTR$(fma##); ")"

END

Values enclosed by () to show there's no leading/trailing space.

min.   SINGLE: (-3.402823E+38)
min. fraction: (1.175494E-38)
max.   SINGLE: (3.402823E+38)

min.   DOUBLE: (-1.797693134862315D+308)
min. fraction: (2.225073858507201D-308)
max.   DOUBLE: (1.797693134862315D+308)

min.   _FLOAT: (-1.189731495357231765F+4932)
min. fraction: (3.362103143112093506F-4932)
max.   _FLOAT: (1.189731495357231765F+4932)
Example 2
Showing how the optional digits argument affects the result.
num## = _PI(10): typ$ = "_FLOAT": mi% = 1: ma% = 19

PRINT "Printing _PI(10) as "; typ$; ":"
PRINT "  default:  "; _TOSTR$(num##)
FOR x% = 0 TO 20
    PRINT USING "## digits:  "; x%;
    num$ = _TOSTR$(num##, x%)
    PRINT num$; SPC(ma% + 5 - LEN(num$));
    IF x% < mi% THEN
        PRINT "(forced to at least 1 digit)"
    ELSEIF x% > ma% THEN
        PRINT "(cropped to max. digits for "; typ$; ")"
    ELSEIF x% > 1 _ANDALSO INSTR(num$, ".") > 0 _ANDALSO LEN(num$) < x% + 1 THEN
        PRINT "(trailing zero (rounding) omitted)"
    ELSE
        PRINT
    END IF
NEXT x%

END

Printing _PI(10) as _FLOAT:
  default:  31.41592653589793116
 0 digits:  3F+01                   (forced to at least 1 digit)
 1 digits:  3F+01                   
 2 digits:  31                      
 3 digits:  31.4                    
 4 digits:  31.42                   
 5 digits:  31.416                  
 6 digits:  31.4159                 
 7 digits:  31.41593                
 8 digits:  31.415927               
 9 digits:  31.4159265              
10 digits:  31.41592654             
11 digits:  31.415926536            
12 digits:  31.4159265359           
13 digits:  31.4159265359           (trailing zero (rounding) omitted)
14 digits:  31.415926535898         
15 digits:  31.4159265358979        
16 digits:  31.41592653589793       
17 digits:  31.415926535897931      
18 digits:  31.4159265358979312     
19 digits:  31.41592653589793116    
20 digits:  31.41592653589793116    (cropped to max. digits for _FLOAT)


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=TOSTR$&oldid=9305"