String Formatting

Methods for creating and outputting formatted strings. More...

Collaboration diagram for String Formatting:

Typedefs
typedef const char *(*	sys_printf_format_handler_t) (char format, va_list *va)
	Custom format handler function type. More...

Functions
void	sys_puts (const char *str)
	Outputs a string to the system console or standard output. More...
void	sys_putch (const char ch)
	Outputs a character to the system console or standard output. More...
size_t	sys_printf (const char *format,...)
	Prints formatted output to the system console. More...
size_t	sys_vprintf (const char *format, va_list args)
	Prints formatted output using a va_list argument. More...
size_t	sys_sprintf (char *buf, size_t sz, const char *format,...)
	Prints formatted output to a string buffer. More...
size_t	sys_vsprintf (char *buf, size_t sz, const char *format, va_list args)
	Prints formatted output to a string buffer using a va_list argument. More...
size_t	sys_vprintf_ex (const char *format, va_list args, sys_printf_format_handler_t custom_handler)
	Prints formatted output using a va_list argument with custom format handler support. More...
size_t	sys_vsprintf_ex (char *buf, size_t sz, const char *format, va_list args, sys_printf_format_handler_t custom_handler)
	Prints formatted output to a string buffer using a va_list argument with custom format handler support. More...
size_t	sys_sprintf_ex (char *buf, size_t sz, const char *format, sys_printf_format_handler_t custom_handler,...)
	Prints formatted output to a string buffer with custom format handler support. More...

Detailed Description

Methods for creating and outputting formatted strings.

This file declares types and functions for formatted output to the system console or to a string buffer. It supports printf-style formatting with various format specifiers, width modifiers, and flags.

The sys_printf() function is the main entry point for formatted output, and it supports a wide range of format specifiers, including integers, strings, and characters. It also supports width modifiers for padding and alignment, as well as flags for zero-padding, left-alignment, and sign handling. There are also functions for formatted output of Objective-C objects and NXTimeInterval values.

The sys_sprintf() function is similar to sys_printf(), but it outputs the formatted string to a buffer instead of the console. It also supports the same format specifiers and flags, and it returns the number of characters that would have been written to the buffer, not counting the null terminator.

The format specifiers supported are:

• %c: Character
• %s: String
• %@: NXObject (Objective-C object). This only works if the Objective-C runtime is available.
• %d: Signed integer
• %u: Unsigned integer
• %x: Unsigned hexadecimal integer
• %b: Unsigned binary integer
• %o: Unsigned octal integer
• %X: Uppercase hexadecimal integer
• %t: NXTimeInterval (Objective-C time interval)
• %p: Pointer address
• %q: JSON-quoted Objective-C object
• %%: Literal percent sign

The format specifiers can be modified with flags and width:

• Width:
  • %80d: Number specifying the minimum width of the output
• Data Type:
  • %ld, %lu: long data type
  • %zu: size_t data type
• Flags:
  • %-10s: Left-aligned output
  • %05d: Zero-padded hexadecimal, decimal, octal, or binary output
  • %+d: Forces a sign for positive numbers
  • %#x, %#b, %#o: Forces a prefix for hexadecimal (0x), binary (0b) and octal (0) formats

The sys_printf() function is thread-safe and can be used from multiple threads simultaneously without additional synchronization. It was implemented to extend the use of printf to Objective-C objects and NXTimeInterval.

At the moment floating point numbers are not supported, but they may be added in the future.

Typedef Documentation

sys_printf_format_handler_t

typedef const char*(* sys_printf_format_handler_t) (char format, va_list *va)

Custom format handler function type.

Parameters

format	The format specifier character (e.g., '@' for '%@').
va	Pointer to the va_list containing the arguments.

Returns

A string representation of the formatted value, or NULL if the format specifier is not handled by this custom handler.

Definition at line 147 of file printf.h.

Function Documentation

sys_printf()

size_t sys_printf	(	const char *	format,
			...
	)

Prints formatted output to the system console.

Parameters

format	A printf-style format string that specifies how subsequent arguments are formatted and printed.
...	Additional arguments corresponding to format specifiers in format.

Returns

The number of characters printed.

Examples:

clock/main.c, examples/runtime/gpio/main.c, examples/runtime/infrared/main.c, examples/runtime/led/main.c, examples/runtime/ntp/main.c, examples/runtime/watchdog/main.c, examples/runtime/wificonnect/main.c, and examples/runtime/wifiscan/main.c.

