String formatting functions

Cross-platform sprintf support with RIP related extensions. More...

Files
file	swcopyf.h
	Header file defining String formatting functions.

Functions
int32	vswcopyf (uint8 *destination, const uint8 *format, va_list ap)
	Equivalent to vsprintf. More...
int32	swcopyf (uint8 *destination, const uint8 *format,...)
	Equivalent to sprintf. More...
int32	vswncopyf (uint8 *destination, int32 len, const uint8 *format, va_list ap)
	Equivalent to vsnprintf. More...
int32	swncopyf (uint8 *destination, int32 len, const uint8 *format,...)
	Equivalent to snprintf. More...
int32	swncopyduration (uint8 *destination, int32 len, int32 millisecs)
	Format a duration, expressing in hours, minutes, and seconds, and also summarised in a machine-parseable format. More...

Detailed Description

Cross-platform sprintf support with RIP related extensions.

The format string supported by swcopyf() and related functions is a sequence of ordinary characters and conversion specifications, introduced by '%'. Conversion specifications have the general form:

%[flags][width][.precision][size|escape]type

Conversion specifications usually consume one or more arguments from the variable argument list supplied. The variable argument list must be supplied with the correct number and types of values to match the format.

The flags are output modifiers that change signs, justification, etc. The flags supported by swcopyf() and related functions are:

' ' (one space character)

For decimal output, if the number is positive leave a space in front of the number instead of left-justifying.

+

For decimal output, put either a plus or minus sign in front of the number.

-

Left justify output within the field width.

#

Use an alternate form of output, if supported by the type. This option is supported for types o, x, X, e, E, f, F, g and G.

0

If the output is shorter than the field width and right-justifying, pad the characters at the left of the output with zero instead of spaces.

=

Use binary token output, if supported by the type (GGS extension). No other flags are permitted when using this option. This option is supported for types i, d, e, E, f, F, g and G.

The width part of the conversion specification is a minimum field width. If the output would be shorter than this width, it is padded with spaces (or zeros, if right justified and the '0' flag is used for numerics), either to the left or right of the output, depending on the justification flag. If the output is longer than the width specified, it will continue to its normal width. The width can be specified directly using a decimal number, or indirectly by '*'. An indirect width specification consumes the next argument as an int32 to supply the width. If a negative width is provided through an indirect width, the output is left-justified.

The precision part of the conversion limits the size of the output. For strings, the precision truncates the width of the output at the precision. For integral values, the precision determines the minimum number of digits to output. For real values, the precision determines the number of significant digits (for 'g' and 'G' types), or the number of digits to appear after the decimal point (for 'e', 'E', 'f', and 'F' types). The precision can be specified directly using a period followed by a decimal number, or indirectly by '.*'. An indirect precision specification consumes the next argument as an int32 to supply the precision.

The size part of the specification determines the size of the argument taken from the variable argument list. The size specifications supported by swcopyf() and related functions are:

h

The argument is the size of a short.

l

The argument is the size of a long.

P

The argument is the size of a pointer (GGS extension).

z

The argument is the size of a size_t.

The size part is optional, so omitting it will interpret the argument as the size of an int, for numeric output. The size modifier does not apply to all types of conversion.

Other printf sizes (hh, ll, L, j and t) are not supported.

String conversions may use an escape modifier instead of a size (GGS extension). The escape modifier is introduced by '!', and may optionally be followed by '7' or '8'. The meanings of these modifiers are:

!

Escape characters '(', ')', and '\' required for representation as a PostScript string, passing through control characters and high-bit characters unmodified.

!7

Escape characters '(', ')', and '\' required for representation as a PostScript string, representing control characters 0-31, 127, and high-bit characters 128-255 as octal sequences. This is a 7-bit clean representation.

!8

Escape characters '(', ')', and '\' required for representation as a PostScript string, representing control characters 0-31 and 127 as octal sequences, but leaving high-bit characters 128-255 as-is. This is an 8-bit clean representation.

The type of the conversion specification is a single character:

%

Write a literal percent '%' character.

s

Write a (uint8 *) pointer as a string, excluding the terminating NUL. May be modified by width, precision, '!', '-'.

c

Write an int as a character. May be modified by width, '-'.

o

Write a short, int, long, or pointer as an octal number. May be modified by width, precision, size, '#'. The alternate form when using the '#' modifier adds a leading zero digit if there would not be one otherwise.

x

Write a short, int, long, or pointer as a hexadecimal number, using lower case letters. May be modified by width, precision, size, '#'. The alternate form when using the '#' modifier adds a leading "0x" to a nonzero value.

X

Write a short, int, long, or pointer as a hexadecimal number, using upper case letters. May be modified by width, precision, size, '#'. The alternate form when using the '#' modifier adds a leading "0X" to a nonzero value.

p

Write a pointer as a hexadecimal number, with a leading "0x", using lower case letters. May be modified by width, precision.

i

Write a short, int, long, size, or pointer as a decimal number. May be modified by width, precision, size, ' ', '+', '0'. This is synonymous with the 'd' type. Binary token format (high order byte first) using the '=' modifier is supported.

d

Write a short, int, long, size, or pointer as a decimal number. May be modified by width, precision, size, ' ', '+', '0'. This is synonymous with the 'i' type. Binary token format (high order byte first) using the '=' modifier is supported.

