Encapsulates C string datatype and hides memory management.
| CString | Encapsulates C string datatype and hides memory management. |
| Copyright | This program is free software. |
| Files | |
| C-kern/ | Header file of CString. |
| C-kern/ | Implementation file CString impl. |
| Types | |
| struct cstring_t | Export cstring_t. |
| Functions | |
| test | |
| unittest_string_cstring | Tests cstring_t. |
| cstring_t | Dynamically growing C string with trailing ‘\0’ byte. |
| length | Length of string in bytes (sizeof(char)==1). |
| allocated_size | Size of allocated memory block chars points to. |
| chars | Pointer to character array with ‘\0’ at the end of the string. |
| lifetime | |
| cstring_FREE | Static initializer. |
| cstring_INIT | Static initializer. |
| init_cstring | Inits cstring_t and preallocates memory. |
| initfromstring_cstring | Inits cstring_t and copies data from string_t. |
| initmove_cstring | Inits dest with content of source and sets source to cstring_FREE. |
| free_cstring | Frees any allocated memory associated with type cstring_t. |
| query | |
| str_cstring | Returns ‘\0’ terminated string. |
| size_cstring | Returns the size of the string in bytes. |
| allocatedsize_cstring | Returns the allocated buffer size in bytes. |
| change | |
| allocate_cstring | Makes sure cstr has at least allocate_size preallocated bytes. |
| append_cstring | Appends str with len str_len to cstr. |
| clear_cstring | Sets size of string to 0. |
| printfappend_cstring | Appends printf formatted string to cstr. |
| resize_cstring | Allocates memory and sets size to new_size. |
| truncate_cstring | Adapts size of cstr to a smaller value. |
| inline implementation | |
| Macros | |
| initmove_cstring | Implements cstring_t.initmove_cstring. |
| allocatedsize_cstring | Implements <cstring_t.allocatedsize>. |
| size_cstring | Implements cstring_t.size_cstring. |
| str_cstring | Implements cstring_t.str_cstring. |
This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
© 2011 Jörg Seebohn
Header file of CString.
Implementation file CString impl.
typedef struct cstring_t cstring_t
Export cstring_t.
int unittest_string_cstring( void )
Tests cstring_t.
struct cstring_t
Dynamically growing C string with trailing ‘\0’ byte.
| length | Length of string in bytes (sizeof(char)==1). |
| allocated_size | Size of allocated memory block chars points to. |
| chars | Pointer to character array with ‘\0’ at the end of the string. |
| lifetime | |
| cstring_FREE | Static initializer. |
| cstring_INIT | Static initializer. |
| init_cstring | Inits cstring_t and preallocates memory. |
| initfromstring_cstring | Inits cstring_t and copies data from string_t. |
| initmove_cstring | Inits dest with content of source and sets source to cstring_FREE. |
| free_cstring | Frees any allocated memory associated with type cstring_t. |
| query | |
| str_cstring | Returns ‘\0’ terminated string. |
| size_cstring | Returns the size of the string in bytes. |
| allocatedsize_cstring | Returns the allocated buffer size in bytes. |
| change | |
| allocate_cstring | Makes sure cstr has at least allocate_size preallocated bytes. |
| append_cstring | Appends str with len str_len to cstr. |
| clear_cstring | Sets size of string to 0. |
| printfappend_cstring | Appends printf formatted string to cstr. |
| resize_cstring | Allocates memory and sets size to new_size. |
| truncate_cstring | Adapts size of cstr to a smaller value. |
Length of string in bytes (sizeof(char)==1). The number of characters could be smaller if the encoding is UTF-8 for example.
(0 == chars) || <chars>[size] == 0
uint8_t* chars
Pointer to character array with ‘\0’ at the end of the string.
((0 == chars) && (0 == allocated_size)) || ((0 != chars) && (0 != allocated_size))
#define cstring_FREE { (size_t)0, (size_t)0, (void*)0 }
Static initializer. Makes calling free_cstring a no op.
#define cstring_INIT { (size_t)0, (size_t)0, (void*)0 }
Static initializer. Same as calling init_cstring with preallocate_size set to 0.
int init_cstring( /*out*/cstring_t * cstr, size_t preallocate_size )
Inits cstring_t and preallocates memory. If you set preallocate_size to 0 no memory is preallocated.
void initmove_cstring( /*out*/cstring_t * restrict dest, cstring_t * restrict source )
Inits dest with content of source and sets source to cstring_FREE.
int free_cstring( cstring_t * cstr )
Frees any allocated memory associated with type cstring_t.
size_t allocatedsize_cstring( const cstring_t * cstr )
Returns the allocated buffer size in bytes. To access the start address of the buffer use str_cstring.
int allocate_cstring( cstring_t * cstr, size_t allocate_size )
Makes sure cstr has at least allocate_size preallocated bytes. The string buffer is reallocated if necessary. If it is big enough nothing is done. After successful return the buffer returned from str_cstring points to at least allocate_size bytes of memory.
int append_cstring( cstring_t * cstr, size_t str_len, const char str[str_len] )
Appends str with len str_len to cstr.
It is not allowed to use parts of the buffer of cstr as arguments for this function. Cause during a possible reallocation of the buffer these arguments become invalid.
void clear_cstring( cstring_t * cstr )
Sets size of string to 0. This function has the same result as calling truncate_cstring with parameter 0. No memory is deallocated.
int printfappend_cstring( cstring_t * cstr, const char * format, ... ) __attribute__ ((__format__ (__printf__, 2, 3)))
Appends printf formatted string to cstr. Like sprintf but the buffer is reallocated if it is too small and the new content is appended to the end of the string.
It is not allowed to use parts of the buffer of cstr as arguments for this function. Cause during a possible reallocation of the buffer these arguments become invalid.
int resize_cstring( cstring_t * cstr, size_t new_size )
Allocates memory and sets size to new_size. The possibly reallocated buffer can be accessed with a call to str_cstring. If the new size is bigger than the current size the buffer will contain “random” characters.
int truncate_cstring( cstring_t * cstr, size_t new_size )
Adapts size of cstr to a smaller value. Use this if you you want to make the string smaller in size. A trailing 0 byte is added by this call. Use this function with caution cause new_size is interpreted as byte offset. If a character uses more than one byte for its encoding and if new_size points not to the end of a valid character sequence the encoded character sequence becomes invalid.
| Macros | |
| initmove_cstring | Implements cstring_t.initmove_cstring. |
| allocatedsize_cstring | Implements <cstring_t.allocatedsize>. |
| size_cstring | Implements cstring_t.size_cstring. |
| str_cstring | Implements cstring_t.str_cstring. |
#define initmove_cstring( dest, source ) do { *(dest) = *(source) ; *(source) = (cstring_t) cstring_FREE ; } while(0)
Implements cstring_t.initmove_cstring.
#define size_cstring( cstr ) ((cstr)->size)
Implements cstring_t.size_cstring.
#define str_cstring( cstr ) ((char*)(cstr)->chars)
Implements cstring_t.str_cstring.
Export cstring_t.
typedef struct cstring_t cstring_t
Dynamically growing C string with trailing ‘\0’ byte.
struct cstring_t
Tests cstring_t.
int unittest_string_cstring( void )
Size of allocated memory block chars points to.
size_t allocated_size
Pointer to character array with ‘\0’ at the end of the string.
uint8_t* chars
Static initializer.
#define cstring_FREE { (size_t)0, (size_t)0, (void*)0 }
Static initializer.
#define cstring_INIT { (size_t)0, (size_t)0, (void*)0 }
Inits cstring_t and preallocates memory.
int init_cstring( /*out*/cstring_t * cstr, size_t preallocate_size )
Inits cstring_t and copies data from string_t.
int initfromstring_cstring( /*out*/cstring_t * cstr, const struct string_t * copiedfrom )
Inits dest with content of source and sets source to cstring_FREE.
void initmove_cstring( /*out*/cstring_t * restrict dest, cstring_t * restrict source )
Frees any allocated memory associated with type cstring_t.
int free_cstring( cstring_t * cstr )
Returns ‘\0’ terminated string.
char * str_cstring( cstring_t * cstr )
Returns the size of the string in bytes.
size_t size_cstring( const cstring_t * cstr )
Returns the allocated buffer size in bytes.
size_t allocatedsize_cstring( const cstring_t * cstr )
Makes sure cstr has at least allocate_size preallocated bytes.
int allocate_cstring( cstring_t * cstr, size_t allocate_size )
Appends str with len str_len to cstr.
int append_cstring( cstring_t * cstr, size_t str_len, const char str[str_len] )
Sets size of string to 0.
void clear_cstring( cstring_t * cstr )
Appends printf formatted string to cstr.
int printfappend_cstring( cstring_t * cstr, const char * format, ... ) __attribute__ ((__format__ (__printf__, 2, 3)))
Allocates memory and sets size to new_size.
int resize_cstring( cstring_t * cstr, size_t new_size )
Adapts size of cstr to a smaller value.
int truncate_cstring( cstring_t * cstr, size_t new_size )
Implements cstring_t.initmove_cstring.
#define initmove_cstring( dest, source ) do { *(dest) = *(source) ; *(source) = (cstring_t) cstring_FREE ; } while(0)
Implements cstring_t.allocatedsize.
#define allocatedsize_cstring( cstr ) ((cstr)->allocated_size)
Implements cstring_t.size_cstring.
#define size_cstring( cstr ) ((cstr)->size)
Implements cstring_t.str_cstring.
#define str_cstring( cstr ) ((char*)(cstr)->chars)