&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).

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.

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). If n is specified then the string is inserted n * numeric-argument times.

s (String)


Expects a single argument arg which is a string to be inserted into the key. If n is given then it is insertedn times.

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.

%


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.

SEE ALSO

Variable Functions, &cat(4).

(c) Copyright JASSPA 1999
Last Modified: 1998/09/02
Generated On: 1999/12/01