F.5  SPRINTF String Formatting

string$ = SPRINTF(string_format$, arg1, arg2, .. )
The name stands for "String Print-Formatted". The function name was chosen to match the name of similar functions found in programming languages such as C, C++, Java, Javascript, PYTHON, etc. Unlike other implimentations, the Sheerpower SPRINTF() function is highly optimized and very fast.

Given the formatting string and a list of optional arguments, returns the string result of the arguments applied to the format. The arguments can be of any data type.

Simple Formatting Examples
Each % within the formatting string marks where the content of the additional arguments are substituted into the string. Each % marks the beginning of a format and is followed by an optional letter and other specifications.

Simple Substitution

Floating (real) and Decimal (integer) Formatting
With Sheerpower the f and d formats are for numeric values. Using a .n after the %, we can specify the number (.n) of decimal digits. This also rounds the number. For example, we might want to show a number rounded to three decimal digits:
Singulars and Plurals
One Sheerpower specific format is %p, which produces a word in its plural form if needed. The last numeric value that precedes the %p format determines if the word is produced as a singular or plural.
Dates and times
To format dates and times you use the %t formatter followed by date/time item names. Item names have a @ prefix. The sprintf() argument is the time in seconds as calculated by the seconds() function. If the seconds given is zero, then the current date and time is used.

The date/time item names are:

• @yyyy -- Four digit year -- 2022
• @yy -- Two digit year -- 22
• @month -- Month name -- January
• @mon -- Short month name -- Jan
• @mm2 -- Two digit month -- 09
• @mm -- One or Two digit month -- 9 or 10
• @dd2 -- Two digit day -- 09
• @dd -- One or two digit day number -- 9 or 10
• @h2 -- Two digit hour -- 09
• @h -- On or two digit hour -- 9 or 10
• @mt -- Military time -- 14
• @m2 -- two digit minute -- 09
• @m -- One or two digit minute -- 9 or 10
• @s2 -- Two digit seconds -- 09
• @s -- one or Two digit seconds -- 9 or 10
• @ampm -- AM or PM indictor
• @day -- Day of the week -- Monday
• @mil -- military datetime -- 15-Jun-2022 07:38:10
• @short -- short length datetime -- Jun09 13:54

If no prefixed item is given, the default of @short is used. If no sprintf() argument is given, the current datetime is used.


Dealing With String Substitutions
Often strings need to be formatted in specific ways. The %z format is used for this purpose. It supports two methods -- each character in turn substitutions using the "@" and segment substitutions using "[]": Segments are the most versatile of the two methods. For each segment, specify [aaa:zzz] where aaa is the starting location in the string and zzz is the ending location. Note that the first location is one and the last location is the length of the string. The word "end" stands for the end of the string.

Within the "[]" one can also include the additional formatting options of "uc" or "lc" for uppercasing or lowercasing the segment:
Formatting Money and Large Numbers
Another Sheerpower specific format is %m, which inserts commas into numbers as needed. It is frequently used when formatting money or large numbers. The .2 in the example below says two decimal digits will be returned. The number will also be rounded as needed.
Positioning with Horizontal Tabs
Sheerpower also supports a horizontal tab format using %h. The argument value is the tab position. Tab position one is the first position.
Column Alignment
Column alignment is accomplished by specifying the fixed width of a given number or string. The width is specified by supplying a number directly after the %. For example, to give a fixed width of 10 characters: By default, numbers are right-justified within columns. To left-justify a number, give a negative column width:
Octal, Hexadecimal, and Binary
The %o, %x, and %b are used to format numbers into octal, hexadecimal, and binary.
Embedding Special Characters
Sometimes there is a need to embed special characters into the format. The "\" (back-slash) is used for this purpose. For example, to insert a "new line" character into the format use \n. For example:
Below is the full list of special characters:

Combination	Result
\b	Backspace
\f	Form-feed
\n	New line
\r	Return
\t	Tab
\0nnn	Generate a character based on the octal value of nnn For example \0102 >> B
\\	The "\" character

Note: The SPRINTF function has many other formatting options. For details, see the "PRINTF Parameters" section here.
The %h, %m, %p, %t, and %z formats are SheerPower specific.

SPRINTF() and Program Safety
Sheerpower's implementation of SPRINTF() is completely safe. If a wrong data type is passed, Sheerpower will attenpt to coerce it to the correct data type. If this cannot be done, an exception is raised, explaining the problem. If too few or too many arguments are passed, an exception is raised. In no case will the Sheerpower runtime environment crash when processing the SPRINTF() function.