emBASIC Reference: Datatypes

14 Format specification

The formatting depends on the locale and internationalization subsystem. The following specifications exist for the default locale and language en-US only.
Format strings are used in special formatting functions like FMT and for the USING clause in PRINT statements.
Generally, the format string is a character string. The format string is composed of zero or more directives:

ordinary characters (not starting with a %), which are copied unchanged to the output stream
conversion specifications, each of which results in fetching subsequent argument.

Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order)

zero or more flags,
an optional minimum field width,
an optional precision and
an optional length modifier.

The arguments must correspond properly (after type promotion) with the conversion specifier.

14.1 Format string for numbers

targetdata = FMT(<formatspec>,<sourcedata>)
PRINT USING ("<formatspec>") <sourcedata>

The behavior is similar to the one used in the C-Language, it however expects only one argument per one format string. The format specifier is composed of a flag character %, followed by 0 or more of the following flags:

	0	The value should be zero padded. The converted value is padded on the left with zeros rather than blanks. If the 0 and - flags both appear, the 0 flag is ignored. If a precision is given with a numeric conversion, the 0 flag is ignored.
	-	The converted value is to be left adjusted on the field boundary. (The default is right justification.) The converted value is padded on the right with blanks by default (if padding character not specified), rather than on the left with blanks or zeros.
	=	The converted value is to be center adjusted on the field boundary. (The default is right justification.)
	' ' (space)	A blank should be left before a positive number (or empty string) produced by a signed conversion.
	+	A sign (+ or -) always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A + overrides a space if both are used.
	'<char>	' followed by a single character specifies alternate padding char.
	field width	An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with padding character (if specified) on the left (or right, or centered the adjustment flag has been given)
	precision	An optional precision, in the form of a period (`.') followed by an optional decimal digit string. Alternate width/precision specification
	mask	It is possible to specify so called “mask” to produce desired output. @ is used as position. For example 7.3 combination could be replaced with “@@@@@@@.@@@”.
	The conversion specifier	A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are

	d	The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.
	o,u,x,X,b	The unsigned int argument is converted to unsigned binary (b), octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x conversions; the letters ABCDEF are used for X conversions.
	f	The double argument is rounded and converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.
	g	The double argument is converted in style f or e. The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.
	e	The double argument is rounded and converted in the style [-]d.ddde\*(Pmdd where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears.

Examples: ###

14.2 Format string for date and time

### Function name TBD

targetdata = FMTT(<formatspec>,<sourcedata>)

Ordinary characters placed in the format string are copied to s without conversion. Conversion specifiers are introduced by a `%' character, and are replaced in s as follows:
%a
The abbreviated weekday name according to the current locale.
%A
The full weekday name according to the current locale.
%b
The abbreviated month name according to the current locale.
%B
The full month name according to the current locale.
%c
The preferred date and time representation for the current locale.
%C
The century number (year/100) as a 2-digit integer.
%d
The day of the month as a decimal number (range 01 to 31).
%D
Equivalent to %m/%d/%y. (Yecch - for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.)
%e
Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.
%F
Equivalent to %Y-%m-%d (the ISO 8601 date format).
%H
The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I
The hour as a decimal number using a 12-hour clock (range 01 to 12).
%k
The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.
%l
The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank.
%m
The month as a decimal number (range 01 to 12).
%M
The minute as a decimal number (range 00 to 59).
%p
Either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as `pm' and midnight as `am'.
%P
Like %p but in lowercase: `am' or `pm' or a corresponding string for the current locale.
%r
The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to `%I:%M:%S %p'.
%R
The time in 24-hour notation (%H:%M). For a version including the seconds, see %T below.
%S
The second as a decimal number (range 00 to 61).
%T
The time in 24-hour notation (%H:%M:%S).
%u
The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
%w
The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%x
The preferred date representation for the current locale without the time.
%X
The preferred time representation for the current locale without the date.
%y
The year as a decimal number without a century (range 00 to 99).
%Y
The year as a decimal number including the century.
%Z
The time zone or name or abbreviation.
%%
A literal `%' character.

14.3 Format string for monetary data

### Function name still to be discussed

Basic command missing
=f
The single-byte character f is used as the numeric fill character (to be used with a left precision, see below). When not specified, the space character is used.
^
Do not use any grouping characters that might be defined for the current locale. By default, grouping is enabled.
( or +
The ( flag indicates that negative amounts should be enclosed between parentheses. The + flag indicates that signs should be handled in the default way, that is, amounts are preceded by the locale's sign indication, e.g., nothing for positive, "-" for negative.
!
Omit the currency symbol.
-
Left justify all fields. The default is right justification.
Next, there may be a field width: a decimal digit string specifying a minimum field width in bytes. The default is 0. A result smaller than this width is padded with spaces (on the left, unless the left-justify flag was given).
Next, there may be a left precision of the form "#" followed by a decimal digit string. If the number of digits left of the radix character is smaller than this, the representation is padded on the left with the numeric fill character. Grouping characters are not counted in this field width.
Next, there may be a right precision of the form "." followed by a decimal digit string. The amount being formatted is rounded to the specified number of digits prior to formatting. The default is specified in the configuration of the current locale. If the right precision is 0, no radix character is printed. (The radix character here is determined by MONETARY locale class, and may differ from that specified by NUMERIC locale class.)
Finally, the conversion specification must be ended with a conversion character. The three conversion characters are
%
(In this case the entire specification must be exactly "%%".) Put a `%' character in the result string.
i
One argument of type double is converted using the locale's international currency format.
n
One argument of type double is converted using the locale's national currency format.
Examples:
MONEYFMT("[%^=*#6n] [%=*#6i]", 1234.567, 1234.567)
outputs
[ fl **1234,57] [ NLG **1 234,57]

###
in the Dutch locale (with fl for "florijnen" and NLG for Netherlands Guilders). The Italian, Australian, Swiss and Portuguese locales yield
[ L. **1235] [ ITL **1.235]
[ $**1234.57] [ AUD **1,234.57]
[Fr. **1234,57] [CHF **1.234,57]
[ **1234$57Esc] [ **1.234$57PTE ]