parse.h File Reference

Standard C library string wrappers and extensions to facilitate string parsing. More...

Go to the source code of this file.

Defines
#define	STRDUP   gift_strdup
#define	STRDUP_N   gift_strndup
#define	STRNCPY   gift_strncpy
#define	STRLEN(str)   gift_strlen(str)
#define	STRLEN_0(str)   gift_strlen0(str)
#define	STRCMP   gift_strcmp
#define	STRCASECMP   gift_strcasecmp
#define	ATOI   gift_strtol /* grumble */
#define	ATOL   gift_strtol
#define	ATOUL   gift_strtoul
#define	ITOA   gift_ltostr
#define	LTOA   gift_ltostr
#define	ULTOA   gift_ultostr
#define	string_move   gift_strmove
#define	STRING_NULL(str)   (((str) && *(str)) ? ((char *)(str)) : ((char *)NULL))
#define	STRING_NOTNULL(str)   ((str) ? ((char *)(str)) : "")
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT char *	stringf (const char *fmt,...)
LIBGIFT_EXPORT char *	stringf_dup (const char *fmt,...)
LIBGIFT_EXPORT char *	string_upper (char *s)
LIBGIFT_EXPORT char *	string_lower (char *s)
LIBGIFT_EXPORT char *	gift_strdup (const char *s)
LIBGIFT_EXPORT char *	gift_strndup (const char *s, size_t len)
LIBGIFT_EXPORT char *	gift_strncpy (char *dst, const char *src, size_t len)
LIBGIFT_EXPORT size_t	gift_strlen (const char *s)
LIBGIFT_EXPORT size_t	gift_strlen0 (const char *s)
LIBGIFT_EXPORT int	gift_strcmp (const char *s1, const char *s2)
LIBGIFT_EXPORT int	gift_strcasecmp (const char *s1, const char *s2)
LIBGIFT_EXPORT long	gift_strtol (const char *str)
LIBGIFT_EXPORT unsigned long	gift_strtoul (const char *str)
LIBGIFT_EXPORT char *	gift_ltostr (long integer)
LIBGIFT_EXPORT char *	gift_ultostr (unsigned long integer)
LIBGIFT_EXPORT char *	gift_strmove (char *dst, const char *src)
LIBGIFT_EXPORT BOOL	string_isempty (const char *s)
LIBGIFT_EXPORT char *	string_trim (char *s)
LIBGIFT_EXPORT char *	string_sep_set (char **string, const char *charset)
LIBGIFT_EXPORT char *	string_sep (char **string, const char *delim)

---

Detailed Description

Standard C library string wrappers and extensions to facilitate string parsing.

---

Define Documentation

#define STRING_NOTNULL (  str   )     ((str) ? ((char *)(str)) : "")

Opposite of STRING_NULL. The str will never evaluate to NULL, opting for an "empty string" (single NUL character) instead.

#define STRING_NULL (  str   )     (((str) && *(str)) ? ((char *)(str)) : ((char *)NULL))

Special macro provided that will check if `str' contains only a NUL character, in which case it will evaluate to NULL instead of the argument. There is a practical use for this somewhere, I'm sure.

---

Function Documentation

LIBGIFT_EXPORT char* gift_ltostr (  long  integer  )

Very silly interface for reverse string-to-integer conversion. Consider using stringf and friends instead.

LIBGIFT_EXPORT int gift_strcasecmp (  const char *  s1, const char *  s2 )

See also: gift_strcmp

LIBGIFT_EXPORT int gift_strcmp (  const char *  s1, const char *  s2 )

Wrapper around strcmp which will not attempt to compare either calling argument if passed as NULL. s1 is considered greater than s2 if s2 is NULL, and vice versa. If both are NULL, s1 is considered greater, as a convenience to the caller.

LIBGIFT_EXPORT char* gift_strdup (  const char *  s  )

Wrapper around strdup with the only benefit of checking s for NULL before duplication. Usage is recommended through the ::STRDUP macro provided below.

LIBGIFT_EXPORT size_t gift_strlen (  const char *  s  )

Prevents strlen(NULL) from causing a segmentation violation. Usage is recommended through the ::STRLEN macro. Returns: The length of the string according to strlen, or 0 if `s' is NULL.

LIBGIFT_EXPORT size_t gift_strlen0 (  const char *  s  )

Similar to gift_strlen, except that the trailing NUL will be counted as a character. This is useful when you wish to determine the actual buffer size, not the length, such as for binary protocols.

LIBGIFT_EXPORT char* gift_strmove (  char *  dst, const char *  src )

Mimic memmove's functionality with NUL-terminated strings.

LIBGIFT_EXPORT char* gift_strncpy (  char *  dst, const char *  src, size_t  len )

Wrapper for strncpy that does not suck. Main difference includes the guarantee that a NUL byte will be written at the end of the destination string. Parameters: dst  src  len  Total number of bytes to copy. The buffer must be at least one byte larger than this value to write the NUL byte. Returns: Pointer to `dst'.

LIBGIFT_EXPORT char* gift_strndup (  const char *  s, size_t  len )

Similar to gift_strdup, except that an exact number of bytes will be copied from the source string. Parameters: s  len  Number of characters to copy. Returns: Dynamically allocated NUL-terminated string of at least len + 1 bytes.

LIBGIFT_EXPORT long gift_strtol (  const char *  str  )

ANSI C portable wrapper to the functionality that strtol provides. Returns: Computed signed integer value. Zero is returned on error, and is indistinguishable from a successful conversion of the integer zero.

LIBGIFT_EXPORT unsigned long gift_strtoul (  const char *  str  )

See also: gift_strtol

LIBGIFT_EXPORT char* gift_ultostr (  unsigned long  integer  )

See also: gift_ltostr

LIBGIFT_EXPORT BOOL string_isempty (  const char *  s  )

Determines whether or not the contents of the calling argument contains non-NUL or newline data. This function is useful when examining strings that may be "" or "\n", but that's about it. Returns: Boolean determination of the emptiness of the string.

LIBGIFT_EXPORT char* string_lower (  char *  s  )

Identical to string_upper, except that tolower will be used, obviously.

LIBGIFT_EXPORT char* string_sep (  char **  string, const char *  delim )

Similar to string_sep_set, except that it is extended to allow for delimiters greater than 1 character wide. Multiple delimiters may not be searched with this function, unfortunately.

LIBGIFT_EXPORT char* string_sep_set (  char **  string, const char *  charset )

Wrapper for strsep for portability and stability. Please note that this function is actually the one most similar to the actual strsep.

LIBGIFT_EXPORT char* string_trim (  char *  s  )

Trims leading and trailing whitespace. Please note that in order to avoid returning an address into the supplied object, data is moved (via gift_strmove) in order to begin the first non-whitespace character at the 0th index. The NUL terminated is then moved to one character beyond the last non-whitespace character. Returns: Original pointer to `s', for convenience.

LIBGIFT_EXPORT char* string_upper (  char *  s  )

Apply the standard toupper function on each character in the provided string. The original calling argument `s' will be returned for your convenience only.

EXTERN_C_BEGIN LIBGIFT_EXPORT char* stringf (  const char *  fmt,   ... )

Similar to sprintf, except that the buffer is replaced by a static character array. This provides a more elegant high-level interface to formatted text. Returns: Pointer to an internally managed static buffer or NULL on error.

LIBGIFT_EXPORT char* stringf_dup (  const char *  fmt,   ... )

Similar to stringf, except that the memory returned will be allocated and management will be handed over to the caller. This is useful when you need multiple formatted buffers or you wish to be threadsafe (and too lazy to use sprintf).

---