This repository was archived by the owner on Aug 31, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 226
Expand file tree
/
Copy pathformat.lcdoc
More file actions
175 lines (145 loc) · 7.31 KB
/
format.lcdoc
File metadata and controls
175 lines (145 loc) · 7.31 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
Name: format
Type: function
Syntax: format(<baseString> [, <valuesList>])
Summary:
Returns a <format|formatted> <string> that has been transformed
according to the rules of the C "printf()" <function>.
Introduced: 1.0
OS: mac, windows, linux, ios, android
Platforms: desktop, server, mobile
Example:
format("Hello world")
Example:
format("Hello\nworld")
Example:
format("%1.3e",865.3)
Example:
format("%45d",5)
Parameters:
baseString (string):
A string that can include one or more special formatting incantations.
valuesList:
A list of strings (or expressions that evaluate to strings), separated
by commas. The <valuesList> contains as many values as there are
incantations in the <baseString>.
Returns:
The <format> function returns a <string>.
Description:
Use the <format> <function> to create <string(glossary)|strings> in
special <format|formats>.
The <format> <function> works by taking a <baseString> that contains
<format|formatting> incantations, transforming each member of the
<valuesList> according to the corresponding incantation, then
substituting the transformed <string(keyword)> for the incantation in
the <baseString>. It also transforms C escape sequences in the
<baseString> into their single- <character> equivalents.
The valid incantations are as follows:
String:
- %[charLength]s - The corresponding value is unchanged, except that
if a charLength is specified, if the <string(keyword)> is shorter than
the charLength, enough leading spaces are added to make it charLength
<characters> long. If the length of the <string(keyword)> is equal to or
greater than the charLength, it is unchanged. For example, the
incantation %3s transforms "H" to " H".
Character:
- %[charLength]c - The corresponding value is treated as an ASCII value
and translated to the corresponding character. If a charLength is specified,
one fewer leading spaces are added to make it charLength characters long.
For example, the incantation %2c transforms 65 to " A" (65 is the ASCII
value of the <character> "A").
Decimal number:
- %[charLength]d - The corresponding value is rounded to the nearest integer:
if the fractional part is .5 or more, the value is rounded up, and otherwise
it is rounded down. (If the value is negative, if the fractional part is
.5, the value is rounded down.) If a charLength is specified, if the
length of the resulting number is less than the charLength, enough
leading spaces are added to make it charLength <characters> long. If the
length of the resulting number is equal to or greater than the
charLength, it is unchanged. For example, the incantation %2d transforms
"2.3" to " 2".
Unsigned integer:
- %[charLength]u - Like %[charLength]d, except that if the value is
negative, it is subtracted from the largest long integer allowed by the
current operating system. (On most operating systems, this is 2^32, or
4,294,967,296.)
Octal:
- %[charLength]o - The corresponding value is assumed to be a decimal
number, rounded to the nearest integer, then converted to an octal
number. If a charLength is specified, if the length of the resulting
number is less than the charLength, enough leading spaces are added to
make it charLength <characters> long. If the length of the resulting
number is equal to or greater than the charLength, it is unchanged. For
example, the incantation %3o transforms "10.7" to " 13".
Hexadecimal:
- %[charLength]x - The corresponding value is assumed to be a decimal
number, rounded to the nearest integer, then converted to a hexadecimal
number. If a charLength is specified, if the length of the resulting
number is less than the charLength, enough leading spaces are added to
make it charLength <characters> long. If the length of the resulting
number is equal to or greater than the charLength, it is unchanged.
For example, the incantation %4x transforms "30.3" to " 1e".
- %[charLength]X - Like %[charLength]x, except that the hex digits A-F
are given in uppercase. For example, the incantation %4x transforms
"30.3" to " 1E".
Floating-point:
- %[charLength].[precision]f - The corresponding value is a real number.
If a precision is specified, if the number of digits after the
<decimal point> is greater than the precision, the number is rounded to
the specified number of digits after the <decimal point>. If the number
of digits is less than the precision, enough trailing zeroes are added
to make precision digits. If no precision is specified, the
number is formatted to six decimal places. If a charLength is specified,
if the total length of the resulting number is less than the charLength,
enough leading spaces are added to make it charLength <characters> long;
if the length of the resulting number is equal to or greater than the
charLength, it is unchanged.
- %[charLength. precision]g - Like %[charLength].[precision]f, except
that trailing zeroes are not added if the number of digits is less than
the precision.
Scientific notation:
- %[charLength].[precision]e - The corresponding value is a real number.
First the number is transformed to scientific notation: expressed as a
number between 1 and 10 (or -10 and 1), multiplied by the appropropriate
power of 10. If a precision is specified, if the number of digits after
the <decimal point> is greater than the precision, the number is rounded
to the specified number of digits after the <decimal point>. If the
number of digits is less than the precision, enough trailing zeroes are
added to make precision digits. If no precision is specified, the number
is given to six digits after the <decimal point>. If a charLength is
specified, if the total length of the resulting number is less than the
charLength, enough leading spaces are added to make it charLength
<characters> long; if the length of the resulting number is equal to or
greater than the charLength, it is unchanged. For example, the
incantation %3.2e transforms "232.4" to "2. 32e+02".
- %[charLength.precision]E - Like %[charLength. precision]e, except that
the "E" separating the number from the power of ten is uppercase. For
example, the incantation %3.2e transforms "232.4" to "2.32E+02".
If a zero is included immediately before the charLength parameter in any formatting
incantation that allows padding, the resulting value is padded (if
necessary) with zeroes instead of spaces. For example, the incantation
%03s transforms H to 00H.
If any of the following C escape sequences are present in the
<baseString>, the <format> function transforms them to the equivalent
character:
- \a Control-G (bell)
- \b Control-H (backspace)
- \f Control-L (formfeed)
- \n Control-J (linefeed)
- \r Control-M (return)
- \t Control-I (tab)
- \v Control-K (vertical tab)
- \\\ \\
- \?? ?
- \' '
- \" " (enclose a quote within a <string(keyword)>)
- \nnn character whose ASCII value is the octal number represented by nnn
- \xnn character whose ASCII value is the hex number represented by nn
> *Note:* Transformation of values in <valuesList> uses the standard
> LiveCode conversion rules. For example, if empty is passed for a numeric
> incantation it will be taken as the value 0.
References: function (control structure), binaryEncode (function),
charToNum (function), baseConvert (function), numToChar (function),
format (glossary), string (glossary), decimal point (glossary),
string (keyword), character (keyword), characters (keyword),
HTMLText (property), numberFormat (property)
Tags: text processing