xscanf 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_istream< _char_type, _traits_type > &	lite::xscanf (std::basic_istream< _char_type, _traits_type > &is, const _char_type *format, _argument1_type &arg1,..., _argumentN_type &argN)
template<typename _char_type , typename _traits_type , typename _alloc_type , typename _argument1_type , ... , typename _argumentN_type >
std::ios_base::iostate	lite::xscanf (const std::basic_string< _char_type, _traits_type, _alloc_type > &str, const _char_type *format, _argument1_type &arg1,..., _argumentN_type &argN)
template<typename _char_type , typename _traits_type , typename _argument_iter_type >
std::basic_istream< _char_type, _traits_type > &	lite::xscanf_range (std::basic_istream< _char_type, _traits_type > &is, 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_istream< _char_type, _traits_type > &	lite::xscanf_range (std::basic_istream< _char_type, _traits_type > &is, const _char_type *format, _argument_iter_type first, _argument_iter_type last)
template<typename _char_type , typename _traits_type , typename _argument_type >
std::basic_istream< _char_type, _traits_type > &	lite::xscanf_one (std::basic_istream< _char_type, _traits_type > &is, const _char_type *fmt_begin, const _char_type *fmt_end, _argument_type &argument)

---

Detailed Description

Scans the arguments using the specified format string.

These functions use a scanf style format string which can be of Standard or Extended form. In both cases, each argument is scanned by a call to an appropriate overload of xscanf_one() function.

The format string uses exactly the same pattern as the format strings used by xprintf(). You can refer to xprintf() for explanation of the format string. Although the format string changes the stream precision and flags the same way that it does for xprintf(), most of these changes have no effect except for a few like 'i','d','o','x', field width, etc.

Any white space in the format string may match zero or more white space in the input stream. The rest of the characters in the format string, excluding the format fields, should match the same character from the input stream otherwise a input_mismatch_error exception will be thrown.

Remarks:

For an input stream, the field width specifies the maximum length of the next string to be read.

Example:

        int i; float f;
        xscanf(std::cin, "f=%f i=%d", f, i);
        xscanf(std::cin, "f=%s i=%c", f, i); // gives the same result
        
        Date d; // assume that xscanf_one() is defined for the Date class.
        xscanf(std::cin, "The date is : %{%m/%d/%y} ", d); // uses the extended format

---

Function Documentation

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

std::ios_base::iostate lite::xscanf	(	const std::basic_string< _char_type, _traits_type, _alloc_type > &	str,
		const _char_type *	format,
		_argument1_type &	arg1,
			...,
		_argumentN_type &	argN
	)			[inline]

Scans arg1 ... argN from the string str using the format string specified by format and then return the status.

This function fails if the input stream does not match the format string.

Parameters:

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

Returns:

Returns the status

Exceptions:

format_error,argument_index_error,input_mismatch_error

Remarks:

To make sure that the format string matches the whole string and there are no extra characters at the end of the string, you can add an extra space to the end of the format string. The extra space will eat all the trailing white space and if there are no extra non-white space characters at the end, the return value should be std::ios_base::eof_bit .

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

std::basic_istream<_char_type, _traits_type>& lite::xscanf	(	std::basic_istream< _char_type, _traits_type > &	is,
		const _char_type *	format,
		_argument1_type &	arg1,
			...,
		_argumentN_type &	argN
	)			[inline]

Scans arg1 ... argN from the input stream is using the format string specified by format and then return the stream.

This function fails if the input stream does not match the format string.

Parameters:

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

Returns:

Returns the same input stream is

Exceptions:

format_error,argument_index_error,input_mismatch_error

template<typename _char_type , typename _traits_type , typename _argument_type >

std::basic_istream< _char_type, _traits_type > & lite::xscanf_one	(	std::basic_istream< _char_type, _traits_type > &	is,
		const _char_type *	fmt_begin,
		const _char_type *	fmt_end,
		_argument_type &	argument
	)			[inline]

Scans the argument argument from the input stream is 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 read argument from the input 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_istream< _char_type, _traits_type > & lite::xscanf_range	(	std::basic_istream< _char_type, _traits_type > &	is,
		const _char_type *	format,
		_argument_iter_type	first,
		_argument_iter_type	last
	)			[inline]

Scans the arguments in the range [arg1, argN) from the input stream is using the format string specified by format and then return the stream.

This function fails if the input stream does not match the format string.

Parameters:

	is	The source input stream
	format	The format string
	first	The iterator pointing to the beginning of the range of arguments
	last	The iterator pointing to one past the last argument in the range of arguments

Returns:

Returns the same input stream is

Exceptions:

format_error,argument_index_error,input_mismatch_error

template<typename _char_type , typename _traits_type , typename _argument_iter_type >

std::basic_istream< _char_type, _traits_type > & lite::xscanf_range	(	std::basic_istream< _char_type, _traits_type > &	is,
		const _char_type *	format_begin,
		const _char_type *	format_end,
		_argument_iter_type	first,
		_argument_iter_type	last
	)			[inline]

Scans the arguments in the range [arg1, argN) from the input stream is using the format string specified by the range [format_begin, format_end) and then return the stream.

This function fails if the input stream does not match the format string.

Parameters:

	is	The source input stream
	format_begin	Pointer to the beginning of the format string
	format_end	Pointer to the end of the format string
	first	The iterator pointing to the beginning of the range of arguments
	last	The iterator pointing to one past the last argument in the range of arguments

Returns:

Returns the same input stream is

Exceptions:

format_error,argument_index_error,input_mismatch_error