/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss of reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

#ifndef _STDIO_FORMAT_H
#define	_STDIO_FORMAT_H

#include <string.h>
#include <stdarg.h>

/** @addtogroup stdio */
/**	@{ */

/**
*	Prototype for the output function of print_xxx().
*
*	This function is called whenever a print_int() or print_flt()
*	function wants to write a partial result. The interpteration of
*	the first argument is up to the function, the print_int() or
*	print_flt() functions never modify that parameter. The second
*	argument is a pointer to the string to be written and the third
*	is the number of characters to write.<br>
*	The function should return a non-negative number in case of
*	success or a negative error code on failure. If the function
*	returns error, the print_int() or print_flt() function will
*	abort and return the same error that this function returned.
*
*	@param	user	A user object that is passed to the formatting
*					function, which, in turn, will pass it verbatim
*					to the user nominated function that writes a
*					block of data to the nominated output.
*
*	@param	data	Pointer to the data to write out
*
*	@param	dlen	The number of bytes to write out
*
*	@return			A non-negative number on success and a negative number
*					on failure. If the returned value was negative, then
*					the format function will return that value as its own
*					error code.
*/

typedef	int	(*BLC_FMT_PUT)( void **user, const char *data, size_t dlen );

/**
*	Prototype for the input function of scan_int and scan_flt().
*
*	This function is called whenever a scan_int() or scan_flt()
*	needs a new character from the input. The interpretation of
*	the argument is up to the function, scan_int() and scan_flt()
*	just pass it to the function but never modify it.
*	The function should return a positive character value if the
*	read from the input was successful, EOF if the input was exhasuted
*	and a negative error code (other than EOF) in case there was a
*	read error. In the case of an error code being returned, scan_int()
*	or scan_flt() will abort and return the same error code.
*
*	@param	user	A user object that is passed to the scanning
*					function, which, in turn, will pass it verbatim
*					to the user nominated function that reads from
*					the nominated output.
*
*	@return			A non-negative number, representing the byte read
*					from the input on success, EOF (i.e. -1) if the
*					input was exhausted and any other negative number
*					on failure. If failure was indicated, the scan function
*					will return the same error code.
*/

typedef int (*BLC_FMT_GET)( void **user );

/**
*	Prototype for the pushback function of scan_int() and scan_flt().
*
*	This function is called whenever a scan_int() or scan_flt()
*	wants to push a character back to the input. At most one character
*	is pushed back before consuming the input again. After calling this
*	function it is expected that the next read from the input will return
*	the same character as was pushed back. Note that scan_int() and scan_flt()
*	guarantees that the character pushed back will be the last character
*	obtained from the input.
*	The first argument for the function is the character to push back,
*	the second is a parameter which can be interpreted by the function
*	in any way. This is the same parameter that is passed to the character
*	read function and it is never modified by scan_int() or scan_flt().
*	The function should return a non-negative value if the pushback was
*	successful and a negative error code (other than EOF) if the pushback
*	failed.
*
*	@param	data	The character to push back to the input stream.
*					It is guaranteed that it is the same character
*					that the last call of the get function returned.
*
*	@param	user	A user object that is passed to the scanning
*					function, which, in turn, will pass it verbatim
*					to the user nominated function that reads from
*					the nominated output.
*
*	@return			A non-negative number in case of success or a
*					negative number (other than EOF) on failure.
*					In the latter case the scan function will return the
*					same value as its own error code.
*/

typedef int (*BLC_FMT_UNG)( int, void ** );

/**
*	End of file marker.
*/

#define	EOF		(-1)

/** @} */

int		print_int( const char *fmt, va_list arg, size_t len,
				   BLC_FMT_PUT fun, void **par, int (*w2m)(char*,wchar_t**) );

int		print_flt( const char *fmt, va_list arg, size_t len,
				   BLC_FMT_PUT fun, void **par, int (*w2m)(char*,wchar_t**) );

int		scan_int( const char *fmt, va_list arg, BLC_FMT_GET get,
				  BLC_FMT_UNG ung, void **par,
				  int(*m2w)(wchar_t**,const char*,size_t) );

int		scan_flt( const char *fmt, va_list arg, BLC_FMT_GET get,
				  BLC_FMT_UNG ung, void **par,
				  int(*m2w)(wchar_t**,const char*,size_t) );

#endif

