FormatString function formats numbers, or a string.  It powerful tool that is also basically the same C++ printf function explain on the page the link displays.

 

Syntax:

formattedString = FormatString( stringToFormat, value1, [value2], [value3] )

 

Parameter:

Description:

 

stringToFormat

String to be formatted: "%[flags] [width] [.precision]"

 

Use: %i when formatting integers, %f when formatting floats, and %s when formatting strings.

value1

Can be any Integer, Floating or String TYPE expression or value.

[value2]

Optional: Integer, Floating or String TYPE expression of value.

[value3]

Optional:  This optional parameter number must be a Floating TYPE variable.

formattedString

Result returns a formatted string.

 

Additional Arguments:

Depending on the format string, function may expect a sequence of additional arguments.  Each additional argument containing one value to be inserted instead of each %- tag specified in the format parameter, when used.

There should be the same number of arguments as the number of %- tags that expect a value.

%[flags][width][.precision][length]specifier

 
Where specifier is the most significant one and defines the type and the interpretation of the value of the corresponding argument:

specifier

Output

Example

c

Character

a

d or i

Signed decimal integer

392

e

Scientific notation (mantise/exponent) using e character

3.9265e+2

E

Scientific notation (mantise/exponent) using E character

3.9265E+2

f

Decimal floating point

392.65

g

Use the shorter of %e or %f

392.65

G

Use the shorter of %E or %f

392.65

o

Signed octal

610

s

String of characters

sample

u

Unsigned decimal integer

7235

x

Unsigned hexadecimal integer

7fa

X

Unsigned hexadecimal integer (capital letters)

7FA

p

Pointer address

B800:0000

n

Nothing printed. The argument must be a pointer to a signed int, where the number of characters written so far is stored.

 

%

A % followed by another % character will write % to the string.

 

 
The tag can also contain flags, width, .precision and modifiers sub-specifiers, which are optional and follow these specifications:

flags

Description

-

Left-justify within the given field width; Right justification is the default (see width sub-specifier).

+

Forces to preceded the result with a plus or minus sign (+ or -) even for positive numbers. By default, only negative numbers are preceded with a - sign.

(space)

If no sign is going to be written, a blank space is inserted before the value.

#

Used with o, x or X specifiers the value is preceded with 0, 0x or 0X respectively for values different than zero.

 

Used with e, E and f, forces the written output to contain a decimal point even if no digits would follow. If no digits follow, no decimal point is written by default.

 
Used with g or G the result is the same as with e or E but trailing zeros are not removed.

0

Left-pads the number with zeroes (0)instead of spaces, where padding is specified (see width sub-specifier).

 

width

Description

(number)

Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.

*

The width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted.

 

.precision

description

.number

For integer specifiers (d, i, o, u, x, X): precision specifies the minimum number of digits to be written.

If the value to be written is shorter than this number, the result is padded with leading zeros.

 

The value is not truncated even if the result is longer.

 

A precision of 0 means that no character is written for the value 0.

For e, E and f specifiers: this is the number of digits to be printed after the decimal point.

For g and G specifiers: This is the maximum number of significant digits to be printed.

For s: this is the maximum number of characters to be printed.  By default all characters are printed until the ending null character is encountered.

For c type, there is no effect.
Without a specified precision, the default precision is 1.

If the period is specified without an explicit value for precision, 0 is assumed.

.*

The precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted.

 

length

description

h

The argument is interpreted as a short int or unsigned short int (only applies to integer specifiers: i, d, o, u, x and X).

l

The argument is interpreted as a long int or unsigned long int for integer specifiers (i, d, o, u, x and X), and as a wide character or wide character string for specifiers c and s.

L

The argument is interpreted as a long double (only applies to floating point specifiers: e, E, f, g and G).

 

 

Note: Use %i when formatting integers, %f when formatting floats, and %s when formatting strings.

 

Example:

PRINT FormatString( "I am %i years old.", 5 )                    
 
PRINT FormatString( "The price of an %s is $%.2f today.", "apple", 100.123456 )      
 
PRINT FormatString( "I'd like to say %s to %s.", "hello", "Sam" )            
 

Results:

I am 5 years old.

The price of an apple is $100.12 today.

I'd like to say hello to Sam.

 

 

The following will create a string variable with tabSize spaces:

Example:

Variables: myPaddingString   Type: String

 
Variables: tabSize           Type: Integer
tabSize =  6
myPaddingString = FormatString( "% *s", tabSize, "" )
 
Print "myPaddingString = ", myPaddingString + ":"
Print "myPaddingString length = ", len(myPaddingString)

 

Results:

myPaddingString =        :

myPaddingString length =  6

 

The following will convert a larger number to a string variable with commas:

Example:

VARIABLES: decimalNum TYPE: FLOATING
 
decimalNum = 1235687.14254
 
PRINT "No Commas in number: " + AsString(decimalNum, 2)
PRINT "Account Balance is $" + AsString(decimalNum, 2, TRUE)

 

Result:

No Commas in number: 1235687.14

Account Balance is $1,235,687.14

 
The following will print the string "1234" padded within 10 leading spaces:

Example:

PRINT "|", FormatString( "% 10s", "1234" ) + "|"

 

Results:

|       1234|

 
These numbers will be right justified in columns:

Example:

PRINT "|", _
    + FormatString( "% 10s", AsString( 5.12 ) ) _
    + FormatString( "% 10s", AsString( 500 ) ) _
    + "|"

Results:

| 5.120000000       500|

 
You can also replace the hard coded padding with an integer variable like this:

Example:

VARIABLES: tabSize TYPE: integer
tabSize = 10
 
PRINT "|", _
    + FormatString( "% *s", tabSize, AsString( 5 ) ) _
    + FormatString( "% *s", tabSize, AsString( 5.123 ) )_
    + "|"
 
PRINT "|", _
    + FormatString( "% *s", tabSize, AsString( 5.12 ) ) _
    + FormatString( "% *s", tabSize, AsString( 500 ) )_
    + "|"

Results:

|          55.123000000|

| 5.120000000       500|

 
The following will do the above, but limit the decimals to 2 places:

Example:

VARIABLES: tabSize                   Type: INTEGER
VARIABLES: floatValue1, floatValue2 TYPE: FLOATING
 
tabSize = 10
floatValue1 = 5
floatValue2 = 5.123
 
PRINT "|", _
    + FormatString( "% *.2f", tabSize, floatValue1 ) _
    + FormatString( "% *.2f", tabSize, floatValue2 ) _
    + "|"

Results:

|       5.00      5.12|

 
The following will do the dynamic padding, and also dynamic number of decimals:

Example:

VARIABLES: tabSize, decimals         TYPE: INTEGER
VARIABLES: floatValue1, floatValue2 TYPE: FLOATING
 
tabSize = 20
decimals = 2
 
floatValue1 = Random( 1000 ) / Random( 10 )
floatValue2 = Random( 100 ) / Random( 10 )
 
PRINT "|", _
    + FormatString( "% *.*f", tabSize, decimals, floatValue1 ) _
    + FormatString( "% *.*f", tabSize, decimals, floatValue2 ) _
    + "|"

Results:

|               106.83               10.00|

 

Links:

AsString, Random

See Also:

Data Groups and Types

 


Edit Time: 9/25/2017 09:09:58 AM


Topic ID#: 347

 

Created with Help & Manual 7 and styled with Premium Pack Version 2.80 © by EC Software