Documentation of usage of Format$ for Dndbbs v5.0a r2.0a PD 2022.

' Converts a number to a string and formats it according to instructions
' contained in a format expression.
'
'    FORMAT$(expression [,fmt$])
'
'     expression  Numeric expression to format
'
'     fmt$        String expression consisting of display-format characters
'                  that detail how the expression is displayed:
'                   Date and time formats
'                   Numeric expression formats
'
' FORMAT$(expression [,fmt$])
'
' Usage Notes
'    If fmt$ is omitted or is a null string, FORMAT$ provides the same
'     functionality as the STR$ function - that is, it converts positive
'     numbers to strings. However, numbers converted to strings using FORMAT$
'     do not have the leading space reserved to display the sign of the value,
'     while numbers converted using STR$ retain the leading space. When no
'     display formatting is required, use STR$ to convert numbers to strings.
'     See: <STR$ Function>
'
'    A format expression (fmt$) can have up to three sections separated by
'     semicolons (;). The first section formats positive values, the second
'     section formats negative values, and the third section formats zeros:
'
'         Usage Result
'         ----------------     ----------------------------------------------
'         One section only     The format applies to all numbers
'         Two sections         The first section applies to positive numbers
'                              and zeros; the second to negative numbers
'         Three sections       The first section applies to positive numbers,
'                              the second to negative numbers, and the third
'                              to zeros
'
'    If you have semicolons with nothing between them, the missing section
'     prevents that type of number from being displayed.
'
'    Visual Basic supports international formatting styles under MS-DOS
'     version 3.31 OR later.
'
'    Default settings for date and time formats are determined by the
'     operating system. See: Date and Time Command Summary
'
' Date and Time Formats
'
'  Default settings for date and time formats are determined by the operating
'   system.
'
'  Visual Basic supports international formatting styles under MS-DOS
'   version 3.31 or later. See: <FORMAT$ Function>
'
'  Date/time serial numbers can be formatted with date/time formats or with
'   numeric formats, since date/time serial numbers are stored as floating-
'   point values. Date and time formats are:
'
'         Symbol Description
'         ------   ----------------------------------------------------------
'         d        Display the day as a number without leading zeros (1-31)
'         dd       Display the day as a number with leading zeros (01-31)
'         ddd      Display the day as an abbreviation (Sun-Sat)
'         dddd     Display the day as a full name (Sunday-Saturday)
'         ddddd    Display a serial date number as a complete date
'                  (including day, month, and year)
'
'         m        Display the month as a number without leading zeros (1-12);
'                  if used immediately following h or hh, the minute rather
'                  than the month is displayed
'         mm       Display the month as a number with leading zeros (01-12);
'                  if used immediately following h or hh, the minute rather
'                  than the month is displayed
'         mmm      Display the month as an abbreviation (Jan-Dec)
'         mmmm     Display the month as a full name (January-December)
'
'         y        Display the year as a two-digit number (00-99)
'         yyyy     Display the year as a four-digit number (1900-2040)
'
'         h        Display the hour as a number without leading zeros (0-23)
'         hh       Display the hour as a number with leading zeros (00-23)
'
'         m        Display the minute as a number without leading zeros
'                  (0-59); if not used immediately following h or hh, the
'                  month rather than the minute is displayed
'         mm       Display the minute as a number with leading zeros (00-59);
'                  if not used immediately following h or hh, the month rather
'                  than the minute is displayed.
'
'         s        Display the second as a number without leading zeros (0-59)
'         ss       Display the second as a number with leading zeros (00-59)
'
'         ttttt    Display a time serial number as a complete time, including
'                  hour, minute, and second
'
'         AM/PM    (Default) Use the 12-hour clock displaying AM or am with
'         am/pm    any hour before noon; PM or pm with any hour between noon
'                  and 11:59
'         A/P      Use the 12-hour clock displaying A or a with any hour
'         a/p      before noon; P or p with any hour between noon and 11:59
'         
'
' See: <Date and Time Command Summary>  <Sample Date and Time Formats>
'
' Numeric Expression Formats
'
'  Default settings for date and time formats are determined by the operating
'   system. See: <Date and Time Command Summary>
'
'  Visual Basic supports international formatting styles under MS-DOS
'   version 3.31 or later. See: <FORMAT$ Function>
'
'  You can use the following symbols to create the format expression used
'   with FORMAT$:
'
'         Value Description
'         ---------------    ------------------------------------------------
'         Null string        General format (no formatting)
'         0                  Digit placeholder
'                             If the number has fewer digits than there are
'                              zeros (on either side of the decimal) in the
'                              format expression, leading or trailing zeros
'                              are displayed.
'                             If the number has more digits to the right of
'                              the decimal point than there are zeros to the
'                              right of the decimal in the format expression,
'                              the number is rounded to as many decimal places
'                              as there are zeros.
'                             If the number has more digits to the left of
'                              the decimal point than there are zeros to the
'                              left in the format expression, the extra digits
'                              are displayed.
'         #                  Digit placeholder
'                             Follows the same rules as for the 0 digit
'                              placeholder, except that extra zeros are not
'                              displayed if the number has fewer digits on
'                              either side of the decimal point than there
'                              are #'s on either side of the format.
'         .                  Decimal point
'                             This symbol determines how many digits (#'s or
'                              0's) display to the right and left of the
'                              decimal point. Note: Some international
'                              settings may cause the comma to be used
'                              as a decimal point rather than a period.
'                             If the format contains only #'s to the left
'                              of this symbol, then numbers smaller than 1
'                              are begun with a decimal point. To avoid this,
'                              you should use 0 as the first digit placeholder
'                              to the left of a decimal point instead of #.
'         %                  Percentage
'                             The expression is multiplied by 100 and the
'                              % character is inserted.
'         ,                  Thousands separator
'                             Visual Basic separates thousands by commas (or
'                              by periods if the country code has been set to
'                              a country other than the United States) if the
'                              format contains a comma surrounded by #'s or
'                              0's.
'                             Two adjacent commas, or a comma immediately to
'                              the left of the decimal point location (whether
'                              there is a decimal specified or not) means
'                              "Omit the three digits that fall between these
'                              commas, or between the comma and the decimal
'                              point, rounding as needed."  Large numbers can
'                              be scaled using this technique. For example,
'                              the format string "##0,,." can be used to
'                              represent 100 million, as simple 100. Numbers
'                              smaller than 1 million are displayed as 0.
'         E- E+ e- e+        Scientific format
'                             If a format contains one digit placeholder
'                              (0 or #) to the right of an E-, E+, e-, or e+,
'                              Visual Basic displays the number in scientific
'                              format and inserts an E or e between the number
'                              and its exponent.
'                             The number of 0's or #'s to the right
'                              determines the number of digits in the
'                              exponent.
'                             Use E- or e- to place a minus sign next to
'                              negative exponents. Use a E+ or e+ to place a
'                              minus sign next to negative exponents and a
'                              plus sign next to positive exponents.
'         :  + $ () space   Display literal character
'                             To display a character other than one of these,
'                              precede the character with a backslash (\) or
'                              enclose the character(s) in double quotation
'                              marks ("").
'         \                  Display next character in format string
'                             Many characters in the format string have a
'                              special meaning and cannot be displayed as
'                              literal characters unless they are preceded
'                              by a backslash. The backslash is not
'                              displayed. This is the same as enclosing the
'                              next character in double quotation marks.
'                             Examples of such characters are the date-
'                              and time-formatting characters (y, m, d, h,
'                              s, a, and p) and the numeric-formatting
'                              characters (#, 0, %, E, e, comma, and
'                              period).
'         "abc"              Display text inside double quotes
'                             To include a text string in fmt$, you must
'                              use CHR$(34) to enclose the text (34 is the
'                              ASCII code for double quotation mark).
'         :                  Time separator
'                             The time separator is used to separate hours,
'                              minutes, and seconds when time values are
'                              formatted.
'         /                  Date separator
'                             The date separator is used to separate day,
'                              month, and year when date values are formatted.
'
' See: <Sample Numeric Formats>  <Format Specifiers>
'
' Format Specifiers
'
'  The following characters are used to format numeric expressions:
'
'   Character Description
'   ---------   -------------------------------------------------------------
'   #           Digit position
'   -           Placed after digit, prints trailing sign for negative numbers
'   .           Decimal point position
'   ,           Placed left of the decimal point, prints a comma every third
'               digit
'   $$          Prints leading $
'   +           Position of number sign
'   **          Fills leading spaces with *
'   ^^^^        Prints in exponential format
'   **$         Combines ** and $$
'
'  The following characters are used to format string expressions:
'
'   Character Description
'   ---------   -------------------------------------------------------------
'   &           Prints entire string
'   \ \         Prints first n characters, where n is the number of blanks
'               between slashes + 2
'   !           Prints only the first character of the string
'
'  The following character is used to print literal characters:
'
'   Character Description
'   ---------   -------------------------------------------------------------
'
'   Note: Any character not in this list is printed as a literal.
'
' See: <PRINT Statement>
'

