| SYNOPSIS |
| string sprintf(string fmt, ...) |
| |
| DESCRIPTION |
| Most of the characters in the format string (FMT) get passed |
| straight through to the output (ie: printed or put in the |
| return string), to format the arguments into the string it is |
| necessary to include an argument format string (AFS) in the |
| FMT. An AFS is a series of characters starting with a percent |
| sign "%" and terminated with a argument type specifier. |
| To include a "%" sign in the output, it is necessary to include a |
| double percent sign "%%". The sequence "%^" will output "%^" again. |
| |
| Valid argument type specifiers are: |
| "s" : the argument is a string. |
| "d" : the argument is an integer to be included in decimal |
| representation. |
| "i" : same as "d". |
| "b" : the argument is an integer to be included in binary |
| representation. |
| "o" : the argument is an integer to be included in octal |
| representation. |
| "x" : the argument is an integer to be included in hexadecimal |
| representation. |
| "X" : as "x" except letters are capitalised. |
| "e","E","f","g","G" : the argument is a float to be included in |
| decimal representation; see examples for details |
| "c" : the argument is an int to included as a character |
| "O" : the argument is an LPC datatype to be printed in an arbituary |
| format, this is for debugging purposes. |
| If the argument is an object then the function |
| printf_obj_name() on the master object is called with the |
| object as a parameter, the string returned is included in |
| brackets at the end of object file name. |
| If 0 is returned then nothing is appended after the file name. |
| "Q" Like "O", except that special characters in strings are |
| printed in LPC notation. |
| |
| Between the percent sign and the argument type specifier in |
| the AFS, the following modifiers can be included to specify |
| the formatting information. Order is not important unless |
| otherwise specified. "n" is used to specify a integer, which |
| can be a "*" in which case the next argument is used as the |
| number. |
| |
| Modifiers: |
| n specifies the field size. If the size is prepended with |
| a 0, the argument is printed with leading zeroes. |
| "."n specifies the precision, for simple (not columns or tables) |
| strings specifies the truncation length. |
| ":"n n specifies both the field size _and_ the presision, if n is |
| prepended by a zero then the pad string is set to "0". |
| "'X'" the pad string is set to the char(s) between the single |
| quotes, if the field size is also prepended with a zero then |
| which ever is specified last will overrule. |
| NOTE: to include "'" in the pad string, you must use "\\'" |
| (as the backslash has to be escaped past the interpreter), |
| similarly, to include "\" requires "\\\\". |
| " " pad positive integers with a space. |
| "+" pad positive integers with a plus sign. |
| "-" left aligned within field size. |
| NB: std (s)printf() defaults to right alignment, which is |
| unnatural in the context of a mainly string based language |
| but has been retained for "compatibility" ;) |
| "|" centered within field size. |
| "$" justified to field size. Ignored unless the type specifier |
| is 's'. |
| "=" column mode. Ignored unless the argument type specifier is 's'. |
| Field size must be specified, if precision is specified then |
| it specifies the width for the string to be wordwrapped in, if |
| not then the field size is. The field size specifies the width |
| of the column and has the effect that the last line of the |
| column is padded with spaces to achieve this length. |
| "#" For strings: table mode. |
| Field size must be specified, if precision is |
| specified then it specifies the number of columns in |
| the table, otherwise the number is "optimally" |
| generated (as few lines and columns as possible). |
| Table mode is passed a list of backslash-n separated |
| 'words' which are put in a format similar to that of |
| ls. |
| For %O/%Q: compact output. |
| "@" the argument is an array. the corresponding AFS (minus all |
| "@") is applied to each element of the array. |
| |
| When the formatting of an element results in several output lines |
| (column or table mode) and no explicit pad strings has been |
| defined, then the efun removes any padding whitespace before |
| the newlines of all but the last line. However, if an explicit |
| pad string has been given, even if it is the simple ' ', then |
| the padding will not be removed. |
| |
| |
| EXAMPLES |
| sprintf("decimal=%d, octal=%o, hexadecimal=%x\n", 7, 7, 7); |
| |
| sprintf("array=%O\n", ({1, 2, 3})); |
| this will return the following: |
| ({ /* sizeof() == 3 */ |
| 1, |
| 2, |
| 3 |
| }) |
| An array will be printed recursively and each element of the |
| array will be indented. Can also be used as a debugging tool. |
| |
| sprintf("%-*#s\n", 80, implode(get_dir("~/."), "\n")); |
| |
| sprintf("foo") // returns "foo" |
| |
| sprintf("%s","foo") // returns "foo" |
| sprintf("%7s","foo") // returns " foo" |
| sprintf("%-7s","foo") // returns "foo " |
| sprintf("%|7s","foo") // returns " foo " |
| sprintf("%7'.'s","foo") // returns "....foo" |
| sprintf("%-7'+-'s","foo") // returns "foo+-+-" |
| sprintf("%|9'-+'s","foo") // returns "-+-foo-+-" |
| sprintf("%3s","foobarbloh") // returns "foobarbloh" |
| sprintf("%3.6s","foobarbloh") // returns "foobar" |
| sprintf("%6.3s","foobarbloh") // returns " foo" |
| sprintf("%:6s","foobarbloh") // returns "foobar" |
| sprintf("%:3s","foobarbloh") // returns "foo" |
| sprintf("%*.*s",-7,2,"foobarbloh") // returns "fo " |
| |
| sprintf("%=12s","this is a very long sentence\n") |
| // returns " this is a\n" |
| // " very long\n" |
| // " sentence\n" |
| sprintf("%=-12s","this is a very long sentence\n") |
| // returns "this is a\n" |
| // "very long\n" |
| // "sentence\n" |
| sprintf("%=|12s","this is a very long sentence\n") |
| // returns " this is a\n" |
| // " very long\n" |
| // " sentence\n" |
| sprintf("%=10.6s","this is a very long sentence\n") |
| // returns " this\n" |
| // " is a\n" |
| // " very\n" |
| // " long\n" |
| // " senten\n" |
| // " ce\n" |
| sprintf("%#-40.3s\n", |
| "one\ntwo\nthree\nfour\nfive\nsix\nseven\neight\nnine\nten\n") |
| // returns "one five nine\n" |
| // "two six ten\n" |
| // "three seven \n" |
| // "four eight \n" |
| sprintf("%#-40s\n", |
| "one\ntwo\nthree\nfour\nfive\nsix\nseven\neight\nnine\nten\n") |
| // returns "one three five seven nine\n" |
| // "two four six eight ten\n" |
| |
| sprintf("%@-5s",({"foo","bar","bloh"})) // returns "foo bar bloh " |
| |
| sprintf("%d",123) // returns "123" |
| sprintf("%7d",123) // returns " 123" |
| sprintf("%-7d",123) // returns "123 " |
| sprintf("%d/%d",123,-123) // returns "123/-123" |
| sprintf("% d/% d",123,-123) // returns " 123/-123" |
| sprintf("%+d/%+d",123,-123) // returns "+123/-123" |
| sprintf("%+5d/%5d",123,123) // returns " +123/ 123" |
| sprintf("%|6d",123) // returns " 123 " |
| sprintf("%|10d",123) // returns " 123 " |
| sprintf("%|10d%3s",123,"foo") // returns " 123 foo" |
| |
| sprintf("%o",16) // returns "20" |
| sprintf("%'0'3o",8) // returns "010" |
| |
| sprintf("%x",123) // returns "7b" |
| sprintf("%X",123) // returns "7B" |
| |
| sprintf("%f",123.5) // returns "124" |
| sprintf("%8.3f",123.5) // returns " 123.500" |
| sprintf("%E",123.5) // returns "1E+02" |
| sprintf("%12.4e",123.5) // returns " 1.2350e+02" |
| sprintf("%g",123.5) // returns "1e+02" |
| sprintf("%8.3G",123.5) // returns " 124" |
| sprintf("%8.6g",123.5) // returns " 123.5" |
| |
| HISTORY |
| LDMud 3.2.9 added the "%^" sequence for compatibility with |
| terminal_colour(), added the "%Q" sequence, clarified the meaning of |
| leading 0s in the field size modifier, clarified the interaction |
| between the padding and newlines, and added the '$' formatter for |
| justified printing of strings. |
| LDMud 3.2.10 added modifier '#' for '%O'/'%Q' and the datatype '%b'. |
| |
| SEE ALSO |
| printf(E), terminal_colour(E) |