<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../style.css">
<title>
Gambas Documentation - Format$
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../help+en"><img class="flag" alt="Home" border="0" src="../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../lang+en">Up</a>&nbsp;
<a href="foreach+en">Previous</a>&nbsp;
<a href="frac+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
Format$
</h1>
<div class="black"><font size="-2"><b>Syntax</b></font></div>
<pre class="syntax"><u>String</u> <b>= Format$ (</b> <u>Expression</u> [ <b>,</b> <u>Format</u> ] <b>)</b>
<u>String</u> <b>= Format (</b> <u>Expression</u> [ <b>,</b> <u>Format</u> ] <b>)</b></pre><p>

Converts the <u>Expression</u> to a <a href="../comp/gb/string+en">String</a> by using a format that depends on the type of the <u>Expression</u> .
<p>
This function can format dates, times, numbers, and currencies.
<p>
<u>Format</u> can be a predefined format (an <a href="type/integer+en">Integer</a> constant) or a user-defined format (a <a href="../comp/gb/string+en">String</a> that depicts the format) or can be omitted.
<p>
See <a href="../cat/constant+en">Predefined Constants</a> for a list of predefined formats.
<p>
If <u>Format</u> is not specified, <a href="../comp/gb/gb+en">gb</a>.<a href="../comp/gb/gb/standard+en">Standard</a> is used.
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/warning.png" align="center"></td><td valign="top">
This function uses localization information.
</td></tr></table></div>
<p>
<h2>User-defined formats for a numeric expression</h2>
<p>
A user-defined format is described by a sequence of special characters.
<p>
Arbitrary characters specified before and after the format strings will be printed as is
<p>
<h3>Characters for user-defined formats</h3>
<p>
<table class="table" border="0" bordercolor="#000000" cellpadding="4" cellspacing="0">
<tr class="dark"><td valign="top">
<tt>+</tt>
</td><td valign="top">
Prints the sign of the number.
</td></tr>
<tr><td valign="top">
<tt>-</tt>
</td><td valign="top">
Prints the sign of the number only if it is negative.
</td></tr>
<tr class="dark"><td valign="top">
<tt>#</tt>
</td><td valign="top">
Prints a digit only if necessary.
</td></tr>
<tr><td valign="top">
<tt>0</tt>
</td><td valign="top">
Always prints a digit, padding with a zero if necessary.
</td></tr>
<tr class="dark"><td valign="top">
<tt>.</tt>
</td><td valign="top">
Prints the decimal separator.
</td></tr>
<tr><td valign="top">
<tt>,</tt>
</td><td valign="top">
Prints the thousand separators.
</td></tr>
<tr class="dark"><td valign="top">
<tt>%</tt>
</td><td valign="top">
Multiplies the number by 100 and prints a per-cent sign.
</td></tr>
<tr><td valign="top">
<tt>E</tt>
</td><td valign="top">
Introduces the exponential part of a <a href="type/float+en">Float</a> number. The sign of the exponent is    always printed.
</td></tr>
</table>
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Pi, &quot;-#.###&quot;)
<hr>3.142</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Pi, &quot;+0#.###0&quot;)
<hr>+03.1416</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Pi / 10, &quot;###.# %&quot;)
<hr>31.4 %</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(-11 ^ 11, &quot;#.##E##&quot;)
<hr>-2.85E+11</pre>
<p>
<h3>User-defined format characters for currencies</h3>
<p>
<table class="table" border="0" bordercolor="#000000" cellpadding="4" cellspacing="0">
<tr class="dark"><td valign="top">
<tt>$</tt>
</td><td valign="top">
Prints the national currency symbol.
</td></tr>
<tr><td valign="top">
<tt>$$</tt>
</td><td valign="top">
When the <tt>$</tt> is doubled, the international currency symbol is printed instead.
</td></tr>
<tr class="dark"><td valign="top">
<tt>(</tt>
</td><td valign="top">
Prints the representation of negative currencies. This must be the first character of the format. You can specify a closed brace <tt>)</tt> at the end of the format.
</td></tr>
</table>
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(1972.06, &quot;$#.###&quot;)
<hr>$1972.06</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(-1972.06, &quot;$,#.###&quot;)
<hr>-$1,972.06</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(-1972.06, &quot;($,#.###)&quot;)
<hr>$1,972.06
or
1.972,06 €</pre>
<p>
<h3>User-defined format characters for dates</h3>
<p>
<table class="table" border="0" bordercolor="#000000" cellpadding="4" cellspacing="0">
<tr class="dark"><td valign="top">
<tt>yy</tt>
</td><td valign="top">
Prints the year on    two digits.
</td></tr>
<tr><td valign="top">
<tt>yyyy</tt>
</td><td valign="top">
Prints the year    on four digits.
</td></tr>
<tr class="dark"><td valign="top">
<tt>m</tt>
</td><td valign="top">
Prints the month.
</td></tr>
<tr><td valign="top">
<tt>mm</tt>
</td><td valign="top">
Prints the month on    two digits.
</td></tr>
<tr class="dark"><td valign="top">
<tt>mmm</tt>
</td><td valign="top">
Prints the month    in an abbreviatted string form.
</td></tr>
<tr><td valign="top">
<tt>mmmm</tt>
</td><td valign="top">
Prints the month    in its full string form.
</td></tr>
<tr class="dark"><td valign="top">
<tt>d</tt>
</td><td valign="top">
Prints the day.
</td></tr>
<tr><td valign="top">
<tt>dd</tt>
</td><td valign="top">
Prints the day on    two digits.
</td></tr>
<tr class="dark"><td valign="top">
<tt>ddd</tt>
</td><td valign="top">
Prints the week    day in an abbreviated form.
</td></tr>
<tr><td valign="top">
<tt>dddd</tt>
</td><td valign="top">
Prints the week    day in its full form.
</td></tr>
<tr class="dark"><td valign="top">
<tt>/</tt>
</td><td valign="top">
Prints the date    separator.
</td></tr>
<tr><td valign="top">
<tt>h</tt>
</td><td valign="top">
Prints the hour.
</td></tr>
<tr class="dark"><td valign="top">
<tt>hh</tt>
</td><td valign="top">
Prints the hour on    two digits.
</td></tr>
<tr><td valign="top">
<tt>n</tt>
</td><td valign="top">
Prints the minutes.
</td></tr>
<tr class="dark"><td valign="top">
<tt>nn</tt>
</td><td valign="top">
Prints the minutes    on two digits.
</td></tr>
<tr><td valign="top">
<tt>s</tt>
</td><td valign="top">
Prints the seconds.
</td></tr>
<tr class="dark"><td valign="top">
<tt>ss</tt>
</td><td valign="top">
Prints the seconds    on two digits.
</td></tr>
<tr><td valign="top">
<tt>:</tt>
</td><td valign="top">
Prints the time    separator.
</td></tr>
<tr class="dark"><td valign="top">
<tt>u</tt>
</td><td valign="top">
Prints the milliseconds, if they are different from zero.
</td></tr>
</table>
<p>

<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Now, &quot;mm/dd/yyyy hh:nn:ssu&quot;)
<hr>04/15/2002 09:05:36.26</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Now, &quot;m/d/yy h:n:s&quot;)
<hr>4/15/02 9:5:36</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Now, &quot;ddd dd mmm yyyy&quot;)
<hr>Mon 15 Apr 2002</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Now, &quot;dddd dd mmmm yyyy&quot;)
<hr>Monday 15 April 2002</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">PRINT Format$(Now, &quot;yyyy-mm-dd hh-nn-ss&quot;)
PRINT Format$(Now, &quot;yyyy/mm/dd hh:nn:ss&quot;)
<hr>2006-04-29 07-41-11
2006.04.29 07:41:11</pre>
<hr><b>See also</b><br>
<a href="../cat/format+en">Formatting functions</a>&nbsp;

</div>
</body>
</html>

