1mNAME0m
       format - Format a string in the style of sprintf

1mSYNOPSIS0m
       1mformat 4m22mformatString24m ?4marg24m 4marg24m 4m...24m?


1mINTRODUCTION0m
       This command generates a formatted string in the same way as the ANSI C
       1msprintf 22mprocedure (it uses 1msprintf  22min  its  implementation).   4mFormat-0m
       4mString24m  indicates  how  to format the result, using 1m% 22mconversion speci-
       fiers as in 1msprintf22m, and the additional arguments, if any, provide val-
       ues to be substituted into the result.  The return value from 1mformat 22mis
       the formatted string.

1mDETAILS ON FORMATTING0m
       The command operates by scanning 4mformatString24m from left to right.  Each
       character  from  the  format  string  is  appended to the result string
       unless it is a percent sign.  If the character is a 1m% 22mthen  it  is  not
       copied  to  the result string.  Instead, the characters following the 1m%0m
       character are treated as a conversion specifier.  The conversion speci-
       fier controls the conversion of the next successive 4marg24m to a particular
       format and the result is appended to the result string in place of  the
       conversion  specifier.   If there are multiple conversion specifiers in
       the format string, then each one controls the conversion of  one  addi-
       tional  4marg24m.   The 1mformat 22mcommand must be given enough 4marg24ms to meet the
       needs of all of the conversion specifiers in 4mformatString24m.

       Each conversion specifier may contain up to  six  different  parts:  an
       XPG3  position specifier, a set of flags, a minimum field width, a pre-
       cision, a length modifier, and a conversion character.   Any  of  these
       fields  may be omitted except for the conversion character.  The fields
       that are present must appear in the order given above.  The  paragraphs
       below discuss each of these fields in turn.

       If  the 1m% 22mis followed by a decimal number and a 1m$22m, as in ``1m%2$d22m'', then
       the value to convert is not taken from the  next  sequential  argument.
       Instead, it is taken from the argument indicated by the number, where 1
       corresponds to the first 4marg24m.  If  the  conversion  specifier  requires
       multiple  arguments  because of 1m* 22mcharacters in the specifier then suc-
       cessive arguments are used, starting with the  argument  given  by  the
       number.   This  follows the XPG3 conventions for positional specifiers.
       If there are any positional specifiers in 4mformatString24m then all of  the
       specifiers must be positional.

       The  second  portion  of  a conversion specifier may contain any of the
       following flag characters, in any order:

       1m-         22mSpecifies that the converted argument should  be  left-justi-
                 fied  in its field (numbers are normally right-justified with
                 leading spaces if needed).

       1m+         22mSpecifies that a number should always be printed with a sign,
                 even if positive.

       4mspace24m     Specifies  that  a  space should be added to the beginning of
                 the number if the first character isn't a sign.

       1m0         22mSpecifies that the number should be padded on the  left  with
                 zeroes instead of spaces.

       1m#         22mRequests an alternate output form. For 1mo 22mand 1mO 22mconversions it
                 guarantees that the first digit is always 1m022m.  For 1mx 22mor 1mX 22mcon-
                 versions, 1m0x 22mor 1m0X 22m(respectively) will be added to the begin-
                 ning of the result unless it is zero.  For all floating-point
                 conversions (1me22m, 1mE22m, 1mf22m, 1mg22m, and 1mG22m) it guarantees that the result
                 always has a decimal point.  For 1mg 22mand 1mG 22mconversions it spec-
                 ifies that trailing zeroes should not be removed.

       The  third portion of a conversion specifier is a number giving a mini-
       mum field width for this conversion.  It is typically used to make col-
       umns  line up in tabular printouts.  If the converted argument contains
       fewer characters than the minimum field width then it will be padded so
       that it is as wide as the minimum field width.  Padding normally occurs
       by adding extra spaces on the left of the converted argument, but the 1m00m
       and  1m-  22mflags may be used to specify padding with zeroes on the left or
       with spaces on the right, respectively.  If the minimum field width  is
       specified as 1m* 22mrather than a number, then the next argument to the 1mfor-0m
       1mmat 22mcommand determines the minimum field width; it must  be  a  numeric
       string.

       The fourth portion of a conversion specifier is a precision, which con-
       sists of a period followed by a number.  The number is used in  differ-
       ent  ways  for  different  conversions.  For 1me22m, 1mE22m, and 1mf 22mconversions it
       specifies the number of digits to appear to the right  of  the  decimal
       point.  For 1mg 22mand 1mG 22mconversions it specifies the total number of digits
       to appear, including those on both sides of the decimal point (however,
       trailing  zeroes  after  the decimal point will still be omitted unless
       the 1m# 22mflag has been specified).  For integer conversions, it  specifies
       a  minimum  number  of digits to print (leading zeroes will be added if
       necessary).  For 1ms 22mconversions it specifies the maximum number of char-
       acters to be printed; if the string is longer than this then the trail-
       ing characters will be dropped.  If the precision is specified  with  1m*0m
       rather  than  a  number  then  the  next argument to the 1mformat 22mcommand
       determines the precision; it must be a numeric string.

       The fifth part of a conversion specifier is a  length  modifier,  which
       must  be 1mh 22mor 1ml22m.  If it is 1mh 22mit specifies that the numeric value should
       be truncated to a 16-bit  value  before  converting.   This  option  is
       rarely  useful.   If it is 1ml 22mit specifies that the numeric value should
       be (at least) a 64-bit value.  If neither 1mh 22mnor 1ml 22mare present,  numeric
       values  are  interpreted  as  being  values  of the width of the native
       machine word, as described by 1mtcl_platform(wordSize)22m.

       The last thing in a conversion specifier  is  an  alphabetic  character
       that determines what kind of conversion to perform.  The following con-
       version characters are currently supported:

       1md         22mConvert integer to signed decimal string.

       1mu         22mConvert integer to unsigned decimal string.

       1mi         22mConvert integer to signed decimal string;   the  integer  may
                 either be in decimal, in octal (with a leading 1m022m) or in hexa-
                 decimal (with a leading 1m0x22m).

       1mo         22mConvert integer to unsigned octal string.

       1mx 22mor 1mX    22mConvert integer to unsigned hexadecimal string, using  digits
                 ``0123456789abcdef'' for 1mx 22mand ``0123456789ABCDEF'' for 1mX22m).

       1mc         22mConvert integer to the Unicode character it represents.

       1ms         22mNo conversion; just insert string.

       1mf         22mConvert floating-point number to signed decimal string of the
                 form 4mxx.yyy24m, where the number of 4my24m's  is  determined  by  the
                 precision  (default: 6).  If the precision is 0 then no deci-
                 mal point is output.

       1me 22mor 1me    22mConvert floating-point number to scientific notation  in  the
                 form 4mx.yyy24m1me+-4m22mzz24m, where the number of 4my24m's is determined by the
                 precision (default: 6).  If the precision is 0 then no  deci-
                 mal point is output.  If the 1mE 22mform is used then 1mE 22mis printed
                 instead of 1me22m.

       1mg 22mor 1mG    22mIf the exponent is less than -4 or greater than or  equal  to
                 the  precision,  then convert floating-point number as for 1m%e0m
                 or 1m%E22m.  Otherwise convert as for 1m%f22m.  Trailing zeroes  and  a
                 trailing decimal point are omitted.

       1m%         22mNo conversion: just insert 1m%22m.

       For  the  numerical conversions the argument being converted must be an
       integer or floating-point  string;  format  converts  the  argument  to
       binary  and  then converts it back to a string according to the conver-
       sion specifier.

