sort()

sqrt()

Method sprintf()

Method sprintf

string sprintf(strict_sprintf_format format, sprintf_args ... args)

Description

Print formated output to string.

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

The following modifiers are supported:

'0' Zero pad numbers (implies right justification). '!' Toggle truncation. ' ' Pad positive integers with a space. '+' Pad positive integers with a plus sign. '-' Left adjust within field size (default is right). '|' Centered within field size. '=' Column mode if strings are greater than field size. Breaks between words (possibly skipping or adding spaces). Can not be used together with '/'. '/' Column mode with rough line break (break at exactly field size instead of between words). Can not be used together with '='. '#' Table mode, print a list of '\n' separated words (top-to-bottom order). '$' Inverse table mode (left-to-right order). 'n' (Where n is a number or *) field width specifier. ':n' '.n' Precision specifier. ';n' Column width specifier. '*' If n is a * then next argument is used for precision/field size. The argument may either be an integer, or a modifier mapping as received by lfun::_sprintf() : "precision" : int|void Precision. "width" : int(0..)|void Field width. "flag_left" : int(0..1)|void Indicates that the output should be left-aligned. "indent" : int(0..)|void Indentation level in %O-mode. "'" Set a pad string. ' cannot be a part of the pad string (yet). '~' Get pad string from argument list. '<' Use same argument again. '^' Repeat this on every line produced. '@' Repeat this format for each element in the argument array. '>' Put the string at the bottom end of column instead of top. '_' Set width to the length of data. '[n]' Select argument number n. Use * to use the next argument as selector. The arguments are numbered starting from 0 (zero) for the first argument after the format . Note that this only affects where the current operand is fetched.

The following operators are supported:

'%' Percent. 'b' Signed binary integer. 'd' Signed decimal integer. 'u' Unsigned decimal integer. 'o' Signed octal integer. 'x' Lowercase signed hexadecimal integer. 'X' Uppercase signed hexadecimal integer. 'c' Character. If a fieldsize has been specified this will output the low-order bytes of the integer in network (big endian) byte order. To get little endian byte order, negate the field size. 'f' Float. (Locale dependent formatting.) 'g' Heuristically chosen representation of float. (Locale dependent formatting.) 'G' Like %g, but uses uppercase E for exponent. 'e' Exponential notation float. (Locale dependent output.) 'E' Like %e, but uses uppercase E for exponent. 'F' Binary IEEE representation of float (%4F gives single precision, %8F gives double precision) in network (big endian) byte order. To get little endian byte order, negate the field size. 's' String. 'q' Quoted string. Escapes all control and non-8-bit characters, as well as the quote characters '\\' and '\"'. 'O' Any value, debug style. Do not rely on the exact formatting; how the result looks can vary depending on locale, phase of the moon or anything else the lfun::_sprintf() method implementor wanted for debugging. 'H' Binary Hollerith string. Equivalent to sprintf("%c%s",        strlen(str), str). Arguments (such as width etc) adjust the length-part of the format. Requires 8-bit strings. 'n' No argument. Same as "%s" with an empty string as argument. Note: Does take an argument array (but ignores its content) if the modifier '@' is active. 't' Type of the argument. '{' Perform the enclosed format for every element of the argument array. '}'

Most modifiers and operators are combinable in any fashion, but some combinations may render strange results.

If an argument is an object that implements lfun::_sprintf() , that callback will be called with the operator as the first argument, and the current modifiers as the second. The callback is expected to return a string.

Note

sprintf-style formatting is applied by many formatting functions, such write() and werror() . It is also possible to get sprintf-style compile-time argument checking by using the type-attributes sprintf_format or strict_sprintf_format in combination with sprintf_args .

Note

The 'q' operator was added in Pike 7.7.

Note

Support for specifying modifiers via a mapping was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_STAR_MAPPING__ .

Note

Support for specifying little endian byte order to 'F' was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_NEGATIVE_F__ .

Example

Pike v7.8 release 263 running Hilfe v3.5 (Incremental Pike Frontend)
 > sprintf("The unicode character %c has character code %04X.", 'A', 'A');
 (1) Result: "The unicode character A has character code 0041."
 > sprintf("#%@02X is the HTML code for purple.", Image.Color.purple->rgb());
 (2) Result: "#A020F0 is the HTML code for purple."
 > int n=4711;
 > sprintf("%d = hexadecimal %x = octal %o = %b binary", n, n, n, n);
 (3) Result: "4711 = hexadecimal 1267 = octal 11147 = 1001001100111 binary"
 > write(#"Formatting examples:
 Left adjusted  [%-10d]
 Centered       [%|10d]
 Right adjusted [%10d]
 Zero padded    [%010d]
 ", n, n, n, n);
 Formatting examples:
 Left adjusted  [4711      ]
 Centered       [   4711   ]
 Right adjusted [      4711]
 Zero padded    [0000004711]
 (5) Result: 142
 int screen_width=70;
 > write("%-=*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.
 (6) Result: 355
 > write("%-=*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.
 (7) Result: 426
 > write("%-$*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.
 (8) Result: 312
 > write("%-#*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.
 (9) Result: 312
 > sample = ([ "align":"left", "valign":"middle" ]);
 (10) Result: ([ /* 2 elements */
          "align":"left",
          "valign":"middle"
        ])
 > write("<td%{ %s='%s'%}>\n", (array)sample);
 <td valign='middle' align='left'>
 (11) Result: 34
 >  write("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
 (12) Result: 106
 > write("%[0]d, %[0]x, %[0]X, %[0]o, %[0]c\n", 75);
 75, 4b, 4B, 113, K
 (13) Result: 19
 > write("%|*s\n",screen_width, "THE END");
                                THE END
 (14) Result: 71
 > write("%|*s\n", ([ "width":screen_width ]), "ALTERNATIVE END");
                            ALTERNATIVE END
 (15) Result: 71

See also

lfun::_sprintf() , strict_sprintf_format , sprintf_format , sprintf_args , String.__HAVE_SPRINTF_STAR_MAPPING__ , String.__HAVE_SPRINTF_NEGATIVE_F__ .