xprintf Family of Functions
[lite xformat - A C++ printf/scanf style IO library]

Functions
template<typename _char_type , typename _traits_type , typename _argument1_type , ... , typename _argumentN_type >
std::basic_ostream< _char_type, _traits_type > &	lite::xprintf (std::basic_ostream< _char_type, _traits_type > &os, const _char_type *format, const _argument1_type &arg1,..., const _argumentN_type &argN)
template<typename _char_type , typename _traits_type , typename _argument1_type , ... , typename _argumentN_type >
std::basic_string< _char_type >	lite::xprintf (const _char_type *format, const _argument1_type &arg1,..., const _argumentN_type &argN)
template<typename _char_type , typename _traits_type , typename _argument_iter_type >
std::basic_ostream< _char_type, _traits_type > &	lite::xprintf_range (std::basic_ostream< _char_type, _traits_type > &os, const _char_type *format_begin, const _char_type *format_end, _argument_iter_type first, _argument_iter_type last)
template<typename _char_type , typename _traits_type , typename _argument_iter_type >
std::basic_ostream< _char_type, _traits_type > &	lite::xprintf_range (std::basic_ostream< _char_type, _traits_type > &os, const _char_type *format, _argument_iter_type first, _argument_iter_type last)
template<typename _char_type , typename _traits_type , typename _argument_type >
std::basic_ostream< _char_type, _traits_type > &	lite::xprintf_one (std::basic_ostream< _char_type, _traits_type > &os, const _char_type *fmt_begin, const _char_type *fmt_end, const _argument_type &argument)

---

Detailed Description

prints the arguments using the specified format string.

These functions use a printf style format string which can use both Standard and Extended format fields. In both cases, each argument is printed by a call to an appropriate overload of xprintf_one() function.

Standard Format Field

The standard format has the following pattern:

%[arg_pos$][flags][width][.precision][h|H|l|L|i|I]type

Each format string may cause certain stream flags to be set or cleared and the precision and/or width variable of the stream to be set. The goal has been to support all features that can be easily simulated using the iostream formatting facilities. Features that have no direct equivalent for iostreams are not supported.

The arg_pos is the positional argument specifying the index of the argument to be printed. The first argument (i.e. arg1) has index 1. using a positional argument also changes the current argument index so the next argument to be printed by the next format field will be arg_pos+1.

The following flags are supported:

• '-' left align.
  • clears: std::ios_base::adjustfield
  • sets: std::ios_base::left
• ' ' prefix with a blank if positive.
  • clears: std::ios_base::adjustfield
  • sets: std::ios_base::internal
• '+' prefix with a '+' if positive.
  • sets: std::ios_base::showpos
• '#' show the base for hexadecimal and octal numbers. Can also be used to enable showpoint and boolalpha.
  • sets: std::ios_base::showpoint, std::ios_base::showbase, std::ios_base::boolalpha
• '0' is ignored.

The width and precision simply sets the stream precision and the field width for the next formatted output of the stream.

All the type prefixes (i.e. 'h', 'H', 'l', ...) are ignored.

The type characters simply set/clear some of the stream flags. The actual type of the argument will be used by the stream for printing. The following type characters are supported:

• 'c', 'C', 'p', 's', 'S' are ignored.
• 'd', 'i', 'u' integer numbers will be printed in decimal.
  • clears: std::ios_base::basefield
  • sets: std::ios_base::dec
• 'o' integer numbers will be printed in octal.
  • clears: std::ios_base::basefield
  • sets: std::ios_base::oct
• 'x' integer numbers will be printed in hexadecimal using lowercase letters.
  • clears: std::ios_base::basefield, std::ios_base::uppercase
  • sets: std::ios_base::hex
• 'X' integer numbers will be printed in hexadecimal using uppercase letters.
  • clears: std::ios_base::basefield
  • sets: std::ios_base::hex, std::ios_base::uppercase
• 'e','a' floating point numbers will be printed in scientific format using 'e' letter.
  • clears: std::ios_base::floatfield, std::ios_base::uppercase
  • sets: std::ios_base::scientific
• 'E','A' floating point numbers will be printed in scientific format using 'E' letter.
  • clears: std::ios_base::floatfield
  • sets: std::ios_base::scientific, std::ios_base::uppercase
• 'g' floating point numbers will be printed in the shortest of fixed or scientific format using 'e' letter.
  • clears: std::ios_base::floatfield, std::ios_base::uppercase