1mDIFFERENCES FROM ANSI SPRINTF0m
       The behavior of the format command is the same as the  ANSI  C  1msprintf0m
       procedure except for the following differences:

       [1]    1m%p 22mand 1m%n 22mspecifiers are not currently supported.

       [2]    For  1m%c 22mconversions the argument must be a decimal string, which
              will then be converted to the corresponding character value.

       [3]    The 1ml 22mmodifier is ignored for real values and  on  64-bit  plat-
              forms,  which  are  always  converted  as if the 1ml 22mmodifier were
              present (i.e. the types 1mdouble 22mand 1mlong 22mare used for the  inter-
              nal  representation  of  real and integer values, respectively).
              If the 1mh 22mmodifier is specified then integer values are truncated
              to  1mshort 22mbefore conversion.  Both 1mh 22mand 1ml 22mmodifiers are ignored
              on all other conversions.

1mEXAMPLES0m
       Convert the output of 1mtime 22minto seconds to an accuracy of hundredths of
       a second:
              set us [lindex [time $someTclCode] 0]
              puts [1mformat 22m"%.2f seconds to execute" [expr {$us / 1e6}]]

       Create a packed X11 literal color specification:
              # Each color-component should be in range (0..255)
              set color [1mformat 22m"#%02x%02x%02x" $r $g $b]

       Use  XPG3  format codes to allow reordering of fields (a technique that
       is often used  in  localized  message  catalogs;  see  1mmsgcat22m)  without
       reordering the data values passed to 1mformat22m:
              set fmt1 "Today, %d shares in %s were bought at $%.2f each"
              puts [1mformat 22m$fmt1 123 "Global BigCorp" 19.37]

              set fmt2 "Bought %2\$s equity ($%3$.2f x %1\$d) today"
              puts [1mformat 22m$fmt2 123 "Global BigCorp" 19.37]

       Print a small table of powers of three:
              # Set up the column widths
              set w1 5
              set w2 10

              # Make a nice header (with separator) for the table first
              set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+
              puts $sep
              puts [1mformat 22m"| %-*s | %-*s |" $w1 "Index" $w2 "Power"]
              puts $sep

              # Print the contents of the table
              set p 1
              for {set i 0} {$i<=20} {incr i} {
                 puts [1mformat 22m"| %*d | %*ld |" $w1 $i $w2 $p]
                 set p [expr {wide($p) * 3}]
              }

              # Finish off by printing the separator again
              puts $sep


1mSEE ALSO0m
       scan(n), sprintf(3), string(n)


1mKEYWORDS0m
