Type-safe formatting, modeled on the Python str.format function. More...

#include "UT_API.h"
#include "UT_Assert.h"
#include "UT_NonCopyable.h"
#include <SYS/SYS_Types.h>
#include <initializer_list>
#include <iosfwd>
#include <limits>
#include <string>
#include <type_traits>

Include dependency graph for UT_Format.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	UT::Format::CustomWriter

struct	UT::Format::Writer

struct	UT::Format::Impl::TrueType< typename >

struct	UT::Format::HasFormat< T >

class	UT::Format::ArgValue

struct	UT::Format::ArgValue::SizedString

struct	UT::Format::ArgValue::Custom

class	UT::Format::Formatter

Namespaces
	UT

	UT::Format

	UT::Format::Impl

Macros
#define	UT_ENABLE_IF(T) typename std::enable_if<T>::type * = nullptr

#define	UT_HAS_FMT(T) HasFormat<T>::value

#define	UT_REMOVE_PTR(T) typename std::remove_pointer<T>::type

#define	UT_IS_PTR(T) std::is_pointer<T>::value

#define	UT_IS_ENUM(T) std::is_enum<T>::value

Functions
UT_API size_t	UT::Format::format (FILE file, const char format, std::initializer_list< ArgValue > args)

UT_API size_t	UT::Format::format (std::ostream &, const char *format, std::initializer_list< ArgValue > args)

UT_API size_t	UT::Format::format (char , size_t, const char format, std::initializer_list< ArgValue > args)

UT_API size_t	UT::Format::printf (FILE file, const char format, std::initializer_list< ArgValue > args)

UT_API size_t	UT::Format::printf (std::ostream &, const char *format, std::initializer_list< ArgValue > args)

UT_API size_t	UT::Format::printf (char , size_t, const char format, std::initializer_list< ArgValue > args)

Standalone formatting functions
template<typename... Args>
size_t	UTformat (FILE file, const char format, const Args &...args)

template<typename... Args>
size_t	UTformat (const char *format, const Args &...args)

template<typename... Args>
size_t	UTformat (std::ostream &os, const char *format, const Args &...args)

template<typename... Args>
size_t	UTformat (char buffer, size_t buffer_size, const char format, const Args &...args)

Standalone printf-like functions
template<typename... Args>
size_t	UTprintf (FILE file, const char format, const Args &...args)

template<typename... Args>
size_t	UTprintf (const char *format, const Args &...args)

template<typename... Args>
size_t	UTprintf (std::ostream &os, const char *format, const Args &...args)

template<typename... Args>
size_t	UTprintf (char buffer, size_t buffer_size, const char format, const Args &...args)

Detailed Description

Type-safe formatting, modeled on the Python str.format function.

This formatter supports a sub-set of the Python format syntax. Notably, only indexed arguments are supported for now, not named ones.

Like with the printf() formatting, the format string contains replacement fields that will be substituted by the textual representation of the arguments to the various format functions. The replacement fields for this formatter are surrounded by curly braces {}, rather than prefixed with a %.

Note the string {{ or }} will result in a single { or } being output.

Format Grammar

The grammar for the replacement field is as follows:

{[<index>][:<spec>]}

The <index> is an optional integer value, which refers to the position of the argument after the format string. If the <index> is omitted for all replacement fields, then they are automatically substituted with 0, 1, 2, ... It is not permitted to mix indexed and non-indexed.

If a colon separator is found, the string after that is interpreted as a formatting specification. The grammar for the <spec> field is as follows:

