cgul_convspec.h File Reference

printf()-style conversion specifier More...

#include "cgul_exception.h"
#include "cgul_string.h"

Include dependency graph for cgul_convspec.h:

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

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_convspec *	cgul_convspec_t

Functions
CGUL_EXPORT cgul_convspec_t	cgul_convspec__new (cgul_exception_t *cex)
CGUL_EXPORT void	cgul_convspec__delete (cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__copy (cgul_exception_t *cex, cgul_convspec_t lhs, cgul_convspec_t rhs)
CGUL_EXPORT void	cgul_convspec__deserialize (cgul_exception_t *cex, cgul_convspec_t cs, const char *format, unsigned long int *index)
CGUL_EXPORT void	cgul_convspec__serialize (cgul_exception_t *cex, cgul_convspec_t cs, cgul_string_t s)
CGUL_EXPORT int	cgul_convspec__get_flag_hash (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_flag_hash (cgul_exception_t *cex, cgul_convspec_t cs, int flag_hash)
CGUL_EXPORT int	cgul_convspec__get_flag_zero (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_flag_zero (cgul_exception_t *cex, cgul_convspec_t cs, int flag_zero)
CGUL_EXPORT int	cgul_convspec__get_flag_dash (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_flag_dash (cgul_exception_t *cex, cgul_convspec_t cs, int flag_dash)
CGUL_EXPORT int	cgul_convspec__get_flag_space (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_flag_space (cgul_exception_t *cex, cgul_convspec_t cs, int flag_space)
CGUL_EXPORT int	cgul_convspec__get_flag_plus (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_flag_plus (cgul_exception_t *cex, cgul_convspec_t cs, int flag_plus)
CGUL_EXPORT int	cgul_convspec__get_is_field_width_present (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_is_field_width_present (cgul_exception_t *cex, cgul_convspec_t cs, int is_field_width_present)
CGUL_EXPORT int	cgul_convspec__get_is_field_width_on_stack (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_is_field_width_on_stack (cgul_exception_t *cex, cgul_convspec_t cs, int is_field_width_on_stack)
CGUL_EXPORT int	cgul_convspec__get_field_width (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_field_width (cgul_exception_t *cex, cgul_convspec_t cs, int field_width)
CGUL_EXPORT int	cgul_convspec__get_is_precision_present (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_is_precision_present (cgul_exception_t *cex, cgul_convspec_t cs, int is_precision_present)
CGUL_EXPORT int	cgul_convspec__get_is_precision_on_stack (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_is_precision_on_stack (cgul_exception_t *cex, cgul_convspec_t cs, int is_precision_on_stack)
CGUL_EXPORT int	cgul_convspec__get_precision (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_precision (cgul_exception_t *cex, cgul_convspec_t cs, int precision)
CGUL_EXPORT int	cgul_convspec__get_is_length_modifier_present (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_is_length_modifier_present (cgul_exception_t *cex, cgul_convspec_t cs, int is_length_modifier_present)
CGUL_EXPORT const char *	cgul_convspec__get_length_modifier (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_length_modifier (cgul_exception_t *cex, cgul_convspec_t cs, const char *length_modifier)
CGUL_EXPORT char	cgul_convspec__get_cspec (cgul_exception_t *cex, cgul_convspec_t cs)
CGUL_EXPORT void	cgul_convspec__set_cspec (cgul_exception_t *cex, cgul_convspec_t cs, char cspec)

Detailed Description

printf()-style conversion specifier. This class is used to serialize and deserialize printf()-style conversion specifications. It is used internally by cgul_string__append_sprintf() and cgul_varsub_formatted(), but it can be useful when you need custom, formatted output.

Author

Paul Serice

Typedef Documentation

cgul_convspec_t

typedef typedefCGUL_BEGIN_C struct cgul_convspec* cgul_convspec_t

Opaque pointer to cgul_convspec instance.

Function Documentation

cgul_convspec__new()

CGUL_EXPORT cgul_convspec_t cgul_convspec__new

(

cgul_exception_t *

cex

)

Create a new cgul_convspec object that is initialized to the default state. The caller is responsible for freeing the object by calling cgul_convspec__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_convspec instance

Referenced by cgul_convspec_cxx::cgul_convspec_cxx().

cgul_convspec__delete()

CGUL_EXPORT void cgul_convspec__delete

(

cgul_convspec_t

cs

)

This method deletes cs by freeing all internally allocated resources associated with the object. The caller must not use cs after calling this method.

Parameters

[in]

cs

cgul_convspec instance

Referenced by cgul_convspec_cxx::set_obj(), and cgul_convspec_cxx::~cgul_convspec_cxx().

cgul_convspec__copy()

CGUL_EXPORT void cgul_convspec__copy	(	cgul_exception_t *	cex,
		cgul_convspec_t	lhs,
		cgul_convspec_t	rhs
	)

This method performs a deep copy of rhs so that lhs has the same state. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	lhs	left-hand side
[in]	rhs	right-hand side

Referenced by cgul_convspec_cxx::cgul_convspec_cxx(), cgul_convspec_cxx::copy(), and cgul_convspec_cxx::operator=().

cgul_convspec__deserialize()

CGUL_EXPORT void cgul_convspec__deserialize	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		const char *	format,
		unsigned long int *	index
	)

This method assumes the conversion specification begins with a '' character at format[index] and increments index for each character that is consumed such that when this method returns index points to one character beyond the end of the conversion specification. This is the primary method to use when you want to initialize an instance of this class.

Note that serializing an object of this class produces a conversion specification string that is suitable for use as part of a format string that can be passed to printf(). Thus, deserializing an instance of this class reduces a printf() conversion specification into its component parts.

If an error occurs, an exception is thrown, and cs will be in an undefined state.

It is important that you call this method correctly. Because index is a pointer to a variable, you must define and use a variable:

    unsigned long int index = 0;
    cgul_convspec__deserialize(cex, cs, "%d", &index);

Parameters

[in,out]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	format	format string
[in,out]	index	index into format

Referenced by cgul_convspec_cxx::deserialize().

cgul_convspec__serialize()

CGUL_EXPORT void cgul_convspec__serialize	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		cgul_string_t	s
	)

This method serializes cs to a string and appends the result to s. Note that serializing an object of this class produces a conversion specification string that is suitable for use as part of a format string that can be passed to printf().

If an error occurs, an exception is thrown. An error can occur if the system runs out of memory while inserting into s. In this case, s will be in an undefined state.

Parameters

[in,out]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in,out]	s	string

Referenced by cgul_convspec_cxx::serialize().

cgul_convspec__get_flag_hash()

CGUL_EXPORT int cgul_convspec__get_flag_hash	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get whether the '#' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the '#' flag is present

Referenced by cgul_convspec_cxx::get_flag_hash().

cgul_convspec__set_flag_hash()

CGUL_EXPORT void cgul_convspec__set_flag_hash	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	flag_hash
	)

Set whether the '#' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	flag_hash	whether the '#' flag is present

Referenced by cgul_convspec_cxx::set_flag_hash().

cgul_convspec__get_flag_zero()

CGUL_EXPORT int cgul_convspec__get_flag_zero	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get whether the '0' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the '0' flag is present

Referenced by cgul_convspec_cxx::get_flag_zero().

cgul_convspec__set_flag_zero()

CGUL_EXPORT void cgul_convspec__set_flag_zero	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	flag_zero
	)

Set whether the '0' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	flag_zero	whether the '0' flag is present

Referenced by cgul_convspec_cxx::set_flag_zero().

cgul_convspec__get_flag_dash()

CGUL_EXPORT int cgul_convspec__get_flag_dash	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get whether the '-' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the '-' flag is present

Referenced by cgul_convspec_cxx::get_flag_dash().

cgul_convspec__set_flag_dash()

CGUL_EXPORT void cgul_convspec__set_flag_dash	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	flag_dash
	)

Set whether the '-' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	flag_dash	whether the '-' flag is present

Referenced by cgul_convspec_cxx::set_flag_dash().

cgul_convspec__get_flag_space()

CGUL_EXPORT int cgul_convspec__get_flag_space	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get whether the ' ' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the ' ' flag is present

Referenced by cgul_convspec_cxx::get_flag_space().

cgul_convspec__set_flag_space()

CGUL_EXPORT void cgul_convspec__set_flag_space	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	flag_space
	)

Set whether the ' ' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	flag_space	whether the ' ' flag is present

Referenced by cgul_convspec_cxx::set_flag_space().

cgul_convspec__get_flag_plus()

CGUL_EXPORT int cgul_convspec__get_flag_plus	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get whether the '+' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the '+' flag is present

Referenced by cgul_convspec_cxx::get_flag_plus().

cgul_convspec__set_flag_plus()

CGUL_EXPORT void cgul_convspec__set_flag_plus	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	flag_plus
	)

Set whether the '+' flag is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	flag_plus	whether the '+' flag is present

Referenced by cgul_convspec_cxx::set_flag_plus().

cgul_convspec__get_is_field_width_present()

CGUL_EXPORT int cgul_convspec__get_is_field_width_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Whether the field width is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the field width is present

Referenced by cgul_convspec_cxx::get_is_field_width_present().

cgul_convspec__set_is_field_width_present()

CGUL_EXPORT void cgul_convspec__set_is_field_width_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	is_field_width_present
	)

Set whether the field width is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	is_field_width_present	whether the field width is present

Referenced by cgul_convspec_cxx::set_is_field_width_present().

cgul_convspec__get_is_field_width_on_stack()

CGUL_EXPORT int cgul_convspec__get_is_field_width_on_stack	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Whether the field width is on the stack. This occurs when the conversion specifier uses '*' instead of an actual width. It makes no sense to call this function if cgul_convspec__get_is_field_width_present() returns false.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the field width is on the stack

Referenced by cgul_convspec_cxx::get_is_field_width_on_stack().

cgul_convspec__set_is_field_width_on_stack()

CGUL_EXPORT void cgul_convspec__set_is_field_width_on_stack	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	is_field_width_on_stack
	)

Set whether the field width is on the stack. This occurs when the conversion specifier uses '*' instead of an actual width. Calling this method with is_field_width_on_stack set to true does not implicitly mark the field width as present. You will still need to call cgul_convspec__set_is_field_width_present() if that is the intent.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	is_field_width_on_stack	whether the field width is on stack

Referenced by cgul_convspec_cxx::set_is_field_width_on_stack().

cgul_convspec__get_field_width()

CGUL_EXPORT int cgul_convspec__get_field_width	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get the field width. It makes no sense to call this function if cgul_convspec__get_is_field_width_present() returns false or cgul_convspec__get_is_field_width_on_stack() returns true.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

field width

Referenced by cgul_convspec_cxx::get_field_width().

cgul_convspec__set_field_width()

CGUL_EXPORT void cgul_convspec__set_field_width	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	field_width
	)

Set the field width. Calling this method does not implicitly mark the field width as present. You will still need to call cgul_convspec__set_is_field_width_present() if that is the intent. It also does not implicitly mark the field width as not being on the stack. You will still need to call cgul_convspec__set_is_field_width_on_stack() if that is the intent.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	field_width	field width

Referenced by cgul_convspec_cxx::set_field_width().

cgul_convspec__get_is_precision_present()

CGUL_EXPORT int cgul_convspec__get_is_precision_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Whether the precision is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the precision is present

Referenced by cgul_convspec_cxx::get_is_precision_present().

cgul_convspec__set_is_precision_present()

CGUL_EXPORT void cgul_convspec__set_is_precision_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	is_precision_present
	)

Set whether the precision is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	is_precision_present	whether the precision is present

Referenced by cgul_convspec_cxx::set_is_precision_present().

cgul_convspec__get_is_precision_on_stack()

CGUL_EXPORT int cgul_convspec__get_is_precision_on_stack	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Whether the precision is on the stack. This occurs when the conversion specifier uses '*' instead of an actual precision. It makes no sense to call this function if cgul_convspec__get_is_precision_present() returns false.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the precision is on the stack

Referenced by cgul_convspec_cxx::get_is_precision_on_stack().

cgul_convspec__set_is_precision_on_stack()

CGUL_EXPORT void cgul_convspec__set_is_precision_on_stack	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	is_precision_on_stack
	)

Set whether the precision is on the stack. This occurs when the conversion specifier uses '*' instead of an actual precision. Calling this method with is_precision_on_stack set to true does not implicitly mark the precision as present. You will still need to call cgul_convspec__set_is_precision_present() if that is the intent.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	is_precision_on_stack	whether the precision is on stack

Referenced by cgul_convspec_cxx::set_is_precision_on_stack().

cgul_convspec__get_precision()

CGUL_EXPORT int cgul_convspec__get_precision	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get the precision. It makes no sense to call this function if cgul_convspec__get_is_precision_present() returns false or cgul_convspec__get_is_precision_on_stack() returns true.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

precision

Referenced by cgul_convspec_cxx::get_precision().

cgul_convspec__set_precision()

CGUL_EXPORT void cgul_convspec__set_precision	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	precision
	)

