cgul_strtok.h File Reference

string tokenizer More...

#include "cgul_common.h"
#include "cgul_exception.h"

Include dependency graph for cgul_strtok.h:

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

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_strtok *	cgul_strtok_t

Functions
CGUL_EXPORT cgul_strtok_t	cgul_strtok__new (cgul_exception_t *cex)
CGUL_EXPORT void	cgul_strtok__delete (cgul_strtok_t tok)
CGUL_EXPORT void	cgul_strtok__set_value (cgul_exception_t *cex, cgul_strtok_t tok, const char *value)
CGUL_EXPORT const char *	cgul_strtok__get_next (cgul_exception_t *cex, cgul_strtok_t tok, const char *separators, int allow_empty_tokens)
CGUL_EXPORT char	cgul_strtok__get_separator (cgul_exception_t *cex, cgul_strtok_t tok)
CGUL_EXPORT size_t	cgul_strtok__get_start (cgul_exception_t *cex, cgul_strtok_t tok)
CGUL_EXPORT size_t	cgul_strtok__get_end (cgul_exception_t *cex, cgul_strtok_t tok)

Detailed Description

String tokenizer designed to replace strtok().

Author

Paul Serice

Typedef Documentation

cgul_strtok_t

typedef typedefCGUL_BEGIN_C struct cgul_strtok* cgul_strtok_t

Opaque pointer to a cgul_strtok instance.

Function Documentation

cgul_strtok__new()

CGUL_EXPORT cgul_strtok_t cgul_strtok__new

(

cgul_exception_t *

cex

)

Create a new cgul_strtok instance. The caller is responsible for caling cgul_strtok__delete() on the pointer returned. If memory allocation fails, NULL is returned, and an exception is thrown.

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_strtok instance

Referenced by cgul_strtok_cxx::cgul_strtok_cxx().

cgul_strtok__delete()

CGUL_EXPORT void cgul_strtok__delete

(

cgul_strtok_t

tok

)

Delete the cgul_strtok object in tok. The client must not use tok after calling this method.

Parameters

[in]

tok

cgul_strtok instance

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

cgul_strtok__set_value()

CGUL_EXPORT void cgul_strtok__set_value	(	cgul_exception_t *	cex,
		cgul_strtok_t	tok,
		const char *	value
	)

Set the value to tokenize. This method makes an internal copy of value out of which tokens will be returned.

Parameters

[in,out]	cex	c-style exception
[in]	tok	cgul_strtok instance
[in]	value	value to tokenize

Referenced by cgul_strtok_cxx::set_value().

cgul_strtok__get_next()

CGUL_EXPORT const char* cgul_strtok__get_next	(	cgul_exception_t *	cex,
		cgul_strtok_t	tok,
		const char *	separators,
		int	allow_empty_tokens
	)

Get the next token that is delimited by the current list of separators. The list of separators can change each time this method is called. If all the tokens have been consumed, NULL is returned.

If allow_empty_tokens is true, this method will return empty tokens when two consecutive separators are encountered including the case where a separator immediately precedes the end of string. If allow_empty_tokens is false, consecutive separators will be telescoped into one, and all tokens returned will be non-empty.

The pointer returned is owned by tok and must not be freed by the client.

Parameters

[in]	cex	c-style exception
[in]	tok	cgul_strtok instance
[in]	separators	list of separators that delimit tokens
[in]	allow_empty_tokens	whether to allow returning empty tokens

Returns

next token

See also

cgul_split()

Referenced by cgul_strtok_cxx::get_next().

cgul_strtok__get_separator()

CGUL_EXPORT char cgul_strtok__get_separator	(	cgul_exception_t *	cex,
		cgul_strtok_t	tok
	)

Get the trailing separator for the current token. This value can be NUL if the current token terminated because it reached the end of the string.

Parameters

[in]	cex	c-style exception
[in]	tok	cgul_strtok instance

Returns

trailing separator for the current token

Referenced by cgul_strtok_cxx::get_separator().

cgul_strtok__get_start()

CGUL_EXPORT size_t cgul_strtok__get_start	(	cgul_exception_t *	cex,
		cgul_strtok_t	tok
	)

Get the starting index for the current token.

Parameters

[in]	cex	c-style exception
[in]	tok	cgul_strtok instance

Returns

starting index for the current token

Referenced by cgul_strtok_cxx::get_start().

cgul_strtok__get_end()

CGUL_EXPORT size_t cgul_strtok__get_end	(	cgul_exception_t *	cex,
		cgul_strtok_t	tok
	)

Get the ending index for the current token. The value returned is actually one beyond the end of the current token. So in effect, the value returned is the index of the trailing separator for the current token.

Parameters

[in]	cex	c-style exception
[in]	tok	cgul_strtok instance

Returns

ending index for the current token

Referenced by cgul_strtok_cxx::get_end().