Dynamic string allocator


Detailed Description

A stralloc variable holds a byte string in dynamically allocated space. String contents are unrestricted; in particular, strings may contain \0. String length is limited only by memory and by the size of an unsigned int.

A stralloc structure has three components: sa.s is a pointer to the first byte of the string, or 0 if space is not allocated; sa.len is the number of bytes in the string, or undefined if space is not allocated; sa.a is the number of bytes allocated for the string, or undefined if space is not allocated.

Applications are expected to use sa.s and sa.len directly.

The stralloc_ready() function makes sure that sa has enough space allocated to hold len bytes. The stralloc_readyplus() function is like stralloc_ready() except that, if sa is already allocated, stralloc_readyplus adds the current length of sa to len.

The stralloc_copyb() function copies the string pointed to by src into dst, allocating space if necessary. The stralloc_copys() function copies a \0-terminated string from src into dst, without the \0. It is the same as stralloc_copyb(&dst,buf,str_len(buf)). stralloc_copy copies the string stored in src into dst. It is the same as stralloc_copyb(&dst,src.s,src.len); src must already be allocated.

The stralloc_catb() adds the string pointed to by src to the end of the string stored in dst, allocating space if necessary. If dst is unallocated, stralloc_catb is the same as stralloc_copyb. The stralloc_cats() function is analogous to stralloc_copys, and stralloc_cat is analogous to stralloc_copy. The stralloc_catf() and stralloc_catm() functions are analogous to stralloc_cats() except that they take a formatted conversion or variable number of arguments, respectively, and appends these to the string stored in dst.


Data Structures

struct  stralloc_t
 dynamic string allocator tracking data More...

Functions

void stralloc_init (stralloc_t *sa)
 initialize dynamic string allocator
void stralloc_zero (stralloc_t *sa)
 truncate string length to zero
int stralloc_ready (stralloc_t *sa, size_t len)
 ensure that enough memory has been allocated
int stralloc_readyplus (stralloc_t *sa, size_t len)
 ensure that enough memory has been allocated
void stralloc_free (stralloc_t *sa)
 deallocate all memory
int stralloc_copyb (stralloc_t *dst, const char *src, size_t len)
 copy a static string to a dynamic one
int stralloc_copys (stralloc_t *dst, const char *src)
 copy a static string to a dynamic one
int stralloc_copy (stralloc_t *dst, const stralloc_t *src)
 copy one dynamic string to another
int stralloc_catb (stralloc_t *dst, const char *src, size_t len)
 concatenate a dynamic string and a static one
int stralloc_catf (stralloc_t *dst, const char *fmt,...)
 concatenate a dynamic string and a static one using formatted conversion
int stralloc_catm (stralloc_t *dst,...)
 concatenate a dynamic string and multiple static ones
int stralloc_cats (stralloc_t *dst, const char *src)
 concatenate a dynamic string and a static one
int stralloc_cat (stralloc_t *dst, const stralloc_t *src)
 concatenate two dynamic strings
int stralloc_cmp (const stralloc_t *a, const stralloc_t *b)
 compare two dynamic strings


Function Documentation

void stralloc_init ( stralloc_t sa  ) 

initialize dynamic string allocator

Parameters:
[out] sa string to initialize

Definition at line 23 of file stralloc_init.c.

References stralloc_t::a, stralloc_t::len, and stralloc_t::s.

Referenced by argv_to_str(), flist32_to_str(), flist64_to_str(), and whirlpool_digest().

00024 {
00025         sa->s   = NULL;
00026         sa->len = sa->a = 0;
00027 }

void stralloc_zero ( stralloc_t sa  ) 

truncate string length to zero

Parameters:
[out] sa string to truncate

Definition at line 21 of file stralloc_zero.c.

References stralloc_t::len.

00022 {
00023         sa->len = 0;
00024 }

int stralloc_ready ( stralloc_t sa,
size_t  len 
)

ensure that enough memory has been allocated

Parameters:
[in] sa string to check
[in] len minimum length that has to be available
Returns:
0 on success, -1 on error with errno set

Definition at line 23 of file stralloc_ready.c.

References stralloc_t::a, and stralloc_t::s.

Referenced by stralloc_copyb(), and stralloc_readyplus().

00024 {
00025         size_t wanted = len + (len >> 3) + 30;
00026         char *tmp;
00027         
00028         if (!sa->s || sa->a < len) {
00029                 if (!(tmp = realloc(sa->s, wanted)))
00030                         return -1;
00031                 
00032                 sa->a = wanted;
00033                 sa->s = tmp;
00034         }
00035         
00036         return 0;
00037 }

int stralloc_readyplus ( stralloc_t sa,
size_t  len 
)

ensure that enough memory has been allocated

Parameters:
[in] sa string to check
[in] len additional length that has to be available
Returns:
0 on success, -1 on error with errno set

Definition at line 23 of file stralloc_readyplus.c.

References stralloc_t::len, stralloc_t::s, and stralloc_ready().

Referenced by stralloc_catb().

00024 {
00025         if (sa->s) {
00026                 if (sa->len + len < len)
00027                         return errno = EINVAL, -1;
00028                 
00029                 return stralloc_ready(sa, sa->len + len);
00030         }
00031         
00032         return stralloc_ready(sa, len);
00033 }

void stralloc_free ( stralloc_t sa  ) 

deallocate all memory

Parameters:
[out] sa string to initialize

Definition at line 23 of file stralloc_free.c.

References stralloc_t::s.

Referenced by argv_to_str(), flist32_to_str(), flist64_to_str(), and whirlpool_digest().

00024 {
00025         if (sa->s)
00026                 free(sa->s);
00027         
00028         sa->s = 0;
00029 }

