TOSTR$: Difference between revisions

Revision as of 18:12, 19 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.
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.
- 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.

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
v4.0.0
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 "(rounding eliminated digit(s))"
    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           (rounding eliminated digit(s))
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)

@@ Line 38: / Line 38: @@
 {{Text|<nowiki>'min/max values for SINGLE, DOUBLE and _FLOAT</nowiki>|#919191}}
 smi! = {{Text|-3.402823E|#F580B1}}+{{Text|38|#F580B1}}
+smf! = {{Text|1.175494E|#F580B1}}-{{Text|38|#F580B1}}
 sma! = {{Text|3.402823E|#F580B1}}+{{Text|38|#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}}
 fmi## = {{Text|-1.189731495357231765F|#F580B1}}+{{Text|4932|#F580B1}}
+fmf## = {{Text|3.362103143112093506F|#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}}
-{{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}} {{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}} {{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}}
@@ Line 60: / Line 66: @@
 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}}

TOSTR$: Difference between revisions

Revision as of 18:12, 19 November 2024

Contents

Syntax

Parameters

Description

Availability

Examples

See also

Navigation menu

TOSTR$: Difference between revisions

Revision as of 18:12, 19 November 2024

Syntax

Parameters

Description

Availability

Examples

See also

Navigation menu

Search