<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 &quot;printf()&quot; <control_st tag="function">function</control_st>. </summary>

	<examples>
<example>format(&quot;Hello world&quot;) </example>
<example>format(&quot;Hello\nworld&quot;) </example>
<example><p>format(&quot;%1.3e&quot;,865.3) </p></example>
<example>format(&quot;Hello world&quot;) </example>
<example>format(&quot;%45d&quot;,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 &quot;<code tag="">H</code>&quot; to &quot;<code tag="">  H</code>&quot;. </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 &quot;<code tag=""> A</code>&quot; (65 is the ASCII value of the <keyword tag="character">character</keyword> &quot;A&quot;). </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 &quot;<code tag="">2.3</code>&quot; to &quot;<code tag=""> </code>2&quot;. </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="">&quot;10. 7</code>&quot; to <code tag="">&quot; 13</code>&quot;.</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 &quot;<code tag="">30.3</code>&quot; to &quot;<code tag="">  1e</code>&quot;. </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 &quot;<code tag="">30. 3</code>&quot; to &quot;<code tag="">  1E</code>&quot;.</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 &quot;232. 4&quot; to &quot;2. 32e+02&quot;. </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 &quot;E&quot; separating the number from the power of ten is uppercase. For example, the incantation<code tag=""> %3. 2e </code>transforms &quot;232. 4&quot; to &quot;2. 32E+02&quot;. </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>&#9;<code tag="">\a</code>&#9;Control-G (bell)</p>
<p>&#9;<code tag="">\b</code>&#9;Control-H (backspace)</p>
<p>&#9;<code tag="">\f</code>&#9;Control-L (<b>formfeed</b>)</p>
<p>&#9;<code tag="">\n</code>&#9;Control-J (linefeed)</p>
<p>&#9;<code tag="">\r</code>&#9;Control-M (<b>return</b>)</p>
<p>&#9;<code tag="">\t</code>&#9;Control-I (<b>tab</b>)</p>
<p>&#9;<code tag="">\v</code>&#9;Control-K (vertical tab)</p>
<p>&#9;<code tag="">\\</code>&#9;\</p>
<p>&#9;<code tag="">\?</code>&#9;?</p>
<p>&#9;<code tag="">\'</code>&#9;'</p>
<p>&#9;<code tag="">\</code>&#9;(enclose a <b>quote</b> within a <keyword tag="string">string</keyword>)</p>
<p>&#9;<code tag="">\nnn</code>&#9;character whose ASCII value is the octal number represented by<code tag="">nnn</code></p>
<p>&#9;<code tag="">\xnn</code>&#9;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>