/
ColdC/Functions/
ColdC/Structure/ 
<head><title>ColdC: Function/Method Reference: strfmt()</title></head>

<body>

<h1 align=center><a href="/ColdC/">ColdC</a>: <a href="/ColdC/Functions/">Function/Method Reference</a>: strfmt()</h1>

<hr>

<p>
<font size=+1><i>STRING</i> <b>strfmt</b>(<i>STRING <b>format</b>, ANY <b>arg</b>...</i>)</font>

<p>This function formats its arguments and returns the result.  How the
arguments are formatted depends upon the argument <var>format</var>.  The
format contains two types of sequences: plain characters, which are
simply copied to the new string, and format specifications, each of
which causes printing of the next successive argument.

<p>The format begins with a percent character (<code>%</code>), followed
by:

<dl>
<dt>Pad Length
<dd>The pad length is an integer which specifies the length of characters to
    pad the argument in.  Pad Length is optional.  Specifying a zero pad
    length will be ignored, and is equivalent to not specifying a pad length.
    <p>
<dt>Precision
<dd>A period (<code>.</code>), followed by an integer specifies
    the precision, which specifies the number of digits to appear
    after the decimal point when printing FLOAT arguments.  Precision is
    optional, and does not have to be specified.  If it is specified it
    must come after the Pad Length (if specified), and before the Filler
    (if specified) or Format Type.
    <p>
<dt>Filler
<dd>Filler specifies what is used when padding a string within the Pad Length.
    Filler is specified within curly braces (<code>{</code> and <code>}</code>).
    To include a curly brace in the filler prefix it with a backslash.  The
    Filler must come after Pad Length or Precision, if they are specified,
    and before Format Type.
    <p>
<dt>Format Type
<dd>Format type must be specified last, and is not optional.  Format Type
    specifies how the argument is to be handled.  It is one of the
    following characters:
    <p>
    <dl>
    <dt><b>d</b> or <b>D</b>
    <dd>literal data  
    <dt><b>s</b> or <b>S</b> or <b>l</b> or <b>L</b>
    <dd>any data, align left    
    <dt><b>r</b> or <b>R</b>
    <dd>any data, align right
    <dt><b>c</b> or <b>C</b>
    <dd>any data, align centered 
    <dt><b>e</b>
    <dd>any data, align left with an elipse 
    </dl>
    <p>If the Format Type is anything but <b>d</b> or <b>D</b>, the data
    will be converted as if it were "added" to a string
    <a href="/ColdC/Structure/expressions.html#arith">using the
    arithmetic operator</a>.  If an uppercase character is used
    in the Format Type, any argument which has a length longer than the
    Pad Length will be truncated accordingly.  Otherwise the argument
    will not be truncated.  If an elipse is used, the argument will always be
    truncated three characters shorter than the Pad Length, with
    <code>"..."</code> being placed at the end.
</dl>
<p>Examples:

<blockquote><pre>
strfmt("%r", "test")
=&gt; "test"

strfmt("%l", "test")
=&gt; "test"

strfmt("%c", "test")
=&gt; "test"

strfmt("%d", "test")
=&gt; "\"test\""

strfmt("%10r", "test")
=&gt; "      test"  

strfmt("%10l", "test")
=&gt; "test      "

strfmt("%10c", "test")
=&gt; "   test   "  

strfmt("%10{|&gt;}r", "test")
=&gt; "|&gt;|&gt;|&gt;test"

strfmt("%10{|&gt;}l", "test")
=&gt; "test|&gt;|&gt;|&gt;" 

strfmt("%10{|&gt;}c", "test")
=&gt; "|&gt;|test|&gt;|" 

strfmt("%.2l", 1.1214)
=&gt; "1.12"

strfmt("%10.3{0}r", 1.1214)
=&gt; "000001.121"

strfmt("%10.3{0}r", 1.1214)
=&gt; "1.12100000"

strfmt("%5e", "testing")
=&gt; "te..."

strfmt("%s parents: %25e", "$user", [$body, $interaction, $mail_ui, $command_aliases]);
=&gt; "$user parents: [$body, $interaction, ..."
</pre</blockquote>
<p><hr size=4><p align=center><i>Last Modified on 24 Mar 1996</i>
<br><i>Copyright &copy; 1995, 1996, Brandon Gillespie</i>
</body>