Formats an expression according to instructions contained in a format expression.
$ = Using[$](format$, a [,b [,c ...]])
| format$ | : sex |
| a, b ,c | : aexp or sexp |
Using is the third function available to format an expression given a format-template after Format() and sprintf(). In older versions of GFA-BASIC, Using was exclusively reserved for Print; however, in GFA-BASIC 32 Using is a separate function and can be used to create a string, to output to a debug window as well as being used with the Print expression as in the old days. Of greater use in modern programming, it can also be used to format a list of strings which can then be used by the Split command to populate a Hash String as shown below:
Mode Using ",."
Local hs As Hash String, s As String
Local a$ = Using("##.##", 2.3, 3, 6.7, 3.45)
Split hs[] = a$, " "
For Each s In hs[]
Debug Each ` s
Next
Debug.Show
Using is very basic compared to Format and sprintf and is best suited to fixed-width fonts for which it was originally designed; there are also numerous bugs and oddities in its execution, so care should be taken when including it in a program.
A very important thing to note before employing the Using function with a numeric variable with decimal and/or thousand separators is that those separators are specified by the Mode(Using) function and set using the Mode Using command, not Mode Format or Mode Lang, neither of which affect the value of Mode(Using) when changed. In addition, when the program is executed, Mode Using is NOT updated to the programmer's locale but set to that of Germany where the decimal separator is a comma (,) and the thousand separator a period or full stop (.). Hence, you may need to reset the values in Mode(Using) to suit the locale in which you are working before using this function - a simple way to do this is to copy over the first two characters of Mode(Format) (which stores them backwards) as follows:
Mode Using Mid(Mode(Format), 2, 1) & Left(Mode(Format))
Using can be employed to output a string based on one or more variables which must all be either numerical or text; if one or more numeric values are passed (or Null or Empty - any other non numeric variable returns an error), the output string will be formatted using one specific set of placeholders and characters in format$; if one or more strings, then another. In both cases, only the relevant placeholders and characters are converted, all other characters in format$, including the placeholders and characters used for the other variable type, being treated as plain text. There is only one exception to this rule and that it the _ format character which can be used with either a string or numeric variable. NOTE: If no relevant placeholders or formatting characters are included in format$, then a Bad Format error is returned.
Another thing to note about Using is that for all variable types, the conversion of value into formatted output starts at the first formatting character or placeholder encountered in format$ (the ^ exponent placeholder being the exception - see below) and ending when the next non-formatting character is processed; all subsequent placeholders and formatting characters are treated as plain text, as can be seen below.
Mode Using ",."
Debug Using("##.## ###", 22.5) // Outputs 22.50 ###
This can cause some very odd errors if numeric placeholders are incorrectly positioned or entered as plain text before and isolated from the digit placeholders: in all cases (except the ^ exponent placeholder), the integer of the passed value is output before the misplaced placeholder (or around it if $ is used) and the fractional part of the value, if any, is lost. Some examples are shown below:
Mode Using ",."
Debug Using("$ ###.##", 24.45) // Output 2$4 ###.##
Debug Using("+ ###.##", -24.45) // Output 24- ###.##
Debug Using(". ###.##", 24.45) // Output 24. ###.##
The only universal formatting character is:
| _ | An underline performs the output of the next character in template as a literal. Debug Using("##_ _t_h_o_u_s_a_n_d_ ###", 1589) // Outputs 1 thousand 589 |
The following characters allow the formatting of a passed numerical value. The sections below detail how to use them and any oddities of which you need to be aware and there is further information above in the first paragraphs of the Description abovel.
The Decimal and Thousand Separators
There are no universal placeholders for the decimal and thousand separators in the Using function as in Format; instead, the relevant symbol stored in Mode(Using) is used, which can become a little bit confusing. Hence, when the program first runs, it is set for Germany and a period or full stop (.) must be used for the thousand placeholder, but if you switch to UK/US numerical style, a comma (,) must be used, to French, a space (" ") and so on, as shown below :
Mode Using ".," // Set to German format
Debug Using("#.###,##", 1234.56) // ..and this outputs 1.234,56 as it should
Mode Using ",." // But set to UK format
Debug Using("#.###,##", 1234.56) // ..and this outputs as 1234.560,00
Debug Using("#,###.##", 1234.56) // ..so this line needs to be used in the UK
A simple workaround to this oddity is to do something like this:
Mode Using ".," // Set to German format
Debug Using("#" & Sep(1) & "###" & Sep(2) & "##", 1234.56) // ..and this outputs 1.234,56 as it should
Mode Using ",." // And set to UK format
Debug Using("#" & Sep(1) & "###" & Sep(2) & "##", 1234.56) // ..and this outputs 1,234.56 as it should
Debug.Show
Function Sep(typ As Int32)
Return Mid(Mode(Using), typ, 1) // Returns thousand (1) or decimal (2) separator
EndFunction
Digit Placeholders
All the following reserve a place in the returned string for a digit taken from the passed value.
| # | The main digit placeholder: This will be replaced by a digit from the value or, when the value is not high enough, a space (or asterisk - see * below). Debug Using("####", 35) // Outputs 35 |
| * | If one or more asterisks (*) are used as a placeholder, then ALL digit placeholders which are unfilled due to the value not being large enough are replaced by an asterisk, not a space. Debug Using("*###", 35) // Outputs **35 Debug Using("##*#", 35) // Outputs **35 Note: the asterisk can be placed anywhere in the format string |
| $ | A special placeholder which signifies that, before the first digit, a dollar sign ($) will be inserted. NOTE: The $ sign takes up a place in the string instead of a digit. Debug Using("$###", 35) // Outputs $35 Debug Using("*##$", 35) // Outputs *$35 Note: the $ sign can be placed anywhere in the format string |
If a value is passed with digits to the right of the decimal point, then, if there are more digits to the right of the decimal point in the value than placeholders, the value is rounded to fit the number of placeholders, whereas, if there are not enough, any unfilled placeholders are replaced by a zero (0).
Mode Using ",."
Debug Using("####.##", 4.555) // Outputs 4.56
Debug Using("####.##", 4.5) // Outputs 4.50
With negative numbers, the minus sign is placed before the first filled digit and after the dollar sign, if this is included (unless a sign placeholder is used to specify the exact location of the sign - see below). NOTE: The minus sign takes up a digit placeholder.
Debug Using("#####", -34) // Outputs -34
Debug Using("#$###", -34) // Outputs $-34
Always ensure that you have included enough digit placeholders to accomodate all the digits of every value you are likely to pass to the Using function as, although the function does pad out the front of the formatted value with any additional digits, they are placed before the dollar sign or any sign placeholders (described below) as can be seen here:
Debug Using("####", 100000) // Outputs 100000 - This is OK
Debug Using("+####", 100000) // Outputs 10+0000 - The excess digits are displayed before the plus sign...
Debug Using("$###", 100000) // Outputs 10$0000 - ...and the dollar sign...
Debug Using("##$#", 100000) // Outputs 10$000 - ...regardless of where it is placed in the format string.
The Sign Placeholders
There are two placeholders which allow where the position of the sign (plus and/or minus) is to be displayed to be specified:
| - | Reserves a place for a minus sign if the value passed is negative, otherwise a space is returned (never an asterisk). Debug Using("-####", 34) // Outputs 34 Debug Using("-####", -34) // Outputs - 34 Debug Using("####-", -34) // Outputs 34- |
| + | Reserves a place for either a plus or minus sign, according to whether the value passed is positive or negative. Debug Using("+####", 34) // Outputs + 34 Debug Using("+####", -34) // Outputs - 34 |
If no sign placeholder ist included, then the minus sign for any negative number is placed before the first printed digit (and after the $ sign if that is to be output as well).
These placeholders are designed to be placed exactly where they are positioned in the format string; therefore they should only be used either at the start or end of the digit placeholders, otherwise the output will be incorrect.
Debug Using("+####", -34) // Outputs -34
Debug Using("###+#", -34) // Outputs 3-4
The Exponent Placeholder
| ^ | Used to specify the position and number of characters in an exponent of the value passed. |
By adding one or more exponent placeholders, this forces Using to convert the value into a mantissa (based on digit placeholders which precede the exponent placeholder) and an exponent of the length specified by the number of exponent placeholders.
There should be enough exponent placeholders to hold the E, the exponent sign and the exponent itself; however, if there are not enough, the output is expanded automatically. Furthermore, if the number of exponent placeholders are greater than required, unused ones are filled with zero (0).
Mode Using ",."
Debug Using("#.###^^^", 2 ^ 10) // Outputs 1.204E+3
Debug Using("###.#^^^", 2 ^ 10) // Outputs 102.4E+1 - NOTE: by changing the format of the mantissa, the exponent is also changed to match.
Debug Using("###.#^^^^", 2 ^ 10) // Outputs 102.4E+01 - NOTE: the excess exponent placeholder is filled with a zero.
Debug Using("###.#^^", 2 ^ 10) // Outputs 102.4E+1 - NOTE: If not enough exponent placeholders are included, the exponent is expanded automatically.
Debug Using("#.#^^^", 102 ^ 6) // Outputs 1.1E+12 - NOTE: Again, the exponent is expanded automatically if required.
When entering exponent placeholders, they need to be contiguous (one after the other); they also need to immediately follow the other digit placeholders - if they precede them or if they come after and are separated by a non-formatting character, then they are ignored as placeholders, counted as plain text and printed accordingly. If you want to insert a space between the mantissa and exponent, use the underscore (_) formatting character as in the example below:
Mode Using ",."
Debug Using("^^#.###^^^", 2 ^ 10) // Outputs ^^1.204E+3 - The exponent placeholders are treated as plain text where they precede the first digit placeholder.
Debug Using("#.### ^^^", 2 ^ 10) // Outputs 1024.000 ^^^ - If there is a non-formatting character before the exponent, the conversion to mantissa/exponent does not take place.
Debug Using("#.###_ ^^^", 2 ^ 10) // Outputs 1.204 E+3 - Using the _ it is possible to insert a space before the exponent.
The characters available for formatting string expressions are few and simple and are listed below:
| & | Performs the output of the whole string. Debug Using("This is the whole string: &", "GFABasic") // Outputs This is the whole string: GFABasic |
| ! | Limits the output to the first character in the string. Debug Using("This is the first character: !", "GFABasic") // Outputs This is the first character: G |
| \...\ | Specifies the number of characters to be printed from a string. The count includes both \ characters and the characters between the backslashes can be anything; if the length of this string exceeds the length of the passed string expression, then spaces are added to pad it out. Debug Using("This is the first five characters: \234\", "GFABasic") // Outputs This is the first five characters: GFABa Debug Using("This shows padding for short string: \234\*", "GFA") // Outputs This shows padding for short string: GFA * |
Local a#, t#
Mode Using ",."
While _Data
Read a#
t# += a#
Debug Using("+_£##,###.##", a#)
Wend
Debug "-----------"
Debug Using("=_£##,###.##", t#)
Debug.Show
Data 24.45,145.6,-27.89,4811.44
This outputs a list of figures in the form of a calculation which looks like this:
+£ 24.45 +£ 145.60 -£ 27.89 +£ 4,811.44 ----------- =£ 4,953.60
OpenW 1
Local a%, f1$, f2$, f3$, f4$
f1$ = "#,###"
f2$ = "#,###_._._."
f3$ = "\...\"
f4$ = "###.###^^^^"
//
Print Using(f1$, PI)// prints 3.142
Print Using(f2$, PI)// prints 3.142...
Print Using(f3$, "Hallo GFA")// prints Hallo
Print Using(f4$, 2 ^ 10)// prints 1.024E+03
Str(), Print, Format, sprintf, Mode
{Created by James Gaite; Last updated: 23/10/2023 by James Gaite}