sprintf()

Return the specified format as a character string to a destination.

Syntax

sprintf(format)

Parameter

Parameter

Definition

format

text, variable names, and control characters that specify the content and format of the character string output to the computer or task output window The format permits the following conversion characters: 
%d signed decimal (identical to %i) 
%i signed decimal (identical to %d) 
%u unsigned decimal 
%o unsigned octal 
%x unsigned hexadecimal using abcedf 
%X unsigned decimal using ABCDEF 
%c unsigned character 
%s character string 
%e double-precision form drddde ± ddd where each d is a digit and r is the radix character 
%E double-precision form drdddE ± ddd where each d is a digit and r is the radix character 
%f decimal notation form dddrddd where each d is a digit and r is the radix character 
%g print in the style of %e if the exponent after conversion is less than -4, else print in style %f 
%G print in the style of %E with the precision specifying the number of significant digits 
%N group digits into threes and separate with commas beginning at the right of the string 
%% print a % character 
The format does not support he standard C pointer conversion characters %p and %n.

format 
(continued)

The format permits the following flags: 
- left-justify and pad on the right with spaces 
+ display plus sign when value is greater than zero 
0 pad with zeros if no other padding is specified 
# alters the meaning of a conversion: appends 0x or 0X to the %x and %X conversions always appends the radix character to the %e, %E, %f, %g, and %G conversions retains trailing zeros in the %g and %G conversions 
The # flag does not affect the %c, %d, %s, or %i conversions.

Description

The sprintf() function is identical to the printf() function except that it returns the created string rather than outputting it to the PATROL Console. If there is an error in format, sprintf sets the PSL errno variable and returns the NULL string. 

The formats, conversions, and values of errno for the various errors are identical to those described for the printf() function. 

C programmers should be careful to use the PSL style: 

destination=sprintf(format)

rather than the C-style: 

sprintf(destination,format)

The latter style will often cause a compilation warning about a null-effect statement.

C Conventions Not Supported by the PSL sprintf Function

The sprintf() function does not support the C convention of using the asterisk (*) as a field width or precision indicator. The sprintf() function does not support the %p and %n conversion characters. 

The length modifiers h, l (ell), and L are not valid and are ignored by the sprintf() function. 

The sprintf() function format conversions are passed directly to the C library sprintf() routine on each platform. The output for obscure formatting features may differ across platforms, especially on platforms with libraries that do not conform to ANSI C requirements.

Conversion Differences between the C sprintf Routine and PSL sprintf Function

The format conversions have the same meaning between standard C and PSL, but the concept of variable types differs between the two. 

PSL supports only string types for its variables, and thus string arguments to the sprintf() function are converted in a manner appropriate for the format conversion:

  • Integral formats, such as %d, convert the string to signed integers.
  • Noninteger numeric formats, such as %f, convert to floating point values.
  • %c prints the ASCII equivalent of its integer argument, or for nonnumeric arguments, the first character of its argument. (Applying %c to "65" will print 'A' and to "AB" will print 'A'.)
  • %s causes no conversion.
  • %% requires no argument.

The %N Format Conversion

The sprintf() function provides one nonstandard C extension--the %N conversion. The %N conversion preprocesses a numeric string so that commas separate each group of three digits beginning at the right side of the string. 

For example, the %N conversion causes the following conversions: 

1234 ⇒ 1,234 12345 ⇒ 12,345 123456 ⇒ 123,456 

The %N conversions ignores initial minus signs and blanks while searching for the first sequence of digits so that %N can be applied to negative values. If no digits are found after the skipped characters, the printed argument is unchanged. 

The %N conversion only modifies the first sequence of digits. For example, the %N conversion changes floating point numbers like 1234.1234 to become 1,234.1234 without changing to the digit sequence to the right of the decimal point. 

As part of the %N conversion, the sprintf() function performs a %s conversion using the field width and precision specifiers supplied in format. The sprintf() function prints the string resulting from the combined %N and %s conversions. Because of the embedded %s conversion, field width and precision under %N conversion have the same effect as with %s.

Note

Currently, no localization is supported by %N, and so the formatting achieved by %N does not change in different locales. 

Example

The following PSL script uses the sprintf() statement to recursively build a formatted decimal/octal/hexadecimal conversion table before printing it.

 

function main() {
i = 0;
string = sprintf(" n Oct Hex\n");
string = sprintf("%s--- ---- ----\n",string);
while (i++ <= 25) {
string = sprintf("%s%3d %4o %4X\n",string,i,i,i);
}
print(string);
return;
}

 

The example produces the following output:

n Oct Hex
--- ---- ----
1 1 1
2 2 2
3 3 3
4 4 4
5 5 5
6 6 6
7 7 7
8 10 8
9 11 9
10 12 A
11 13 B
12 14 C
13 15 D
14 16 E
15 17 F
16 20 10
17 21 11
18 22 12
19 23 13
20 24 14
21 25 15
22 26 16
23 27 17
24 30 18
25 31 19