u

Write a short, int, long, size, or pointer as an unsigned decimal number. May be modified by width, precision, size, ' ', '+', '0'.

e

Write a promoted_real as a signed value using the exponent form [-]9.9999e[+|-]999. The digit before the decimal point is non-zero if the value is non-zero. The precision determines how many digits appear between the decimal point and the exponent character. The value zero has an exponent of zero. The alternate form when using the '#' modifier always contains a decimal point, even if no digits follow it. Binary token format (machine byte order) using the '=' modifier is supported.

E

Similar to 'e', but uses capital E for the exponent character.

f

Write a promoted_real as a signed value using the non-exponent form [-]9999.9999. The precision determines how many digits follow the decimal point. The alternate form when using the '#' modifier always contains a decimal point, even if no digits follow it. Binary token format (machine byte order) using the '=' modifier is supported.

F

Synonymous with 'f'.

g

Write a promoted_real in either the 'e' or 'f' form, based on the value and precision. An exponent less than -4 or greater than the precision selects the 'e' form. Trailing zeros and the decimal point are printed only if necessary. The alternate form when using the '#' modifier always contains a decimal point, even if no digits follow it, and trailing zeros are not removed. Binary token format (machine byte order) using the '=' modifier is supported.

G

Write a promoted_real in either the 'E' or 'F' form, based on the value and precision. An exponent less than -4 or greater than the precision selects the 'E' form. Trailing zeros and the decimal point are printed only if necessary. The alternate form when using the '#' modifier always contains a decimal point, even if no digits follow it, and trailing zeros are not removed. Binary token format (machine byte order) using the '=' modifier is supported.

N

Do not add the trailing NUL to the destination buffer (GGS extension). This does not change the number of characters returned by swncopyf() or vswncopyf(), just whether the trailing NUL is output.

No other conversion specification characters should be used in the format string. Global Graphics may extend the conversions supported at any time, using other conversion specification characters.

The printf conversions a, A and n are not supported.

Function Documentation

swcopyf()

int32 swcopyf	(	uint8 *	destination,
		const uint8 *	format,
			...
	)

Equivalent to sprintf.

Parameters

[out]	destination	A pointer to a buffer to which output will be stored. Since this function does not perform length validation, the caller must supply a buffer of sufficient length for any possible output.
[in]	format	A sprintf-like format string, describing the fixed and variable portions of the data stored in destination.
[in]	...	A variable-length list of arguments, interpreted according to format.

Returns

The number of characters written.

It is recommended that swncopyf() is used instead of this function.

swncopyduration()

int32 swncopyduration	(	uint8 *	destination,
		int32	len,
		int32	millisecs
	)

Format a duration, expressing in hours, minutes, and seconds, and also summarised in a machine-parseable format.

This is used to format durations expressed in the RIP's monitor output.

Parameters

[out]	destination	A pointer to a buffer to which output will be stored.
[in]	len	The size of the buffer pointed to by destination.
[in]	millisecs	A non-negative duration, expressed in milliseconds.

Returns

The number of characters that would have been written without consideration of the buffer length, excluding the terminating NUL character. The actual number of characters written is limited to len, including a terminating NUL, so the buffer length must be one greater than the returned length to ensure that the string was written in its entirety.

swncopyf()

int32 swncopyf	(	uint8 *	destination,
		int32	len,
		const uint8 *	format,
			...
	)

Equivalent to snprintf.

Parameters

[out]	destination	A pointer to a buffer to which output will be stored.
[in]	len	The size of the buffer pointed to by destination.
[in]	format	A sprintf-like format string, describing the fixed and variable portions of the data stored in destination.
[in]	...	A variable-length list of arguments, interpreted according to format.

Returns

The number of characters that would have been written without consideration of the buffer length, excluding the terminating NUL character. The actual number of characters written is limited to len, including a terminating NUL, so the buffer length must be one greater than the returned length to ensure that the string was written in its entirety.

vswcopyf()

int32 vswcopyf	(	uint8 *	destination,
		const uint8 *	format,
		va_list	ap
	)

Equivalent to vsprintf.

Parameters

[out]	destination	A pointer to a buffer to which output will be stored. Since this function does not perform length validation, the caller must supply a buffer of sufficient length for any possible output.
[in]	format	A sprintf-like format string, describing the fixed and variable portions of the data stored in destination.
[in]	ap	A handle to a variable-length list of arguments, interpreted according to format.

Returns

The number of characters written.

It is recommended that vswncopyf() is used instead of this function.

vswncopyf()

int32 vswncopyf	(	uint8 *	destination,
		int32	len,
		const uint8 *	format,
		va_list	ap
	)

Equivalent to vsnprintf.

Parameters

[out]	destination	A pointer to a buffer to which output will be stored.
[in]	len	The size of the buffer pointed to by destination.
[in]	format	A sprintf-like format string, describing the fixed and variable portions of the data stored in destination.
[in]	ap	A handle to a variable-length list of arguments, interpreted according to format.

Returns

The number of characters that would have been written without consideration of the buffer length, excluding the terminating NUL character. The actual number of characters written is limited to len, including a terminating NUL, so the buffer length must be one greater than the returned length to ensure that the string was written in its entirety.