|
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 implementations, 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
Real and integer Formatting
In Sheerpower, the r and i formats are used for numeric values, representing Real and Integer types, respectively. For compatibility with other implementations of sprintf, the f format can also be used for Real numbers, and the d format can also be used for Integer numbers.
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:
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 "[]":
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.
Writing Numbers in Words
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:
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:
SPRINTF() and Program Safety
Sheerpower's implementation of SPRINTF() is completely safe. If a wrong data type is passed, Sheerpower will attempt 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 or become polluted when processing the SPRINTF() function.
(Show/Hide Sheerpower SPRINTF Takeaways)
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 implementations, 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
age = 33
print sprintf('Age is %', age)
Age is 33
name$ = 'Sally Sue'
age = 22
note$ = sprintf ('% is %', name$, age)
print 'Here is my note: '; note$
Here is my note: Sally Sue is 22
Real and integer Formatting
In Sheerpower, the r and i formats are used for numeric values, representing Real and Integer types, respectively. For compatibility with other implementations of sprintf, the f format can also be used for Real numbers, and the d format can also be used for Integer numbers.
print sprintf('PI is about %r', pi)
print sprintf('PI is about %i', pi)
PI is about 3.1415926535897932
PI is about 3
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 REAL rounded to three decimal digits:
print sprintf('PI is about %.3r', 3.14159265)
PI is about 3.142
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.
ox_counter = 56
print sprintf('I have % %p.', ox_counter, 'ox')
I have 56 oxen.
ox_counter = 1
print sprintf('I have % %p.', ox_counter, 'ox')
I have 1 ox.
print sprintf('%p', 'foot')
feet
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
f$ = "%tThe party is @month (month# @mm) @dd, @yyyy @mt:@m2:@s2 - or @h2:@m2:@s2 @ampm on a @day"
now_secs = seconds('')
print sprintf(f$, now_secs)
The party is June (month# 6) 10, 2022 05:32:28 - or 05:32:28 AM on a Monday
f$ = '%t@month @dd2-@mon-@yyyy'
now_secs = seconds('20221225 0000')
print sprintf(f$, now_secs)
December 25-Dec-2022
print sprintf(%t@mil Processing starting')
15-Jun-2022 08:26:47 Processing starting
print sprintf(%t@short Processing starting')
Jun09 15:11 Processing starting
print sprintf('%t Processing started')
Jun09 15:11 Processing started
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 "[]":
ssn$ = '123456789'
print sprintf('%z SSN: @@@-@@-@@@@', ssn$)
print sprintf('%z SSN: [1:3]-[4:5]-[6:9]', ssn$)
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:
a$='abcdefGHI'
print sprintf('%z[uc:1:3]-[4:5]-[lc:6:end]', a$)
ABC-de-fghi
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.
cash = 1234567.887
print sprintf('About $ %.2m', cash)
About $ 1,234,567.89
Writing Numbers in Words
Sheerpower supports the %w format for producing the written-in-words version
of a numeric value.
This is especially useful for checks, invoices, receipts, legal documents, and other business output where an amount must appear both numerically and in words.
Problem:
Business software often needs to print monetary amounts in words, such
as "One thousand two hundred thirty four and 56/100".
Solution:
Use the %w format in sprintf$() to convert
a numeric value into its written form. The integer portion is written
out in English words. The fractional portion is produced in check
style as and nn/100.
Efficiency:
By making written-number formatting part of
sprintf$(), Sheerpower eliminates boilerplate conversion
code and keeps business formatting fast, consistent, and easy to read.
For example:
a = 1234.56
print sprintf$('%r Written: %w', a, a)
Output: 1234.56 Written: One thousand two hundred thirty four and 56/100
Note: For financial output, the fractional portion is handled using
truncation to two decimal digits, not rounding. This follows
check-writing convention and ensures that the written value never
exceeds the numeric value.
amount = 1234.567
print sprintf$('%r Written: %w', amount, amount)
Output: 1234.567 Written: One thousand two hundred thirty four and 56/100
This behavior is intentional. A rounded result such as
57/100 would overstate the written amount. For check and
payment text, truncation is the safer and more conventional rule.
Some additional examples:
print sprintf$('%w', 0)
Zero and 00/100
print sprintf$('%w', 0.75)
Zero and 75/100
print sprintf$('%w', 1.01)
One and 01/100
print sprintf$('%w', -42.10)
Negative forty two and 10/100
Use %w when you want the number written in words. Use
other numeric formats such as %r or %m when
you want conventional numeric display.
Sheerpower also supports a horizontal tab format using %h. The argument value is the tab position. Tab position one is the first position.
tab_pos = 15
age = 45
print sprintf('The age was: %h%i',tab_pos, age)
The age was: 45
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:
print sprintf('Number: %10i and more.', 123)
Number: 123 and more.
By default, numbers are right-justified within columns. To left-justify a number, give
a negative column width:
print sprintf('Number: %-10i and more.', 123)
Number: 123 and more.
Octal, Hexadecimal, and Binary
The %o, %x, and %b are used to format numbers into octal, hexadecimal, and binary.
print sprintf('%i in Octal: %o Hex: %x Binary: %b', 123, 123, 123, 123)
123 in Octal: 173 Hex: 7b Binary: 1111011
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:
print sprintf ('Hello\nWorld')
Hello
World
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 |
print sprintf ('The letter (\0102)')
The letter (B)
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.
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 attempt 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 or become polluted when processing the SPRINTF() function.
(Show/Hide Sheerpower SPRINTF Takeaways)
Sheerpower SPRINTF Takeaways
SPRINTF()formats strings using placeholders (%) and arguments of any data type.- Supports standard formats (
%i,%r,%f,%d) for integers and reals, including decimal rounding with.n. - Sheerpower adds unique formats:
%p(plurals),%t(dates/times),%z(string substitutions),%m(money/commas), and%h(horizontal tabs). - Column alignment is supported with positive widths (right-justify) or negative widths (left-justify).
- Octal, hexadecimal, and binary are handled with
%o,%x, and%b. - Special characters are embedded with backslashes
(e.g.,
\n,\t,\\,\0nnn). - Optimized date/time formatting with
@shortcan process 10+ million operations per second, ideal for logging. - Safe by design: type mismatches or wrong argument counts raise clear exceptions without crashing the runtime.
|
Hide Description
|
|
|
Enter or modify the code below, and then click on RUN |
|
Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use. |