[[<fill>]<align>][<sign>][#][,][0][<width>][.<precision>][<type>]

Where:

<fill> is the fill character to use when the width of the field is greater than the length of the argument value being printed.
<align> is a single character code which sets the alignment of the value within the field:
- <: The field is left-aligned. This is the default for non-numeric values.
- >: The field is right-aligned. This is the default for numeric values.
- ^: The field is center-aligned.
- =: The field is number aligned. This is the same as right-aligned, except the fill value is inserted between the sign indicator and the numeric value. This alignment is only available for numeric values.
<sign> is a single character that specifies how the sign is printed for numeric values:
- +: Always print a sign, whether positive or negative.
- -: Only print a sign when the number is negative.
- <space>: Use a leading space on positive numbers, minus sign for negative.
The '#' option is only available for binary, octal or hexadecimal output. It indicates that they should be prefixed with '0b', '0' and '0x', respectively.
The ',' option will add digit grouping to numerical outputs. For float

Definition in file UT_Format.h.

Macro Definition Documentation

#define UT_ENABLE_IF ( T ) typename std::enable_if<T>::type * = nullptr

Definition at line 319 of file UT_Format.h.

#define UT_HAS_FMT ( T ) HasFormat<T>::value

Definition at line 320 of file UT_Format.h.

#define UT_IS_ENUM ( T ) std::is_enum<T>::value

Definition at line 323 of file UT_Format.h.

#define UT_IS_PTR ( T ) std::is_pointer<T>::value

Definition at line 322 of file UT_Format.h.

#define UT_REMOVE_PTR ( T ) typename std::remove_pointer<T>::type

Definition at line 321 of file UT_Format.h.

Function Documentation

template<typename... Args>

size_t UTformat	(	FILE *	file,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to the FILE pointer.

Parameters

file	The `FILE` pointer to write to. The FILE must be opened in write or append mode.
format	The formatting codes, as defined in Format Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Examples:: IMG/TIL_NullFilter.C.

Definition at line 657 of file UT_Format.h.

template<typename... Args>

size_t UTformat	(	const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to stdout.

Parameters

format	The formatting codes, as defined in Format Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 668 of file UT_Format.h.

template<typename... Args>

size_t UTformat	(	std::ostream &	os,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to the output stream object.

Parameters

os	The output stream to write to.
format	The formatting codes, as defined in Format Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 680 of file UT_Format.h.

template<typename... Args>

size_t UTformat	(	char *	buffer,
		size_t	buffer_size,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string into the buffer provided. If buffer is nullptr, then nothing is written out, but the number of bytes needed to store the entire formatted string is returned. A termination byte is not written out to the buffer. If termination is required, the caller must take care of it.

Parameters

buffer	The character buffer to write the formatted string to.
buffer_size	The size of the character buffer.
format	The formatting codes, as defined in Format Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 697 of file UT_Format.h.

template<typename... Args>

size_t UTprintf	(	FILE *	file,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to the FILE pointer.

Parameters

file	The `FILE` pointer to write to. The FILE must be opened in write or append mode.
format	The formatting codes, as defined in Printf Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 716 of file UT_Format.h.

template<typename... Args>

size_t UTprintf	(	const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to stdout.

Parameters

format	The formatting codes, as defined in Printf Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 727 of file UT_Format.h.

template<typename... Args>

size_t UTprintf	(	std::ostream &	os,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string to the output stream object.

Parameters

os	The output stream to write to.
format	The formatting codes, as defined in Printf Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 739 of file UT_Format.h.

template<typename... Args>

size_t UTprintf	(	char *	buffer,
		size_t	buffer_size,
		const char *	format,
		const Args &...	args
	)

Takes a formatting string and a set of arguments and writes out the formatted string into the buffer provided. If buffer is nullptr, then nothing is written out, but the number of bytes needed to store the entire formatted string is returned. A termination byte is not written out to the buffer. If termination is required, the caller must take care of it.

Parameters

buffer	The character buffer to write the formatted string to.
buffer_size	The size of the character buffer.
format	The formatting codes, as defined in Printf Grammar.
args	The arguments to the formatting.

Returns: The number of bytes successfully written out.

Definition at line 756 of file UT_Format.h.

Classes

Namespaces

Macros

Functions

Detailed Description

Format Grammar

Macro Definition Documentation

Function Documentation