format man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



format(n)	      Tcl Built-In Commands		format(n)

_________________________________________________________________

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

Tcl								1

format(n)	      Tcl Built-In Commands		format(n)

       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

Tcl								2

format(n)	      Tcl Built-In Commands		format(n)

       minimum 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 8-bit character it repre-
		 sents.

       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

Tcl								3

format(n)	      Tcl Built-In Commands		format(n)

		 floating-point number as for %e or  %E.   Other-
		 wise  convert	as for %f.  Trailing zeroes and a
		 trailing 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

Tcl								4

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net