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
char * stralloc_finalize (stralloc_t *sa)
 finalize dynamic string in new buffer
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 20 of file stralloc_init.c.

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

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

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

void stralloc_zero ( stralloc_t sa  ) 

truncate string length to zero

Parameters:
[out] sa string to truncate

Definition at line 20 of file stralloc_zero.c.

References stralloc_t::len.

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

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 21 of file stralloc_ready.c.

References stralloc_t::a, mem_realloc(), and stralloc_t::s.

Referenced by stralloc_copyb(), and stralloc_readyplus().

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

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 22 of file stralloc_readyplus.c.

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

Referenced by stralloc_catb().

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

char* stralloc_finalize ( stralloc_t sa  ) 

finalize dynamic string in new buffer

Parameters:
[in] sa string to finalize
Returns:
Newly allocated null-terminated string on success, NULL otherwise.

Definition at line 21 of file stralloc_finalize.c.

References stralloc_t::len, mem_alloc(), mem_cpy(), and stralloc_t::s.

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

00022 {
00023         char *buf = mem_alloc(sa->len + 1);
00024 
00025         if (!buf)
00026                 return 0;
00027 
00028         mem_cpy(buf, sa->s, sa->len);
00029         return buf;
00030 }

void stralloc_free ( stralloc_t sa  ) 

deallocate all memory

Parameters:
[out] sa string to initialize

Definition at line 21 of file stralloc_free.c.

References mem_free(), and stralloc_t::s.

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

00022 {
00023         if (sa->s)
00024                 mem_free(sa->s);
00025 
00026         sa->s = 0;
00027 }

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 21 of file stralloc_copyb.c.

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

Referenced by stralloc_copy(), and stralloc_copys().

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

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 21 of file stralloc_copys.c.

References str_len(), and stralloc_copyb().

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

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 20 of file stralloc_copy.c.

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

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

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 21 of file stralloc_catb.c.

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

Referenced by stralloc_cat(), and stralloc_cats().

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

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 23 of file stralloc_catf.c.

References _lucid_vasprintf(), mem_free(), and stralloc_cats().

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

00024 {
00025         va_list ap;
00026         char *buf;
00027         int rc;
00028 
00029         va_start(ap, fmt);
00030 
00031         if (_lucid_vasprintf(&buf, fmt, ap) == -1) {
00032                 va_end(ap);
00033                 return -1;
00034         }
00035 
00036         va_end(ap);
00037 
00038         rc = stralloc_cats(dst, buf);
00039 
00040         mem_free(buf);
00041 
00042         return rc;
00043 }

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 22 of file stralloc_catm.c.

References stralloc_cats().

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

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 21 of file stralloc_cats.c.

References str_len(), and stralloc_catb().

Referenced by stralloc_catf(), and stralloc_catm().

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

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 20 of file stralloc_cat.c.

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

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

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 20 of file stralloc_cmp.c.

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

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


Generated on Tue Jun 19 20:38:45 2007 for lucid by  doxygen 1.5.2