int stralloc_copyb ( stralloc_t dst,
const char *  src,
size_t  len 
)

copy a static string to a dynamic one

Parameters:
[out] dst dynamic destination string
[in] src static source string
[in] len copy at most len bytes
Returns:
0 on success, -1 on error with errno set

Definition at line 22 of file stralloc_copyb.c.

References stralloc_t::len, stralloc_t::s, str_cpyn(), and stralloc_ready().

Referenced by stralloc_copy(), and stralloc_copys().

00023 {
00024         if (stralloc_ready(dst, len) == -1)
00025                 return -1;
00026         
00027         str_cpyn(dst->s, src, len);
00028         dst->len = len;
00029         return 0;
00030 }

int stralloc_copys ( stralloc_t dst,
const char *  src 
)

copy a static string to a dynamic one

Parameters:
[out] dst dynamic destination string
[in] src static source string
Returns:
0 on success, -1 on error with errno set

Definition at line 22 of file stralloc_copys.c.

References str_len(), and stralloc_copyb().

00023 {
00024         return stralloc_copyb(dst, src, str_len(src));
00025 }

int stralloc_copy ( stralloc_t dst,
const stralloc_t src 
)

copy one dynamic string to another

Parameters:
[out] dst dynamic destination string
[in] src dynamic source string
Returns:
0 on success, -1 on error with errno set

Definition at line 21 of file stralloc_copy.c.

References stralloc_t::len, stralloc_t::s, and stralloc_copyb().

00022 {
00023         return stralloc_copyb(dst, src->s, src->len);
00024 }

int stralloc_catb ( stralloc_t dst,
const char *  src,
size_t  len 
)

concatenate a dynamic string and a static one

Parameters:
[out] dst dynamic destination string
[in] src static source string
[in] len append at most len bytes
Returns:
0 on success, -1 on error with errno set

Definition at line 22 of file stralloc_catb.c.

References stralloc_t::len, stralloc_t::s, str_cpyn(), and stralloc_readyplus().

Referenced by stralloc_cat(), and stralloc_cats().

00023 {
00024         if (stralloc_readyplus(dst, len) == -1)
00025                 return -1;
00026         
00027         str_cpyn(dst->s + dst->len, src, len);
00028         dst->len += len;
00029         return 0;
00030 }

int stralloc_catf ( stralloc_t dst,
const char *  fmt,
  ... 
)

concatenate a dynamic string and a static one using formatted conversion

Parameters:
[out] dst dynamic destination string
[in] fmt format string
[in] ... variable number of arguments
Returns:
0 on success, -1 on error with errno set

Definition at line 25 of file stralloc_catf.c.

References _lucid_vasprintf(), and stralloc_cats().

Referenced by flist32_to_str(), flist64_to_str(), and whirlpool_digest().

00026 {
00027         va_list ap;
00028         char *buf;
00029         int rc;
00030         
00031         va_start(ap, fmt);
00032         _lucid_vasprintf(&buf, fmt, ap);
00033         va_end(ap);
00034         
00035         rc = stralloc_cats(dst, buf);
00036         
00037         free(buf);
00038         
00039         return rc;
00040 }

int stralloc_catm ( stralloc_t dst,
  ... 
)

concatenate a dynamic string and multiple static ones

Parameters:
[out] dst dynamic destination string
[in] ... variable number of source strings
Returns:
0 on success, -1 on error with errno set
Note:
the last argument must be NULL

Definition at line 23 of file stralloc_catm.c.

References stralloc_cats().

Referenced by argv_to_str().

00024 {
00025         va_list ap;
00026         char *s;
00027         
00028         va_start(ap, dst);
00029         
00030         while ((s = va_arg(ap, char *))) {
00031                 if (stralloc_cats(dst, s) == -1) {
00032                         va_end(ap);
00033                         return -1;
00034                 }
00035         }
00036         
00037         va_end(ap);
00038         return 0;
00039 }

int stralloc_cats ( stralloc_t dst,
const char *  src 
)

concatenate a dynamic string and a static one

Parameters:
[out] dst dynamic destination string
[in] src static source string
Returns:
0 on success, -1 on error with errno set

Definition at line 22 of file stralloc_cats.c.

References str_len(), and stralloc_catb().

Referenced by stralloc_catf(), and stralloc_catm().

00023 {
00024         return stralloc_catb(dst, src, str_len(src));
00025 }

int stralloc_cat ( stralloc_t dst,
const stralloc_t src 
)

concatenate two dynamic strings

Parameters:
[out] dst dynamic destination string
[in] src dynamic source string
Returns:
0 on success, -1 on error with errno set

Definition at line 21 of file stralloc_cat.c.

References stralloc_t::len, stralloc_t::s, and stralloc_catb().

00022 {
00023         return stralloc_catb(dst, src->s, src->len);
00024 }

int stralloc_cmp ( const stralloc_t a,
const stralloc_t b 
)

compare two dynamic strings

Parameters:
[in] a first string
[in] b second string
Returns:
An integer greater than, equal to, or less than 0, if the string pointed to by a is greater than, equal to, or less than the string pointed to by b, respectively.

Definition at line 21 of file stralloc_cmp.c.

References stralloc_t::len, and stralloc_t::s.

00022 {
00023         size_t i, j;
00024         
00025         for (i = 0;; ++i) {
00026                 if (i == a->len)
00027                         return i == b->len ? 0 : -1;
00028                 
00029                 if (i == b->len)
00030                         return 1;
00031                 
00032                 if ((j = ((unsigned char)(a->s[i]) - (unsigned char)(b->s[i]))))
00033                         return j;
00034         }
00035         
00036         return j;
00037 }


Generated on Sun Dec 3 17:46:16 2006 for lucid by  doxygen 1.5.1