  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
A major part of this chapter covers a large group of functions dealing with strings, including output, parsing, and other fundamental functionalities.
A string is a series of characters normally terminated by a zero byte (/0 or 0x00). The characters can be virtually anything but typically represent text or some type of coded text. For example:
“My name is Bob”
is represented as a series (or string) of coded characters:
M y n a m e i s B o b
4D 79 20 6E 61 6D 65 20 69 73 20 42 6F 62 00
Each of the characters is represented by an ASCII code, and the string is ended with a zero-byte or terminator. This is conventional for most languages and is produced and is expected by most Legato functions unless otherwise specified. Any string data placed after the zero-byte will generally be ignored.
Since Legato supports an application that is largely designed to process text and tables, it is only natural that we start with strings. Strings are either a series of 8-bit or 16-bit characters. What you are reading is text within a paragraph which is represented by a series of characters that are then grouped and said to be in a string. For most languages, strings are what is typically known a “zero-terminated”. This means the end of series of characters is denoted by a zero byte (0x00 or simple code 0). Strings can also be constrained by a size, but this is not the norm. Unless otherwise noted, all strings are assumed to be zero-terminated. See Section 3.5 Strings Versus Characters for more details on strings and characters.
Typically strings employ 8-bit characters for ASCII, ISO-8851 and ANSI sets. Unicode requires 16-bit or ‘wide’ strings.
Note: Unicode support is very limited in Version 1.1 of Legato.
Most languages provide a method to format data into presentable string arrangements for human or computer consumption, and Legato is no exception. Formatted strings can be employed as part of a number of functions, including the FormatString, AddMessage , and MessageBox functions. For example, the following code:
MessageBox("%d items processed, %d errors", items, errors);
will yield something like this (depending on the values of items and errors):
Functions employing formatted strings will automatically convert both the variable type and formatting of the string content. For example, if a string is requested to be inserted and a floating-point number is provided as a parameter, the floating-point number will be converted to a string with formatting as specified and then inserted.
Formatted strings contain effectively two types of data: inert characters that are passed through and control segments that are replaced with formatted content. The source string is directly copied to the result until a ‘%’ character is encountered, at which point the conversion process replaces the content. Inert or ordinary characters are like any other string literal within the language. When a ‘%’ character is desired in the output, add ‘%%’ which will be replaced by a single character.
The control segments start with the ‘%’ character and end with a specific format character (detailed in the next section). C/C++ programmers will recognize this coding style since the underlying formatting function uses the C++ libraries. In between, optional formatting information can be added. For example:
| %d | converts a numeric parameter (or converted string) to a string character representation of that number. |
| %3d | converts the integer but will pad up to two spaces leading the number. |
| %03d | pads with leading zeros. |
The basic format is:
% flags size type
Where:
Flags — One or more characters, in any order, which modify the control segment:
| - | Specifies a left adjustment to the converted segment. |
| + | Specifies that the number will always be converted with a +/- sign (does not apply to strings, accounting or hex). |
| 0 | Specifies to fill with zeros rather than spaces. |
| # | Specifies an alternative output form. For ‘o’ (octal), the first digit will always be zero. For ‘x’ or ‘X’ (hex), a leading prefix is added as 0x. For floating-point (‘e’ ,’E’, ‘f’, ‘g’ and ‘G’), the output will always have a decimal point; for ‘g’ and ‘G’, trailing zeros will not be deleted. |
Size — A number specifying a minimum field width. The converted segment will be created to be at least this wide and wider if required. If the resulting field contains less characters, it will be padded left or right as necessary to fill the size requirement. The padding character is normally a space but can optionally be a zero if the size is specified with a leading 0.
A period character within size separates the integer size from the precision for floating-point format. For example, %2.1f will always have a trailing .1 precision. See type next for more information.
Type — A character dictating the type of formatting to be applied. The following types are permitted:
| d | Signed decimal integer (“0, 5, -1” for compatibility with C). |
| i | Signed decimal integer (“0, 5, -1”). |
| o | Octal (“1”). |
| x | Hexadecimal lower (“1a0e”). |
| X | Hexadecimal upper (“1A0E”). |
| u | Unsigned decimal integer (“1”). |
| c | Character (“a”). |
| s | String (“hello”). String fields may have one component for formatting: %ns or %-ns Where n is the overall field size in characters. By default, the field is right aligned in the character padding area. Adding a leading dash will left align the data. |
| f | Float (“1.2”). Note that the default precision for floating point values is 6 digits. To achieve a higher level of translation of precision, use explicit numeric format values. For example, ‘%1.10f”. |
| e | Scientific lower (“1.2e+3”). |
| E | Scientific upper (“1.2E+3”). |
| g | Use the shortest representation: %e or %f (“123.45”). |
| G | Use the shortest representation: %E or %F (“123.45”). |
| a | Accounting (“12,345”). If the number is negative, the value is placed inside of parenthesis, for example, -12345 becomes “(12,345)”. For padded fields such as “%15a”, the last character is reserved as either a space or close parenthesis for alignment purposes. The provides for easy alignment of text fields. Accounting fields may have one component for formatting of integer values: %na or %-na Where n is the overall field size in characters. By default, the field is right aligned in the character padding area. Adding a leading dash will left align the data. For float values, the accounting field as an additional component: %n.pa or %-n.pa Where n is as described above and p is the number of decimal places. If p is omitted, the default value is 2. |
| A | Accounting (“12,345”). If the number is negative, a dash is placed in front of the value, for example, -12345 becomes “-12,345”. For padded fields such as “%15a”, the last character is reserved as either a space or close parenthesis for alignment purposes. The provides for easy alignment of text fields. Accounting fields may have one component for formatting of integer values: %na or %-na Where n is the overall field size in characters. By default, the field is right aligned in the character padding area. Adding a leading dash will left align the data. For float values, the accounting field as an additional component: %n.pa or %-n.pa Where n is as described above and p is the number of decimal places. If p is omitted, the default value is 2. |
The number of control segments must match the number of provided parameters.
5.2.3 String and String Related Functions
The following sections cover basic strings:
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.