Format Function
Purpose
Returns a String containing an expression formatted according to instructions contained in a format expression.
Syntax
$ = Format(expression[, formsexp])
| expression | : string, numerical, variant or date |
| formsexp | : string |
Description
Format() is a conversion function for which you can format numeric, string, variant and date expressions.
Generally, the output of numeric, variant and date expressions can be altered using Mode Format, Mode Lang but not with Mode Date; however,all the predefined formats use your system's Locale settings rather than GFA's internal register and these can only be altered using Mode Lang (where this is the case, it is noted in the text). If you are dealing with dates - and sometimes numeric expressions - which will be displayed in different locales it is generally better to use the pre-defined formats if possible as the return values are automatically created using Windows Locale APIs.
The Format function can be used with or without the second parameter; if used without, then it is assumed to be an empty or null string and the function returns an expression accordingly. For example:
Debug Format(2) // Returns 2 without a leading character
Debug Format(Date) // Returns the current date in Short format
Debug Format(Now) // Returns the current date in Short Format and time in Long format
Debug Format(Now, "") // Same as above
°Debug Format("GFA") // This will fail in the IDE as GFA Strings are not supported...
Local a = "GFA"
Debug Format(a) // ...but Strings in a Variant are supported and this returns GFA
The power of the function becomes apparent when the formsexp parameter is used: this parameter can be constructed to adapt the expression to the form you require. For example:
Debug Format(Now, "Long Date") // Returns the current date in Long Date format (e.g. 21 November 2022)
Debug Format(3.41, #34"£"#34 & "###,##0.00##") // Returns £3.41
In addition, the formsexp can be divided into sections, each separated using a semi-colon (;); the number of sections available is dependant on the variable type passed as expression as follows:
- Strings - When dealing with string variables, formsexp can have two separate sections: the first contains the formatting that will be applied to all valid strings of one or more characters (or any numeric or variant information which will be converted using CStr), while the second holds the formatting that will be applied if the expression passed is a null or empty string. For example:
Debug Format("GFA Basic", "&&&;"#34"(Blank)"#34) // Returns "GFA" (dictated by formatting in first section)
Debug Format("", "&&&;"#34"(Blank)"#34) // Returns "(Blank)" (dictated by formatting in second section)
Debug Format(2.42, "&&&;"#34"(Blank)"#34) // Returns " 2." (dictated by formatting in first section)
- Numeric Variables can have up to three sections: the first formats the value if it is positive, the second if it is negative and the third if it is zero; any string passed will first be converted by CDbl. Thus:
Debug Format(2.88, #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Positive"
Debug Format(-2.88, #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Negative"
Debug Format(0, #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Zero"
Debug Format("2.88", #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Positive" (converted using CDbl)
NOTE 1: Numerical values formatted using predefined names can only have one section (see below).
NOTE 2: If the second section (negative number) is used, the absolute of the value without the minus sign is returned. This is to allow, for example, -20 to be output as (20).
- Variants are always treated as Numeric values (if the Variant contains a string, convert the variant into a GFA string first and pass that as expression instead). Therefore they have the same three sections as Numerical Values and act the same; in the original documentation, Variants are meant to have a fourth section which handles the VT_NULL (or Null Value), but this does not seem to work and raises either an Invalid Access error or is treated as a zero value.
- Dates - Dates can only have one section and, if the date is invalid, an error is raised or zero is returned.
All but the first section can be omitted and, if so, any values which correspond to the missed section will be formatted according to the first one instead, as below:
Debug Format(-2.22, #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Negative"
Debug Format(-2.22, #34"Positive"#34";;"#34"Zero"#34) // Returns "Positive"
Finally, if only one section is used, the semi-colons are not required and can be omitted.
If a value is passed which is incompatible with the format type to be output, zero is generally assumed if the value is not convertible; the below show how GB32 handles incorrect values that are passed:
Trace Format("Today", "dd/mm/yyyy") // Converts to zero and returns 30/12/1899 (or 0)
Trace Format(2.44, "@@@@") // Converts to text with leading space and returns ' 2.4' (without apostrophes)
Trace Format(#12/12/2023#, "@@@@") // Converts to text in short date format and returns 12/1 (no leading space)
Trace Format("Today", "#,##0.00") // Converts to number and returns 0.00
Trace Format("2.33", "#,##0.00") // Converts to number and returns 2.33
This list is not exhaustive but gives an idea of what to expect.
General Formatting
Show
The following characters apply to all user-defined formats.
| - + ( ) $ | The parentheses, the + and the – sign, and the $ sign are always used unchanged. This also applies to the space and many currency signs.
Debug Format(24, "(+##)") // Returns (+24)
|
| * | The character after the asterisk is used as a filler character. For strings, each & without an associated character in the string to be formatted is replaced by the filler and, for numbers, any # and any commas before the first digit displayed; the position of the * followed by the filler character is ignored. Only one filler character is possible; if more than one is entered then just the last one is used.
Debug Format(12.45, "*_\£#,##0.00##") // Returns £___12.45__
|
| \ | The character immediately following the backslash is accepted unchanged.
Debug Format(12.45, "\£#,##0.00") // Returns £12.45
|
| "string" | All characters inside the inverted commas are accepted unchanged; in all cases, the inverted commas should be inserted using ..."+Chr$(34)+"... or ..."#34"...
NOTE: If the closing inverted commas are omitted then an error is returned.
Debug Format(-2.22, #34"Positive"#34";"#34"Negative"#34";"#34"Zero"#34) // Returns "Negative"
|
| 'string' | Similar to the form above, the string is inserted unchanged, execpt in this case, apostrophes are used to delimit the string rather than inverted commas./BR>
NOTE: If the closing apostrophe is omitted then an error is returned.
Debug Format(-2.22, "'Positive';'Negative';'Zero'") // Returns "Negative"
|
String Formatting
Show
Before using this function to format strings, it is important to keep the following in mind:
- The maxiumum length of string which can be input or output is 1023 characters.
- The formsexp string can have two sections, one for strings with one or more characters, the other for null-length strings (see here for more information)..
- Strings in Variants need to be converted into GFA strings before being passed; otherwise they will be internally converted with CDbl and treated as numeric values.
On top of the characters that can be used for all variable types, the following characters are only used when expression is a string.
| & | Character placeholder. A character of the string to be formatted is processed; if the string length is exceeded, no character is output unless a filler character has been defined with * when this is output instead.
Debug Format("GFA", "&&&&&&") & "*" // Returns "GFA*"
Debug Format("GFA", "&&&&&&*-") & "*" // Returns "GFA---*"
|
| @ | Character placeholder. Outputs either a character from the input string or, if the length of the string has been exceeded, a space is output instead - not the specified filler character, if any.
Debug Format("GFA", "@@@@@@") & "*" // Returns "GFA *"
Debug Format("GFA", "&&&&@@") & "*" // Returns "GFA *"
Debug Format("GFA", "&&&&@@*-") & "*" // Returns "GFA- *" - NOTE: Filler characters are only used with the & placeholder
|
| < or > | Force lowercase/uppercase. If these symbols are used, < forces all characters in the string into lowercase and > into uppercase (exactly like Lower and Upper). Only one symbol (< or >) can be used in any formatting statement and relates to the whole line; if more than one is used then Format uses only the last one. In addition, using one of these symbols negates all other formatting symbols and returns the whole input string in the case specified.
Debug Format("GFÄ", "@@@@@@") & "*" // Returns "GFÄ *"
Debug Format("GFÄ", "@@@@@@<") & "*" // Returns "gfä*" - NOTE: Format ignores the @ formatting symbols
Debug Lower("GFÄ"), LCase("GFÄ") // Returns "gfä" and "gfÄ" - NOTE: Works like Lower but not LCase.
|
| ! | Force right alignment of string value. By default, the value is left aligned when being assigned to placeholders; by including this symbol in formsexp, Format is forced to right align the string, including any filler characters. NOTE: If the number of characters in the input string expression exceed the number of placeholder characrters, this symbol is ignored
Debug Format("GFÄ", "@@@@@@!") // Returns " GFÄ"
Debug Format("GFÄ", "!&&&&&") // Returns "GFÄ" - NOTE: The ! character can be anywhere in the formatting string
Debug Format("GFÄ", "&&&!&*-&") // Returns "--GFÄ" - NOTE: The filler character can be anywhere in the formatting string
Debug Format("GFÄ", "&&!") // Returns "GF" - The ! is ignored as there are more input characters than placeholders
|
User-defined Number (& Variant) Formatting
Show
The follwoing needs to be kept in mind when formatting numeric and/or Variant values using Format:
- The string passed as formsexp can have up to three sections (see here for more information).
- If the number of digits before a decimal point (if any) exceeds the number of placeholders to the left of the decimal point in the relevant section of formsexp then the excess digits are not lost but added on to the beginning of the output value; this also refers to the minus sign (-) if the value is negative.
- if the number of digits following a decimal point exceed the number of placeholders to the right of the decimal point in formsexp, then the fraction is rounded to the relevant number of placeholders.
- Variants are always treated as numbers by the Format function and are internally converted using CDbl before being processed.
The following characters can be used to format numerical expressions, along with those used for all variable types listed above:
| 0 | Digit Placeholder. The 0 is a placeholder for a digit of the number to be formatted; if the number of placeholders exceeds the number of digits in the input number (expression) then those placeholders not filled are returned as 0 (not the predefined filler character, if any).
Debug Format(1244.55, "00000.000") // Returns 01244.550
Debug Format(1244.55, "000.000") // Returns 1244.550 - NOTE: The whole integer is returned, not just the last three digits
Debug Format(1244.55, "00000.0") // Returns 01244.6 - NOTE: The fraction is rounded to the number of placeholders after the d.p.
|
| # | Digit Placeholder. Similar to 0 above, the hash is a placeholder for a digit of the number to be formatted. The difference to 0 is that with a 0, leading zeros or following zeros after the decimal point are also output, while with # either the pre-defined filler character or, if no filler, then nothing (technically a Null string) is output.
Debug Format$(3.14, "###.###") // Returns 3.14
Debug Format$(3.14, "###.##0") // Returns 3.140
Debug Format$(3.14, "#00.00#*_") // Returns _03.14_ - NOTE: The second placeholder (0) is returned as 0, not as "_"
Debug Format(0.14, "###.###") // Returns .14
Debug Format(0.14, "##0.##0") // Returns 0.140
|
| . | The decimal placeholder. The position of the decimal placeholder determines how many digits appear before and after the decimal place. The decimal placeholder must always be a '.' (period or full stop) in formsexp but will be output according to either regional settings or changes made by Mode Format and/or Mode Lang.. |
| , | The comma has two functions in the formatting of numbers:
The thousands separator. If followed by either the 0 or # placeholder, the comma serves as a thousands separator; as with the decimal placeholder, it must always be represented as a comma (,) in formsexp but will be output according to either regional settings or changes made by Mode Format and/or Mode Lang.
Mode Format ".," // Set to US/UK format
Debug Format(2441.55, "#,##0.00") // Returns 2,441.55
Mode Format ",." // Set to GERMAN format
Debug Format(2441.55, "#,##0.00") // Returns 2.441,55
Mode Lang "FRA" // Set to FRENCH format
Debug Format(2441.55, "#,##0.00") // Returns 2 441,55
Divide by one thousand. If the comma (or group of commas) is not followed by a 0 or # placeholder then it functions as an instruction to Format to divide the number passed in expression by 1,000 for each such comma found.
Debug Format(2E+8, "#,###,###") // Returns 200,000,000
Debug Format(2E+8, "#,###,###,") // Returns 200,000 (2E+8/1,000)
Debug Format(2E+8, "#,###,###,,") // Returns 200 (2E+8/(1,000 * 2))
Debug Format(2E+8, "#,###,###,,,") // Returns 0 (2E+8/(1,000 * 3)) rounded to 0 d.p.
Known Issue: If the comma is placed anywhere after a decimal point marker, a Bad Format error is raised. Hence 'divide by a thousand' commas can not be used with a decimal output.
|
| % | Percent placeholder and indicator. A percent sign causes the number being formatted to be multiplied by 100 and the output value will include the % sign; the % symbol should always be placed at the end of formsexp.
Known Issue: The value is multipled by 100 for every percentage sign added to the formatting string; if you wish to use a second sign, add it in inverted commas ("%") to get around this issue.
Debug Format(10 / 14, "0%") // Returns 71% - NOTE: The integer is not truncated despite being longer than the placeholder
Debug Format(1 / 8, "#0.00##%") // Returns 12.50%
Debug Format(1 / 8, "%#0.00##") // Returns %12.50 - NOTE: Care should be taken with the placement of the % sign
|
| E+ e+ E- e- | Scientific format. If the format expression contains at least one digit placeholder (0 or #) to the right of E-, E+, e-, or e+, the number is displayed in scientific format and E or e is inserted between the number and its exponent. The number of digit placeholders 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 E+ or e+ to place a minus sign next to negative exponents and a plus sign next to positive exponents.
Known Issue 1: The documentation claims that, if the digits in the exponent exceed the number of digit placeholders, then the output is extended to include all necessary extra digits - however, this does not happen
Known Issue 2: If formsexp is formatted as E- and the value passed in expression is greater than 1, then the E- should be changed to E+ but is not; the exponent value is correct but the + sign is missing. However, if the format is entered as E+ then this is correctly changed to E- if the passed value is less than one, so it is probably best to always use E+.
Debug Format(10000, "#E+00") // Returns 1E+04
Debug Format(10000, "#E-00") // Returns 1E04 - NOTE: The exponent is not changed to a + sign as it should be
Debug Format(Large 10000000000, "#E+0") // Returns 1E+0 - NOTE: Despite the documentation, the exponent is not expanded if not big enough
Debug Format(0.44, "#E+00") // Returns 4E-01 - NOTE: In this instance, the exponent sign is changed correctly.
Debug Format(0.44, "#E-00") // Returns 4E-01
Debug Format(0.44, "#e-00") // Returns 4e-01
Known Issue 3: If E+/- is entered before number formats, all formatted values are rturned incorrectly; this is related to Known Issue 4.
Trace Format(2000, "E+## 0.0##") // Returns E+00 0.004
Known Issue 4: When using E+/-, any 0 and # characters after the initial exponent block are counted as part of the exponent structure.
Trace Format(2000, "0.0## E+## 00") // Returns 2.0 E+00 03
Known Issue 5: When formatting, # characters are treated as 0 in both the mantissa (before the decimal point) and the exponent.
Trace Format(2000, "##0.0## E+##0") // Returns 200.0 E+001
|
|
Predefined Number (& Variant) Formatting
Show
As well as the ability to format numerical values using user-defined formatting strings, there are a number of built in pre-defined named number formats which can be used as well. These can be entered with or without spaces and in any case. NOTE: Unlike using custom formatting, numbers formatted using the pre-defined names can only have one section in formsexp,
The pre-defined named number formats are:
| General Number |
Displays number with no thousand separator. Debug Format(1204.553, "General Number"), Format(-1204.553, "GeneralNumber"), Format(0, "generalnumber") // Returns 1204.553 -1204.553 0
|
| Currency |
Displays number with thousand separator, if appropriate; displays two digits to the right of the decimal separator. Output is based on system settings and can only be adjusted using Mode Lang. Debug Format(1204.553, "Currency"), Format(-1204.553, "currency"), Format(0, "Currency") // Returns £1,204.55 -£1,204.55 £0.00
|
| Fixed |
Displays at least one digit to the left and two digits to the right of the decimal separator. Debug Format(1204.553, "Fixed"), Format(-1204.553, "fixed"), Format(0, "fixed") // Returns 1204.55 -1204.55 0.00
|
| Standard |
Displays number with thousand separator, at least one digit to the left and two digits to the right of the decimal separator. Output is based on system settings and can only be adjusted using Mode Lang. Debug Format(1204.553, "Standard"), Format(-1204.553, "standard"), Format(0, "Standard") // Returns 1,204.55 -1,204.55 0.00
|
| Percent |
Displays number multiplied by 100 with a percent sign (%) appended to the right; always displays two digits to the right of the decimal separator. Debug Format(.25, "Percent"), Format(-1.45, "percent"), Format(0, "Percent") // Returns 25.00% -145.00% 000.00%
|
| Scientific |
Use standard scientific notation. Debug Format(12442, "Scientific"), Format(.0034, "scientific") // Returns 1.2442E+04 3.40E-03 NOTE: Format (0,"Scientific") causes an error in the IDE. To get round this, use a variable, as in the example below: Local a% = 0 : Debug Format(a%, "Scientific") // Returns 0.00E+00
|
| Yes/No |
Displays No if number is 0; otherwise, displays Yes. Debug Format(12442, "Yes/No"), Format(-12442, "yes/no"), Format(0, "Yes/no") // Returns Yes Yes No
|
| True/False |
Displays False if number is 0; otherwise, displays True Debug Format(12442, "True/False"), Format(-12442, "true/False"), Format(0, "True/False") // Returns True True False
|
| On/Off |
Displays Off if number is 0; otherwise, displays On. Debug Format(12442, "On/Off"), Format(-12442, "On/off"), Format(0, "on/off") // Returns On On Off |
User-defined Date and Time Formatting
Show
Before using Format to create user-defined dates, it is important to note:
- Unlike some other formatting characters, these are case specific.
- Date/Time values can be entered as literals (e.g. #01/01/2023#) or integers (date only - days from 30th December 1899 - see CDate) or decimals (values greater or equal to 1 representing date and time; values less than 1 representing time only). For more information, see Date And Time.
- Mode Date has no effect on the output of the Format function; use Mode Format instead.
The following characters can be used to format Date/Time statements, along with the universal symbols listed above. NOTE: All example texts were created on a computer with UK settings; if your computer is set up for a different country, the output may be different
General
| : | Time separator. In some locales, other characters may be used to represent the time separator. The time separator separates hours, minutes, and seconds when time values are formatted. The actual character used as the time separator in formatted output is determined by Mode Format, Mode Lang or your system settings. |
| / | Date separator. In some locales, other characters may be used to represent the date separator. The date separator separates the day, month, and year when date values are formatted. The actual character used as the date separator in formatted output is determined by Mode Format, Mode Lang or your system settings. |
| c | Displays the date as ddddd and displays the time as ttttt, in that order. Displays only date information if there is no fractional part to the date serial number; displays only time information if there is no integer portion. NOTE: (1) This uses the system settings to determine date, time and seperator format; these ignore changes made by Mode Format but can be altered using Mode Lang; (2) Using the c character is the same as using the "General Date" predefined name (see below) or Format(Date).
Mode Format ",..:" // Change to different settings using Mode Format
Debug Format(44888.5021587616, "dd/mm/yyyy hh:nn:ss") // Returns 23:11:2022 12.03.07
Debug Format(44888.5021587616, "c") // Ignores changes made by Mode Format and returns in your native format; for UK, 23/11/2022 12:03:07
Mode Lang "DEU" // Change to German system settings using Mode Lang
Debug Format(44888.5021587616, "c") // Affected by the changes made with Mode Lang and returns 23.11.2022 12:03:07
Debug Format(44888.5021587616, "General Date") // As with "c" and return 23.11.2022 12:03:07
Debug Format(CDate(44888.5021587616)) // As with "c" and return 23.11.2022 12:03:07 (Note: the number needs to be converted to a Date first)
|
Date Specific
| d, dd | Displays the day as a number either without (using d) or with (using dd) a leading zero.
Debug Format(44927, "d/m/yy") : Debug Format(44927, "dd/mm/yyyy") // Returns 1/1/23 and 01/01/2023
|
| ddd, dddd | Displays the day as a name, either as an abbreviation (using ddd) or in full (using dddd).
Debug Format(44927, "ddd") : Debug Format(44927, "dddd") // Returns Sun and Sunday
|
| ddddd | Displays the date as a complete date (including day, month, and year), formatted according to your system's short date format setting which can only be altered using Mode Lang.
Debug Format(44888, "ddddd") // Returns 23/11/22
|
| dddddd | Displays a date serial number as a complete date (including day, month, and year) formatted according to the long date setting recognized by your system which can only be altered using Mode Lang.
Debug Format(44888, "dddddd") // Returns 23 November 2022
|
| w | Displays the day of the week as a number (1 for Sunday through 7 for Saturday).
Debug Format(#23.11.2022#, "w") // Returns 4 (Wednesday)
|
| ww | Displays the week of the year as a number (1 - 53).
Debug Format(#23.11.2022#, "ww") // Returns 47 (th week of the year)
|
| m, mm | Displays the month as a number without (using m) or with (using mm) a leading zero. If either immediately follows h or hh, the minutes rather than the month is displayed. For month only, M and MM can also be used.
Debug Format(44927, "d/m/yy") : Debug Format(44927, "d/M/yy") // Both return 1/1/23
Debug Format(44927, "dd/mm/yy") : Debug Format(44927, "dd/MM/yy") // Both return 01/01/23
|
| mmm, mmmm | Displays the name of the month either as an abbreviation (using mmm) or in full (using mmmm); you can also use MMM and MMMM.
Debug Format(#23.11.2022#, "mmm") : Debug Format(#23.11.2022#, "MMM") // Both return Nov
Debug Format(#23.11.2022#, "mmmm") : Debug Format(#23.11.2022#, "MMMM") // Both return November
|
| q | Displays the quarter of the year as a number (1 - 4).
Debug Format(#23.11.2022#, "q") // Returns 4 (th quarter)
|
| y | Displays the day of the year as a number (1 - 366).
Debug Format(#23.11.2022#, "y") // Returns 327 (days since start of year)
|
| yy, yyyy | Displays the year as either a 2 (00 to 99 using yy) or a 4-digit number (100 - 9999 using yyyy).
Debug Format(44927, "d/m/yy") : Debug Format(44927, "dd/mm/yyyy") // Returns 1/1/23 and 01/01/2023
|
Time Specific
| h, H, hh, HH | Displays the hours as a number without (using h or H) or with (using hh or HH) a leading zero.
Debug Format(.25075, "h:m:s"), Format(.25075, "H:n:s") // Both return 6:1:5
Debug Format(.25075, "hh:mm:ss"), Format(.25075, "HH:nn:ss") // Both return 06:01:05
|
| n, nn | Displays the minutes as a number without (using n) or with (usinf nn) a leading zero. The characters m and mm can also be used, as long as they immediately follow h, hh, H or HH.
Debug Format(.25075, "h:m:s"), Format(.25075, "H:n:s") // Both return 6:1:5
Debug Format(.25075, "hh:mm:ss"), Format(.25075, "HH:nn:ss") // Both return 06:01:05
|
| s, ss | Displays the seconds as a number without (using s) or with (using ss) a leading zero.
Debug Format(.25075, "h:m:s"), Format(.25075, "hh:mm:ss") // Return 6:1:5 and 06:01:05
|
| ttttt | Displays a time as a complete time (including hour, minute, and second), formatted using the time separator defined by the time format recognized by your system or Mode Lang. Whether a leading zero is displayed depends upon settings which are not changeable in GFA-BASIC.
Debug Format(.25075, "ttttt") // Returns 06:01:05
|
| am/pm, AM/PM | Uses the 12-hour clock and displays either an upper or lower case AM with any hour before noon, or an upper or lower case PM with any hour between noon and 11:59 P.M. These formatting characters are not Locale dependent, so will returm am/pm regardless of the Mode Lang setting.
Debug Format(.25075, "hh:mm:ssam/pm"), Format(.25075, "hh:mm:ss AM/PM") // Returns 06:01:05am and 06:01:05 AM
Debug Format(.75075, "hh:mm:ss am/pm"), Format(.75075, "hh:mm:ssAM/PM") // Returns 06:01:05 pm and 06:01:05PM
|
| a/p, A/P | Uses the 12-hour clock and displays either an upper or lower case A with any hour before noon, or an upper or lower case P with any hour between noon and 11:59 P.M. These formatting characters, like am/pm, are not Locale dependent, so will returm a/p regardless of the Mode Lang setting
Debug Format(.25075, "hh:mm:ss a/p"), Format(.25075, "hh:nn:ss A/P") // Returns 06:01:05 a and 06:01:05 A
Debug Format(.75075, "hh:nn:ss a/p"), Format(.75075, "hh:mm:ss A/P") // Returns 06:01:05 p and 06:01:05 P
|
| ampm, AMPM | Uses the 12-hour clock and displays the AM string literal as defined by your system with any hour before noon or the PM string literal as defined by your system with any hour between noon and 11:59 P.M. The characters can be either uppercase or lowercase, but the case of the string displayed matches the string as defined by your Locale settings - the value in Mode(Lang).
Debug Format(.25075, "hh:mm:ss ampm"), Format(.25075, "hh:nn:ss AMPM") // Both return 06:01:05 AM
|
Predefined Date/Time Formatting
Show
The following are predefined format names for Dates and Times; in all cases, the names can be entered in any case with spaces included or omitted and the resulting formats are based on you system settings and can be changed using Mode Lang, but not Mode Format. (NOTE: The examples were created using UK settings so may appear differently than described if run on a conmputer with different language settings.)
| General Date | Displays a date and/or time. For real numbers, both date and time are displayed; if there is no fractional part, only a date; and if there is no integer part, only a time. This is the same as using the "c" character (see above) or simply using Format(Date).
Local a As Date = #24.11.2022 11:48:55#
Debug Format(a, "General Date") // Returns 24/11/2022 11:48:55
Debug Format(Int(a), "General Date") // Returns 24/11/2022 (only an integer was passed)
Debug Format(Frac(a), "General Date") // Returns 11:48:55 (only the fraction was passed)
Debug Format(a, "c") // Returns 24/11/2022 11:48:55
Debug Format(a) // Returns 24/11/2022 11:48:55
|
| Long Date | Displays a date according to your system's long date format.
Debug Format(#24.11.2022 13:06:04#, "Long Date") // Returns 24 November 2022
|
| Medium Date | Displays a date using the medium date format appropriate for the language version of the host application. This does not work correctly as it inserts date seperators when there should be none.
Debug Format(#24.11.2022 13:06:04#, "MediumDate") // Returns 24/Nov/2022 (should be 24 Nov 2022)
|
| Short Date | Displays a date using your system's short date format.
Debug Format(#24.11.2022 13:06:04#, "Short Date") // Returns 24/11/2022
|
| Long Time | Displays a time using your system's long time format; includes hours, minutes, seconds.
Debug Format(#24.11.2022 13:06:04#, "long time") // Returns 13:06:04
|
| Medium Time | Is meant to display time in 12-hour format using hours and minutes and the AM/PM designator, but actually outputs the same as Short Time.
Debug Format(#24.11.2022 13:06:04#, "Medium Time") // Returns 13:06 (should be 01:06PM)
|
| Short Time | Displays a time using the 24-hour format.
Debug Format(#24.11.2022 13:06:04#, "Short Time") // Returns 13:06
|
The Format function is quite versatile and the value passed can be split into sections or used repeatedly to produce different values, as in the following examples:
Debug Format(#10/15/2023#, "dddddd 'is a' dddd 'in week 'ww' of the year.'") // Prints "15 October 2023 is a Sunday in week 41 of the year."
Debug Format(12306344, "#0' million, '000' thousand, '0' hundred and '00'.'") // Prints "12 million, 306 thousand, 3 hundred and 44."
Debug Format("GFABasic", "'The first three letters of the word are '&&&' and the rest are '&&&&&'.'") // Print "The first three letters of the word are GFA and the rest are Basic."
Example
Use the following example to see how the formatting appears on your system:
Debug Format(12.345, "$#,##0.00")
Debug Format(44576, "dd/mm/yyyy hh:nn:ss")
Debug Format(12.345, "General Number")
Debug Format(12.345, "Currency")
Debug Format(12.345, "Fixed")
Debug Format(12.345, "Standard")
Debug Format(12.345, "Percent")
Debug Format(12.345, "Scientific")
Debug Format(12.345, "General Date")
Debug Format(12.345, "Long Date")
Debug Format(12.345, "Medium Date")
Debug Format(12.345, "Short Date")
Debug Format(12.345, "Long Time")
Debug Format(12.345, "Medium Time")
Debug Format(12.345, "Short Time")
Remarks
See Also
Using
{Created by Sjouke Hamstra; Last updated: 18/10/2023 by James Gaite; Other Contributors: Jean-Marie Melanson}