• 'G' floating point numbers will be printed in the shortest of fixed or scientific format using 'E' letter.
  • clears: std::ios_base::floatfield, std::ios_base::uppercase
• 'n' is ignored and the corresponding argument is skipped.

Extended Format Field

In the extended format, a user defined format string is used to format the argument.

%[arg_pos$]{fmt}

The format string fmt is enclosed in braces and can be any arbitrary string which is balanced with respect to '{' and '}'. This allows for nesting of format fields. The fmt is then passed to the appropriate overload of the xprintf_one() function for processing. The xprintf_one() will do the actual printing.

Example:

        xprintf(std::cout, "%.4f %5s %1$f", 34.34, "hello");
        xprintf(std::cout, "%.4s %5d %1$f", 34.34, "hello"); // gives the same result
        
        Date d; // assume that xprintf_one() is defined for the Date class.
        xprintf(std::cout, "The date is : %{%m/%d/%y}, temperature is : %d", d, 80); // uses the extended format

Remarks:

The precision and flags of the stream are saved at the beginning and restored to their initial value upon exiting the function even if the function exits due to an exception. Also, the stream flags and precision value are reset to their saved value before processing any of the format fields. However, for standard format fields, the flags are reset to the default stream values.

---

Function Documentation

template<typename _char_type , typename _traits_type , typename _argument1_type , ... , typename _argumentN_type >

std::basic_string<_char_type> lite::xprintf	(	const _char_type *	format,
		const _argument1_type &	arg1,
			...,
		const _argumentN_type &	argN
	)			[inline]

Prints arg1 ... argN to a string using the format string specified by format and then return the string.

Parameters:

	format	The format string
	argI	I-th argument where I is 1,2, ... N

Returns:

Returns the resulting string

Remarks:

Note that this function does not throw any exception. Instead, it silently ignores any error. and the printing stops as soon as an error is encountered.

template<typename _char_type , typename _traits_type , typename _argument1_type , ... , typename _argumentN_type >

std::basic_ostream<_char_type, _traits_type>& lite::xprintf	(	std::basic_ostream< _char_type, _traits_type > &	os,
		const _char_type *	format,
		const _argument1_type &	arg1,
			...,
		const _argumentN_type &	argN
	)			[inline]

Prints arg1 ... argN to output stream os using the format string specified by format and then return the stream.

Parameters:

	os	The target output stream
	format	The format string
	argI	I-th argument where I is 1,2, ... N

Returns:

Returns the same output stream os

Exceptions:

format_error,argument_index_error

template<typename _char_type , typename _traits_type , typename _argument_type >

std::basic_ostream< _char_type, _traits_type > & lite::xprintf_one	(	std::basic_ostream< _char_type, _traits_type > &	os,
		const _char_type *	fmt_begin,
		const _char_type *	fmt_end,
		const _argument_type &	argument
	)			[inline]

Prints the argument argument to output stream os using the user defined format string specified by the range [fmt_begin, fmt_end). The default implementation of this function ignores the format string and simply uses the << operator to print argument to the output stream. This function can be overloaded to allow handling of user defined format strings.

template<typename _char_type , typename _traits_type , typename _argument_iter_type >

std::basic_ostream< _char_type, _traits_type > & lite::xprintf_range	(	std::basic_ostream< _char_type, _traits_type > &	os,
		const _char_type *	format,
		_argument_iter_type	first,
		_argument_iter_type	last
	)			[inline]

Prints the arguments in the range [first, last) to output stream os using the format string specified by format and then return the stream.

Parameters:

	os	The target output stream
	format	pointer to the the format string
	first	iterator to the first argument
	last	iterator to one past the last argument

Returns:

Returns the same output stream os

Exceptions:

format_error,argument_index_error

template<typename _char_type , typename _traits_type , typename _argument_iter_type >

std::basic_ostream< _char_type, _traits_type > & lite::xprintf_range	(	std::basic_ostream< _char_type, _traits_type > &	os,
		const _char_type *	format_begin,
		const _char_type *	format_end,
		_argument_iter_type	first,
		_argument_iter_type	last
	)			[inline]

Prints the arguments in the range [first, last) to output stream os using the format string specified by the range [format_begin, format_end) and then return the stream.

Parameters:

	os	The target output stream
	format_begin	pointer to the beginning of the format string
	format_end	pointer to one past the end of the format string
	first	iterator to the first argument
	last	iterator to one past the last argument

Returns:

Returns the same output stream os

Exceptions:

format_error,argument_index_error