forked from livecode/livecode
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathformat.xml
More file actions
96 lines (80 loc) · 11.2 KB
/
Copy pathformat.xml
File metadata and controls
96 lines (80 loc) · 11.2 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
<doc>
<legacy_id>2362</legacy_id>
<name>format</name>
<type>function</type>
<syntax>
<example>format(<i>baseString</i>[,<i>valuesList</i>])</example>
</syntax>
<synonyms>
</synonyms>
<summary>Returns a <glossary tag="format">formatted</glossary> <keyword tag="string">string</keyword> that has been transformed according to the rules of the C "printf()" <control_st tag="function">function</control_st>. </summary>
<examples>
<example>format("Hello world") </example>
<example>format("Hello\nworld") </example>
<example><p>format("%1.3e",865.3) </p></example>
<example>format("Hello world") </example>
<example>format("%45d",5) </example>
</examples>
<history>
<introduced version="1.0">Added. </introduced>
<deprecated version=""></deprecated>
<removed version=""></removed>
</history>
<objects>
</objects>
<platforms>
<mac/>
<windows/>
<linux/>
<ios/>
<android/>
</platforms>
<classes>
<desktop/>
<server/>
<web/>
<mobile/>
</classes>
<security>
</security>
<classification>
<category>Text and Data Processing</category>
</classification>
<references>
<function tag="numToChar">numToChar Function</function>
<function tag="baseConvert">baseConvert Function</function>
<function tag="binaryEncode">binaryEncode Function</function>
<function tag="charToNum">charToNum Function</function>
<property tag="numberFormat">numberFormat Property</property>
<property tag="HTMLText">HTMLText Property</property>
</references>
<description>
<overview>Use the <b>format</b> <control_st tag="function">function</control_st> to create <glossary tag="string">strings</glossary> in special <glossary tag="format">formats</glossary>. </overview>
<parameters>
<parameter>The <i>baseString</i> is a string that can include one or more special formatting incantations.</parameter>
<parameter>The <i>valuesList</i> is a list of strings (or expressions that evaluate to strings), separated by commas. The <i>valuesList</i> contains as many values as there are incantations in the <i>baseString</i>.</parameter>
</parameters>
<value>The <b>format</b> function returns a <keyword tag="string">string</keyword>.</value>
<comments>The <b>format</b> <control_st tag="function">function</control_st> works by taking a <i>baseString</i> that contains <glossary tag="format">formatting</glossary> incantations, transforming each member of the <i>valuesList</i> according to the corresponding incantation, then substituting the transformed <keyword tag="string">string</keyword> for the incantation in the <i>baseString</i>. It also transforms C escape sequences in the <i>baseString</i> into their single-<keyword tag="character">character</keyword> equivalents. <p></p><p>The valid incantations are as follows:</p><p></p><p><code tag="">String:</code></p><p>%<code tag="">[</code><i>charLength</i>]s</p><p>The corresponding value is unchanged, except that if a <i>charLength</i> is specified, if the <keyword tag="string">string</keyword> is shorter than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long. If the length of the <keyword tag="string">string</keyword> is equal to or greater than the <i>charLength</i>, it is unchanged. For example, the incantation<code tag=""> %3s </code>transforms "<code tag="">H</code>" to "<code tag=""> H</code>". </p><p></p><p><code tag="">Character:</code></p><p>%<code tag="">[</code><i>charLength</i>]c</p><p>The corresponding value is treated as an ASCII value and translated to the corresponding character. If a <i>charLength</i> is specified, one fewer leading spaces are added to make it <i>charLength</i> characters long. For example, the incantation<code tag=""> %2c </code>transforms<code tag=""> 65 </code>to "<code tag=""> A</code>" (65 is the ASCII value of the <keyword tag="character">character</keyword> "A"). </p><p></p><p><code tag="">Decimal number:</code></p><p><code tag="">%[</code><i>charLength</i>]d</p><p>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 <i>charLength</i> is specified, if the length of the resulting number is less than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long. If the length of the resulting number is equal to or greater than the <i>charLength</i>, it is unchanged. For example, the incantation<code tag=""> %2d </code>transforms "<code tag="">2.3</code>" to "<code tag=""> </code>2". </p><p></p><p><code tag="">Unsigned integer:</code></p><p><code tag="">%[</code><i>charLength</i>]u</p><p>Like <code tag="">%[</code><i>charLength</i>]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.)</p><p></p><p><code tag="">Octal:</code></p><p><code tag="">%[charLength]o</code></p><p>The corresponding value is assumed to be a decimal number, rounded to the nearest integer, then converted to an octal number. If a <i>charLength</i> is specified, if the length of the resulting number is less than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long. If the length of the resulting number is equal to or greater than the <i>charLength</i>, it is unchanged. For example, the incantation<code tag=""> %3o </code>transforms <code tag="">"10. 7</code>" to <code tag="">" 13</code>".</p><p></p><p><code tag="">Hexadecimal:</code></p><p><code tag="">%[</code><i>charLength</i>]x</p><p>The corresponding value is assumed to be a decimal number, rounded to the nearest integer, then converted to a hexadecimal number. If a <i>charLength</i> is specified, if the length of the resulting number is less than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long. If the length of the resulting number is equal to or greater than the <i>charLength</i>, it is unchanged. For example, the incantation<code tag=""> %4x </code>transforms "<code tag="">30.3</code>" to "<code tag=""> 1e</code>". </p><p></p><p><code tag="">%[</code><i>charLength</i>]X</p><p>Like <code tag="">%[</code><i>charLength</i>]x, except that the hex digits A-F are given in uppercase. For example, the incantation<code tag=""> %4x </code>transforms "<code tag="">30. 3</code>" to "<code tag=""> 1E</code>".</p><p></p><p><code tag="">Floating-point:</code></p><p><code tag="">%[</code><i>charLength</i>]<i>.</i>[<i>precision</i>]f</p><p>The corresponding value is a real number. If a <i>precision</i> is specified, if the number of digits after the <glossary tag="decimal point">decimal point</glossary> is greater than the <i>precision</i>, the number is rounded to the specified number of digits after the <glossary tag="decimal point">decimal point</glossary>. If the number of digits is less than the <i>precision</i>, enough trailing zeroes are added to make <i>precision</i> digits. If no <i>precision</i> is specified, the number is formatted to six decimal places. If a <i>charLength</i> is specified, if the total length of the resulting number is less than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long; if the length of the resulting number is equal to or greater than the <i>charLength</i>, it is unchanged.</p><p></p><p><code tag="">%[</code><i>charLength. precision</i>]g</p><p>Like<code tag=""> %[</code><i>charLength</i>]<i>. </i>[<i>precision</i>]f, except that trailing zeroes are not added if the number of digits is less than the <i>precision</i>. </p><p></p><p><code tag="">Scientific notation:</code></p><p><code tag="">%[</code><i>charLength. precision</i>]e</p><p>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 <i>precision</i> is specified, if the number of digits after the <glossary tag="decimal point">decimal point</glossary> is greater than the <i>precision</i>, the number is rounded to the specified number of digits after the <glossary tag="decimal point">decimal point</glossary>. If the number of digits is less than the <i>precision</i>, enough trailing zeroes are added to make <i>precision</i> digits. If no <i>precision</i> is specified, the number is given to six digits after the <glossary tag="decimal point">decimal point</glossary>. If a <i>charLength</i> is specified, if the total length of the resulting number is less than the <i>charLength</i>, enough leading spaces are added to make it <i>charLength</i> <keyword tag="characters">characters</keyword> long; if the length of the resulting number is equal to or greater than the <i>charLength</i>, it is unchanged. For example, the incantation<code tag=""> %3. 2e </code>transforms "232. 4" to "2. 32e+02". </p><p></p><p><code tag="">%[</code><i>charLength</i>. <i>precision</i>]E</p><p>Like <code tag="">%[</code><i>charLength. precision</i>]e, except that the "E" separating the number from the power of ten is uppercase. For example, the incantation<code tag=""> %3. 2e </code>transforms "232. 4" to "2. 32E+02". </p><p></p>
<p>If a zero is included immediately before the <i>charLength</i> parameter in any formatting incantation that allows padding, the resulting value is padded (if necessary) with zeroes instead of spaces. For example, the incantation <code tag="">%03s</code> transforms <code tag="">H</code> to <code tag="">00H</code.</p>
<p></p>
<p>If any of the following C escape sequences are present in the <i>baseString</i>, the <b>format</b> function transforms them to the equivalent character:</p>
<p></p>
<p>	<code tag="">\a</code>	Control-G (bell)</p>
<p>	<code tag="">\b</code>	Control-H (backspace)</p>
<p>	<code tag="">\f</code>	Control-L (<b>formfeed</b>)</p>
<p>	<code tag="">\n</code>	Control-J (linefeed)</p>
<p>	<code tag="">\r</code>	Control-M (<b>return</b>)</p>
<p>	<code tag="">\t</code>	Control-I (<b>tab</b>)</p>
<p>	<code tag="">\v</code>	Control-K (vertical tab)</p>
<p>	<code tag="">\\</code>	\</p>
<p>	<code tag="">\?</code>	?</p>
<p>	<code tag="">\'</code>	'</p>
<p>	<code tag="">\</code>	(enclose a <b>quote</b> within a <keyword tag="string">string</keyword>)</p>
<p>	<code tag="">\nnn</code>	character whose ASCII value is the octal number represented by<code tag="">nnn</code></p>
<p>	<code tag="">\xnn</code>	character whose ASCII value is the hex number represented by<code tag="">nn</code></p>
<p></p>
<p><note>Transformation of values in <i>valuesList</i> uses the standard LiveCode conversion rules. For example, if empty is passed for a numeric incantation it will be taken as the value 0.</note></p>
</comments>
</description>
</doc>