&sprintf(4)

NAME

&sprintf - Formatted string construction

SYNOPSIS

&sprintf format args

DESCRIPTION

The &sprintf function (or &spr in it's abbreviated form) provides a mechanism to generated a formatted string, similar to the 'C' programming language sprintf(2) function.

The &sprintf function is generally used where a number of different sources of information have to be converted and joined together to form a new string. It is possible to do this using &cat(4), but it does become complicated if the number of strings to be spliced together is greater than about 4, sprintf alleviates these problems and results in faster execution. Where only two, or three strings are to be concatenated &cat provides better execution times.

The &sprintf function produces a string construct for the format and a caller determined number of arguments args (variable arguments). The format string may contain special '%' formatting commands to insert strings and numbers into the base format string. The format for the '%' commands is "%nc" where:

n


An optional numerical argument, the interpretation of the numeric value is determined by the following command (c). As in 'C' it may be preceded by a minus sign, and may be followed by a full stop and a second number.

c


The command determines the interpretation of the next argument arg which are specified as follows:

d (Decimal integer)


Expects a single numeric argument arg which is inserted into the format string as decimal text string. If n is specified then the inserted text string is fixed to n character in length, if n is prefixed with a 0 then the number is padded with zeros otherwise spaces are used.

e (floating point number - scientific)

f (floating point number)

g (floating point number - shorter of e or f)


Expects a single numeric argument arg which is inserted into the format string as a floating point number string. If n is specified it must be of the form [min-width][.<precision>] where either the [min-width] or the [.<precision>] can be omitted.

n (Repeat String)


Expects two arguments arg, the first is a numeric argument giving the number of times to insert the given string (the second argument). The optional argument n is ignored if specified.

o (Octal integer)


Expects a single numeric argument arg which is inserted into the format string as an octal text string. If n is specified then the inserted text string is fixed to n character in length, if n is prefixed with a 0 then the number is padded with zeros otherwise spaces are used.

s (String)


Expects a single argument arg which is a string to be inserted into the format string. If n is given it is the minimum field width and the string is padded with spaces on the left, or on the right when n is prefixed with a '-'. A '.' followed by a number gives the maximum number of characters to take from the string. To insert a string more than once use the n command.

x (Hexadecimal integer)


Expects a single numeric argument arg which is inserted into the format string as hexadecimal text string. If n is given then the inserted text string will be fixed to n character in length, if n is prefixed with a 0 then the number is padded with zeros otherwise spaces are used.

X (Hexadecimal integer)


Same as x only using uppercase letters.

%


Inserts a single '%', n has no effect.

The &sprintf function may be nested (i.e. a string argument to &sprintf may be the result of another &sprintf invocation). Although this type of construct is not generally required !!

EXAMPLE

The following examples show how the command may be used:

set-variable %result &sprintf "Foo [%s%s]" "a" "b" 

generates "Foo [ab]"

set-variable %result &sprintf "Foo [%n%s]" 10 "a" "b" 

generates "Foo [aaaaaaaaaab]".

set-variable %result &sprintf "[%d] [%3d] [%x] [%3x]" 10 11 12 13 

generates "[10] [ 11] [c] [  d]"

NOTES

It is the callers responsibility to ensure that the correct number of arguments is supplied to match the requested formatting string. The results are undefined if an incorrect number of arguments are supplied.

An error will be thrown if the % command is not one of the supported ones listed above.

COMPATIBILITY

Prior to August 2026 the s command treated n as a repeat count rather than a field width, so "%13s" inserted the string thirteen times. Macros written against the older behaviour must be changed to use the n command, which is unaffected:

; before - inserted the box character 13 times 
set-variable %line &sprintf "%13s" %box-char 
; now 
set-variable %line &sprintf "%n" 13 %box-char 

A "%" followed by digits and an "s" is the construct to look for.

SEE ALSO

Variable Functions, &cat(4).

Ref: &sprintf(4) File: m4fil004.4 Date: 2026/08/07

(c) Copyright JASSPA 2026