NAME
	sprintf - print the result from sprintf

SYNTAX
	string sprintf(string format,mixed arg,....);

DESCRIPTION
	The format string is a string containing a description of how to
	output the data in the rest of the arguments. This string should
	generally speaking have one %<modifiers><operator> (examples:
	%s, %0d, %-=20s) for each of the rest arguments.

	Modifiers:

	0	Zero pad numbers (implies right justification)
	!	Toggle truncation
	' ' (space)	pad positive integers with a space
	+	pad positive integers with a plus sign
	-	left adjusted within field size (default is right)
	|	centered within field size
	=	column mode if strings are greater than field size
	/	Rough linebreak (break at exactly fieldsize instead of
		between words)
	#	table mode, print a list of '\n' separated word
		(top-to-bottom order)
	$	Inverse table mode (left-to-right order)
	n	(where n is a number or *) a number specifies field size
	.n	set precision
	:n	set field size & precision
	;n	Set column width
	*	if n is a * then next argument is used for precision/field size
	'X'	Set a pad string. ' cannot be a part of the pad_string (yet)
	~	Get pad string from argument list.
	<	Use same arg again
	^	repeat this on every line produced
	@	do this format for each entry in argument array
	>	Put the string at the bottom end of column instead of top
	_	Set width to the length of data

	Operators:

	%%	percent
	%d	signed decimal int
	%u	unsigned decimal int (doesn't really exist in Pike)
	%o	unsigned octal int
	%x	lowercase unsigned hexadecimal int
	%X	uppercase unsigned hexadecimal int
	%c	char (or short with %2c, %3c gives 3 bytes etc.)
	%f	float
	%g	heruistically chosen representation of float
	%e	exponential notation float
	%s	string
	%O	any type (debug style)
	%n	nop
	%t	type of argument
	%<modifiers>{format%}	do a format for every index in an array.

EXAMPLES
	Pike v0.1 Running Hilfe v1.2 (Incremental Pike Frontend)
	> int screen_width=70;
	Result: 70
	> mixed sample;
	> write(sprintf("fish: %c\n", 65));
	fish: A
	Result: 0
	> write(sprintf("Hello green friends\n"));
	Hello green friends
	Result: 0
	> write(sprintf("num: %d\n", 10));
	num: 10
	Result: 0
	> write(sprintf("num: %+10d\n", 10));
	num:        +10
	Result: 0
	> write(sprintf("num: %010d\n", 5*2));
	num: 0000000010
	Result: 0
	> write(sprintf("num: %|10d\n", 20/2));
	num:     10    
	Result: 0
	> write(sprintf("%|*s\n",screen_width,"THE NOT END"));
	                             THE NOT END                              
	Result: 0
	> write(sprintf("%|=*s\n",screen_width, "fun with penguins\n"));
	                          fun with penguins                           
	Result: 0
	> write(sprintf("%-=*O\n",screen_width,({ "fish", 9, "gumbies", 2 })));
	({ /* 4 elements */                                                   
	    "fish",                                                           
	    9,                                                                
	    "gumbies",                                                        
	    2                                                                 
	})                                                                    
	Result: 0
	> write(sprintf("%-=*s\n", screen_width,
	 "This will wordwrap the specified string within the "+
	 "specified field size, this is useful say, if you let "+
	 "users specify their screen size, then the room "+
	 "descriptions will automagically word-wrap as appropriate.\n"+
	 "slosh-n's will of course force a new-line when needed.\n"));
	This will wordwrap the specified string within the specified field    
	size, this is useful say, if you let users specify their screen size, 
	then the room descriptions will automagically word-wrap as            
	appropriate.                                                          
	slosh-n's will of course force a new-line when needed.                
	Result: 0
	> write(sprintf("%-=*s %-=*s\n", screen_width/2,
	 "Two columns next to each other (any number of columns will "+
	 "of course work) independantly word-wrapped, can be useful.",
	 screen_width/2-1,
	 "The - is to specify justification, this is in addherence "+
	 "to std sprintf which defaults to right-justification, "+
	 "this version also supports centre and right justification."));
	Two columns next to each other (any The - is to specify justification,
	number of columns will of course    this is in addherence to std      
	work) independantly word-wrapped,   sprintf which defaults to         
	can be useful.                      right-justification, this version 
	                                    also supports centre and right    
	                                    justification.                    
	Result: 0
	>  write(sprintf("%-$*s\n", screen_width,
	 "Given a\nlist of\nslosh-n\nseparated\n'words',\nthis option\n"+
	 "creates a\ntable out\nof them\nthe number of\ncolumns\n"+
	 "be forced\nby specifying a\npresision.\nThe most obvious\n"+
	 "use is for\nformatted\nls output."));
	Given a          list of          slosh-n          
	separated        'words',         this option      
	creates a        table out        of them          
	the number of    columns          be forced        
	by specifying a  presision.       The most obvious 
	use is for       formatted        ls output.       
	Result: 0
	>  write(sprintf("%-#*s\n", screen_width,
	 "Given a\nlist of\nslosh-n\nseparated\n'words',\nthis option\n"+
	 "creates a\ntable out\nof them\nthe number of\ncolumns\n"+
	 "be forced\nby specifying a\npresision.\nThe most obvious\n"+
	 "use is for\nformatted\nls output."));
	Given a          creates a        by specifying a  
	list of          table out        presision.       
	slosh-n          of them          The most obvious 
	separated        the number of    use is for       
	'words',         columns          formatted        
	this option      be forced        ls output.       
	Result: 0
	> sample = ({ "first column: bing", "second column: womble" });
	Result: ({ /* 2 elements */
	    "first column: bing",
	    "second column: womble"
	})
	> write(sprintf("%-=*s\n%-=@*s\n", screen_width,
	 "Another bizarre option is the @ operator, it applies the "+
	 "format string it is in to each element of the array:",
	 screen_width/sizeof(sample),
	 sample));
	Another bizarre option is the @ operator, it applies the format string
	it is in to each element of the array:                                
	first column: bing                 second column: womble              
	Result: 0
	> write(sprintf("Better use these instead: %{gurksallad: %s\n%}\n",
	 sample));
	Better use these instead: gurksallad: first column: bing
	gurksallad: second column: womble
	
	Result: 0
	> write(sprintf("Of course all the simple printf options "+
	 "are supported:\n %s: %d %x %o %c\n",
	 "65 as decimal, hex, octal and a char",
	 65, 65, 65, 65));
	Of course all the simple printf options are supported:
	 65 as decimal, hex, octal and a char: 65 41 101 A
	Result: 0
	> write(sprintf("%|*s\n",screen_width, "THE END"));
	                               THE END                                
	Result: 0
	> quit
	Exiting.

KEYWORDS
	string

SEE ALSO
	sscanf