Set the precision. Calling this method does not implicitly mark the precision as present. You will still need to call cgul_convspec__set_is_precision_present() if that is the intent. It also does not implicitly mark the precision as not being on the stack. You will still need to call cgul_convspec__set_is_precision_on_stack() if that is the intent.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	precision	precision

Referenced by cgul_convspec_cxx::set_precision().

cgul_convspec__get_is_length_modifier_present()

CGUL_EXPORT int cgul_convspec__get_is_length_modifier_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Whether the length modifier is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

whether the length modifier is present

Referenced by cgul_convspec_cxx::get_is_length_modifier_present().

cgul_convspec__set_is_length_modifier_present()

CGUL_EXPORT void cgul_convspec__set_is_length_modifier_present	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		int	is_length_modifier_present
	)

Set whether the length modifier is present.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	is_length_modifier_present	whether the length modifier is present

Referenced by cgul_convspec_cxx::set_is_length_modifier_present().

cgul_convspec__get_length_modifier()

CGUL_EXPORT const char* cgul_convspec__get_length_modifier	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get the length modifier. It makes no sense to call this function if cgul_convspec__get_is_length_modifier_present() returns false.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

length modifier

Referenced by cgul_convspec_cxx::get_length_modifier().

cgul_convspec__set_length_modifier()

CGUL_EXPORT void cgul_convspec__set_length_modifier	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		const char *	length_modifier
	)

Set the length modifier. Calling this method does not implicitly mark the length modifier as present. You will still need to call cgul_convspec__set_is_length_modifier_present() if that is the intent. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	length_modifier	length modifier

Referenced by cgul_convspec_cxx::set_length_modifier().

cgul_convspec__get_cspec()

CGUL_EXPORT char cgul_convspec__get_cspec	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs
	)

Get the conversion specifier. For example, this is the 'd' character in the "%d" conversion specification.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance

Returns

conversion specifier

Referenced by cgul_convspec_cxx::get_cspec().

cgul_convspec__set_cspec()

CGUL_EXPORT void cgul_convspec__set_cspec	(	cgul_exception_t *	cex,
		cgul_convspec_t	cs,
		char	cspec
	)

Set the conversion specifier. For example, this is the 'd' character in the "%d" conversion specification.

Parameters

[in]	cex	c-style exception
[in]	cs	cgul_convspec instance
[in]	cspec	conversion specifier

Referenced by cgul_convspec_cxx::set_cspec().