gi_strobj.h File Reference

Defines an abstract object for constructing and manipulating strings. More...

#include "gi_buffer.h"

Go to the source code of this file.

Classes
struct	GiString
Defines
#define	GI_STRBUF(string)   (gi_string_buffer ((string)))
#define	GI_STRLEN(string)   (gi_string_length ((string)))
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT void	gi_string_init (GiString *string)
LIBGIFT_EXPORT void	gi_string_initex (GiString *string, char *str, size_t alloc, size_t len, bool can_resize)
LIBGIFT_EXPORT void	gi_string_finish (GiString *string)
LIBGIFT_EXPORT char *	gi_string_finish_keep (GiString *string)
LIBGIFT_EXPORT GiString *	gi_string_new (char *str, size_t alloc, size_t len, bool rok)
LIBGIFT_EXPORT void	gi_string_free (GiString *string)
LIBGIFT_EXPORT char *	gi_string_free_keep (GiString *string)
LIBGIFT_EXPORT char *	gi_string_buffer (GiString *string)
LIBGIFT_EXPORT size_t	gi_string_length (GiString *string)
LIBGIFT_EXPORT int	gi_string_appendvf (GiString *string, const char *fmt, va_list args)
LIBGIFT_EXPORT int	gi_string_appendf (GiString *string, const char *fmt,...)
LIBGIFT_EXPORT int	gi_string_append (GiString *string, const char *str)
LIBGIFT_EXPORT int	gi_string_appendu (GiString *string, unsigned char *str, size_t len)
LIBGIFT_EXPORT int	gi_string_appendc (GiString *string, int c)

---

Detailed Description

Defines an abstract object for constructing and manipulating strings.

Extremely crude string object. This supports only the most basic string building operations and even those leave a lot to be desired. Please don't expect much from this system.

---

Function Documentation

LIBGIFT_EXPORT int gi_string_append (  GiString *  string, const char *  str )

Append a single NUL-terminated string. Returns: On success, the number of bytes written, not including the trailing NUL; otherwise, -1.

LIBGIFT_EXPORT int gi_string_appendc (  GiString *  string, int  c )

Append a single character value. The supplied character should be unsigned and cast to an int to be passed to this API. Returns: On success, 1 is returned; otherwise, -1.

LIBGIFT_EXPORT int gi_string_appendf (  GiString *  string, const char *  fmt,   ... )

See sprintf.

LIBGIFT_EXPORT int gi_string_appendu (  GiString *  string, unsigned char *  str, size_t  len )

Append a single unsigned non-NUL terminated string. Returns: On success, number of bytes written; otherwise, -1. The return value will never be short of `len'.

LIBGIFT_EXPORT int gi_string_appendvf (  GiString *  string, const char *  fmt, va_list  args )

See vsprintf.

LIBGIFT_EXPORT char* gi_string_buffer (  GiString *  string  )

Accessor for the underlying string buffer.

LIBGIFT_EXPORT void gi_string_finish (  GiString *  string  )

Release any internally used memory. The object is not nullified and it is up to the caller to avoid further usage.

LIBGIFT_EXPORT char* gi_string_finish_keep (  GiString *  string  )

Release all but the internally built string and return it. It is up to the caller to free() the resulting string manually, assuming it was allocated internally. Be careful when mixing usage of this with ::gi_string_setbuf.

LIBGIFT_EXPORT void gi_string_free (  GiString *  string  )

Destroy an allocated GiString object. All internally used memory will be destroyed as well.

LIBGIFT_EXPORT char* gi_string_free_keep (  GiString *  string  )

Destroy the allocated GiString object, but preserve the internally managed C string. See gi_string_finish_keep for more details.

EXTERN_C_BEGIN LIBGIFT_EXPORT void gi_string_init (  GiString *  string  )

Initialize a string object given a pointer to it's present storage. This produces a blank object ready for use with the rest of the API.

LIBGIFT_EXPORT void gi_string_initex (  GiString *  string, char *  str, size_t  alloc, size_t  len, bool  can_resize )

Initialize a string object and manually set the internally managed buffer with another, generally found in the caller's localized scope. Parameters: string  str  New string buffer to use. This buffer does not necessarily need to be dynamically allocated, depending on `can_resize'. alloc  Total size allocated to `str'. That is, how many bytes can we write, including the terminating NUL character. len  Number of bytes currently written to `str'. Specify 0 if the buffer is not initialized. can_resize  Specifies whether or not the supplied string buffer can be resized with realloc(). If no, it will be considered an error to append data beyond the currently allocated size.

LIBGIFT_EXPORT size_t gi_string_length (  GiString *  string  )

Accessor for the string buffer's length (excluding the NUL, of course).

LIBGIFT_EXPORT GiString* gi_string_new (  char *  str, size_t  alloc, size_t  len, bool  rok )

Allocates a new dynamic GiString object. Upon success, ::gi_string_setbuf is called with the calling parameters.

---