# 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"` : `bool`|`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

See also

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