sys_putch()

void sys_putch

(

const char

ch

)

Outputs a character to the system console or standard output.

Parameters

ch	The character to be output.

This function writes the specified character to the system's standard output stream, but does not flush the output buffer.

Examples:

clock/main.c.

sys_puts()

void sys_puts

(

const char *

str

)

Outputs a string to the system console or standard output.

Parameters

str	A pointer to a null-terminated string to be output. If str is NULL, existing output is flushed.

This function writes the specified null-terminated string to the system's standard output stream, and flushes the output buffer.

Examples:

examples/runtime/infrared/main.c.

sys_sprintf()

size_t sys_sprintf	(	char *	buf,
		size_t	sz,
		const char *	format,
			...
	)

Prints formatted output to a string buffer.

Parameters

buf	Pointer to the destination buffer where the formatted string will be stored. If NULL, only the length is calculated.
sz	Size of the destination buffer in bytes, including space for the null terminator.
format	A printf-style format string.
...	Additional arguments corresponding to format specifiers in format.

Returns

The number of characters that would have been written if the buffer was sufficiently large, not counting the null terminator.

Examples:

examples/runtime/gpio/main.c, and examples/runtime/infrared/main.c.

sys_sprintf_ex()

size_t sys_sprintf_ex	(	char *	buf,
		size_t	sz,
		const char *	format,
		sys_printf_format_handler_t	custom_handler,
			...
	)

Prints formatted output to a string buffer with custom format handler support.

Parameters

buf	Pointer to the destination buffer where the formatted string will be stored. If NULL, only the length is calculated.
sz	Size of the destination buffer in bytes, including space for the null terminator.
format	A printf-style format string.
custom_handler	Custom format handler for unsupported format specifiers, or NULL.
...	Additional arguments corresponding to format specifiers in format.

Returns

The number of characters that would have been written if the buffer was sufficiently large, not counting the null terminator.

This function is similar to sys_sprintf() but allows specifying a custom format handler that will be called for any format specifiers not handled by the built-in implementation. This enables support for custom format specifiers like '%@' for objects.

sys_vprintf()

size_t sys_vprintf	(	const char *	format,
		va_list	args
	)

Prints formatted output using a va_list argument.

Parameters

format	A printf-style format string.
args	A va_list containing the arguments for the format string.

Returns

The number of characters printed.

sys_vprintf_ex()

size_t sys_vprintf_ex	(	const char *	format,
		va_list	args,
		sys_printf_format_handler_t	custom_handler
	)

Prints formatted output using a va_list argument with custom format handler support.

Parameters

format	A printf-style format string.
args	A va_list containing the arguments for the format string.
custom_handler	Custom format handler for unsupported format specifiers, or NULL.

Returns

The number of characters printed.

This function is similar to sys_vprintf() but allows specifying a custom format handler that will be called for any format specifiers not handled by the built-in implementation. This enables support for custom format specifiers like '%@' for objects.

sys_vsprintf()

size_t sys_vsprintf	(	char *	buf,
		size_t	sz,
		const char *	format,
		va_list	args
	)

Prints formatted output to a string buffer using a va_list argument.

Parameters

buf	Pointer to the destination buffer where the formatted string will be stored. If NULL, only the length is calculated.
sz	Size of the destination buffer in bytes, including space for the null terminator.
format	A printf-style format string.
args	A va_list containing the arguments for the format string.

Returns

The number of characters that would have been written if the buffer was sufficiently large, not counting the null terminator.

sys_vsprintf_ex()

size_t sys_vsprintf_ex	(	char *	buf,
		size_t	sz,
		const char *	format,
		va_list	args,
		sys_printf_format_handler_t	custom_handler
	)

Prints formatted output to a string buffer using a va_list argument with custom format handler support.

Parameters

buf	Pointer to the destination buffer where the formatted string will be stored. If NULL, only the length is calculated.
sz	Size of the destination buffer in bytes, including space for the null terminator.
format	A printf-style format string.
args	A va_list containing the arguments for the format string.
custom_handler	Custom format handler for unsupported format specifiers, or NULL.

Returns

The number of characters that would have been written if the buffer was sufficiently large, not counting the null terminator.

This function is similar to sys_vsprintf() but allows specifying a custom format handler that will be called for any format specifiers not handled by the built-in implementation. This enables support for custom format specifiers like '%@' for objects.