' Date and Time Command Summary
'
'  Visual Basic provides several different ways to manipulate and use date
'   and time values:
'
'   <Date and Time Formats>  Used to format date/time output (FORMAT$)
'   <DAY Function>           Returns the day of the month from a serial number
'   <HOUR Function>          Returns the hour from a serial number
'   <DATE$ Function>         Returns the current system date (dd-mm-yyyy)
'   <DATE$ Statement>        Sets the current system date
'   <DATESERIAL Function>    Returns a serial number from y%, m%, d% arguments
'   <DATEVALUE Function>     Returns a serial number from a date string
'   <FORMAT$ Function>       Converts a number to a string and formats it
'   <MINUTE Function>        Returns the minute from a serial number
'   <MONTH Function>         Returns the month from a serial number
'   <NOW Function>           Returns serial number equal to current date/time
'   <ON TIMER Statement>     Branches to a specified routine after n seconds
'   <SECOND Function>        Returns the seconds from a serial number
'   <Serial Numbers>         Defines Visual Basic date/time code conventions
'   <TIME$ Function>         Returns the current system time (hh:mm:ss)
'   <TIME$ Statement>        Sets the current system time
'   <Timer Control>          Runs a procedure at a set time interval
'   <Timer Event>            Occurs when timer control interval has elapsed
'   <TIMESERIAL Function>    Returns a serial number from h%, m%, s% arguments
'   <TIMER Statement>        Enables/disables/suspends timer event trapping
'   <TIMEVALUE Function>     Returns a serial number from a time string
'   <WEEKDAY Function>       Returns the day of the week from serial number
'   <YEAR Function>          Returns the year from serial number
'
' See: <Keywords by Task>
'
' Evaluates a date/time serial number and returns the day of the month, a
' value in the range 1 to 31, inclusive.
'
'    DAY(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Evaluates a date/time serial number and returns the hour, a value between 0
' (12:00 A.M.) and 23 (11:00 P.M.), inclusive.
'
'    HOUR(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Returns a serial number that represents the date of the arguments.
'
'    DATESERIAL(year%, month%, day%)
'
'     year%     Year between 1753 and 2078, inclusive
'
'     month%    Month between 1 and 12, inclusive
'
'     day%      Day between 1 and 31, inclusive
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Returns a serial number that represents the date of the argument.
'
'    DATEVALUE(date$)
'
'     date$    Any valid date string between January 1, 1753 and December 31,
'               2078, inclusive
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
'
' Evaluates a date/time serial number and returns the minute, a value between
' 0 and 59, inclusive.
'
'    MINUTE(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Evaluates a date/time serial number and returns the month, a value in the
' range 1 to 12, inclusive.
'
'    MONTH(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Returns a serial number representing current system date and time.
'
'    NOW
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Evaluates a date/time serial number and returns the seconds, a value between
' 0 and 59, inclusive.
'
'    SECOND(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Serial numbers
'
'  A serial number is a date/time code used by Visual Basic to represent
'   dates and times. The valid range for a serial number is -53,688 to 65,380.
'   This equates to the date range between January 1, 1753, and December 31,
'   2078, inclusive.
'
'  The valid range for serial numbers is not the same as the valid range
'   used when setting the current system date. See: <DATE$ Statement>
'
'  Specifying arguments that return a serial number outside the valid range
'   (-53,688 to 65,380) causes Visual Basic to generate the error message,
'   "Illegal function call."
'
'  Numbers to the left of the decimal point represent the date; numbers to
'   the right of the decimal point represent the time. For example:
'
'         Serial Number       Date
'         -------------       -----------------------------------------------
'         20323.25            August 22, 1955  6:00 A.M.
'         20324.25            August 23, 1955  6:00 A.M.
'
'         367.5               January 1, 1901  12:00 P.M.
'         367.75              January 1, 1901  6:00 P.M.
'
'  A serial number with no fractional part represents a date only. A serial
'   number with only a fractional part represents a time only.
'
'  The date portion of the serial number (to the left of the decimal point)
'   can represent dates between January 1, 1753, and December 31, 2078. Dates
'   before December 30, 1899, are represented by negative numbers; dates after
'   December 30 are represented by positive numbers. For example:
'
'         Serial Number       Date
'         -------------       -----------------------------------------------
'         -1                  December 29, 1899
'          0                  December 30, 1899
'          1                  December 31, 1899
'          2                  January 1, 1900
'
'  The time portion of the serial number (to the right of the decimal point)
'   can represent times between 0 (00:00:00 A.M.) and .99999 (11:59:59 P.M. or
'   23:59:59).
'
' See: <Date and Time Command Summary>
'
' Returns a serial number that represents the time of the arguments.
'
'    TIMESERIAL(hour%, minute%, second%)
'
'     hour%      Hour between 0 (12:00 A.M.) and 23 (11:00 P.M.), inclusive
'
'     minute%    Minute between 0 and 59, inclusive
'
'     second%    Second between 0 and 59, inclusive
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Returns a serial number that represents the time of the argument.
'
'    TIMEVALUE(time$)
'
'     time$  A time between 0:00:00 (12:00:00 A.M.) and 23:59:59
'             (11:59:59 P.M.), inclusive; time$ value can be entered as
'             "2:24PM" or "14:24"; date information, if included in time$,
'             is ignored
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Evaluates a date/time serial number and returns the day of the week.
'
'    WEEKDAY(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>
'
' Evaluates a date/time serial number and returns the year, a value in range
' 1753 to 2078, inclusive.
'
'    YEAR(serial)
'
'     serial    Serial number in the range -53,688 to 65,380 that represents
'                a date and/or time
'
' See Also
'    <Date and Time Command Summary>    <Serial Numbers>

