NAME
       format - Format a string in the style of sprintf

SYNOPSIS
       format formatString ?arg arg ...?


INTRODUCTION
       This  command generates a formatted string in the same way
       as the ANSI C sprintf procedure (it uses  sprintf  in  its
       implementation).  FormatString indicates how to format the
       result, using % conversion specifiers as in  sprintf,  and
       the  additional  arguments,  if  any, provide values to be
       substituted into the result.  The return value from format
       is the formatted string.


DETAILS ON FORMATTING
       The command operates by scanning formatString 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 % then it  is  not  copied  to  the  result
       string.  Instead, the characters following the % character
       are treated as a  conversion  specifier.   The  conversion
       specifier  controls  the conversion of the next successive
       arg 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 arg.  The format command must be given enough  args
       to  meet  the needs of all of the conversion specifiers in
       formatString.

       Each conversion specifier may contain up to six  different
       parts: an XPG3 position specifier, a set of flags, a mini-
       mum field width, a precision, 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 para-
       graphs below discuss each of these fields in turn.

       If the % is followed by a decimal number and a  $,  as  in
       ``%2$d'',  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 arg.  If the conversion specifier requires  mul-
       tiple  arguments  because of * characters in the specifier
       then successive arguments  are  used,  starting  with  the
       argument  given by the number.  This follows the XPG3 con-
       ventions for positional  specifiers.   If  there  are  any
       positional  specifiers  in  formatString  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:

       -         Specifies  that the converted argument should be
                 left-justified in its field  (numbers  are  nor-
                 mally  right-justified  with  leading  spaces if
                 needed).

       +         Specifies that a number should always be printed
                 with a sign, even if positive.

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

       0         Specifies  that  the  number should be padded on
                 the left with zeroes instead of spaces.

       #         Requests an alternate output form. For o  and  O
                 conversions  it  guarantees that the first digit
                 is always 0.  For x or X conversions, 0x  or  0X
                 (respectively) will be added to the beginning of
                 the result unless it is zero.  For all floating-
                 point conversions (e, E, f, g, and G) it guaran-
                 tees that the result always has a decimal point.
                 For g and G conversions it specifies that trail-
                 ing zeroes should not be removed.

       The third portion of a conversion specifier  is  a  number
       giving  a  minimum field width for this conversion.  It is
       typically used to make columns line up in  tabular  print-
       outs.  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 0 and - flags 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 * rather than a number, then the  next  argu-
       ment  to  the  format command determines the minimum field
       width; it must be a numeric string.

       The fourth portion of a conversion specifier is  a  preci-
       sion,  which  consists  of  a period followed by a number.
       The number is used in different ways for different conver-
       sions.   For e, E, and f conversions it specifies the num-
       ber of digits to appear to the right of the decimal point.
       For  g  and G conversions 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  #  flag  has  been
       specified).  For integer conversions, it specifies a mini-
       mum number of digits to  print  (leading  zeroes  will  be
       added  if  necessary).  For s conversions it specifies the
       maximum number of characters to be printed; if the  string
       is  longer  than this then the trailing characters will be
       dropped.  If the precision is specified with * rather than
       a  number  then  the  next  argument to the format command
       determines the precision; it must be a numeric string.

       The fifth part of a conversion specifier is a length modi-
       fier,  which must be h or l.  If it is h it specifies that
       the numeric value should be truncated to  a  16-bit  value
       before  converting.   This option is rarely useful.  The l
       modifier is ignored.

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

       d         Convert integer to signed decimal string.

       u         Convert integer to unsigned decimal string.

       i         Convert  integer  to signed decimal string;  the
                 integer may either be in decimal, in octal (with
                 a  leading  0) or in hexadecimal (with a leading
                 0x).

       o         Convert integer to unsigned octal string.

       x or X    Convert integer to unsigned hexadecimal  string,
                 using  digits  ``0123456789abcdef''  for  x  and
                 ``0123456789ABCDEF'' for X).

       c         Convert integer to the Unicode character it rep-
                 resents.

       s         No conversion; just insert string.

       f         Convert  floating-point number to signed decimal
                 string of the form xx.yyy, where the  number  of
                 y's is determined by the precision (default: 6).
                 If the precision is 0 then no decimal  point  is
                 output.

       e or e    Convert   floating-point  number  to  scientific
                 notation in the form x.yyye+-zz, where the  num-
                 ber  of  y's  is  determined  by  the  precision
                 (default: 6).  If the precision  is  0  then  no
                 decimal  point is output.  If the E form is used
                 then E is printed instead of e.

       g or G    If the exponent is less than -4 or greater  than
                 or  equal  to the precision, then convert float-
                 ing-point number as for  %e  or  %E.   Otherwise
                 convert as for %f.  Trailing zeroes and a trail-
                 ing decimal point are omitted.
       %         No conversion: just insert %.

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


DIFFERENCES FROM ANSI SPRINTF
       The behavior of the format command is the same as the ANSI
       C sprintf procedure except for the following differences:

       [1]    %p and %n specifiers are not currently supported.

       [2]    For %c conversions the argument must be  a  decimal
              string,  which will then be converted to the corre-
              sponding character value.

       [3]    The l modifier  is  ignored;   integer  values  are
              always  converted as if there were no modifier pre-
              sent and real values are always converted as if the
              l  modifier  were present (i.e. type double is used
              for the internal representation).  If the  h  modi-
              fier is specified then integer values are truncated
              to short before conversion.


KEYWORDS
       conversion specifier, format, sprintf,  string,  substitu-
       tion
