diff options
author | ambrop7 <ambrop7@1a93d707-3861-5ebc-ad3b-9740d49b5140> | 2013-01-19 03:22:45 +0400 |
---|---|---|
committer | ambrop7 <ambrop7@1a93d707-3861-5ebc-ad3b-9740d49b5140> | 2013-01-19 03:22:45 +0400 |
commit | d6659b4df2d14c053cadb177f1aebb9d5ad6d41d (patch) | |
tree | e2cae5eb8856691fb18cc9e4f023e97bddc82274 /misc | |
parent | 266db4a338ce14895df721beb5cccb26e99fba7f (diff) |
misc/string.h: add documentation
Diffstat (limited to 'misc')
-rw-r--r-- | misc/cstring.h | 63 |
1 files changed, 62 insertions, 1 deletions
diff --git a/misc/cstring.h b/misc/cstring.h index 0586481..789ace0 100644 --- a/misc/cstring.h +++ b/misc/cstring.h @@ -1,5 +1,5 @@ /** - * @file composed_string.h + * @file cstring.h * @author Ambroz Bizjak <ambrop7@gmail.com> * * @section LICENSE @@ -39,8 +39,21 @@ struct b_cstring_s; +/** + * Callback function which is called by {@link b_cstring_get} to access the underlying resource. + * \a cstr points to the cstring being accessed, and the callback can use the userN members to + * retrieve any state information. + * \a offset is the offset from the beginning of the string; offset < cstr->length. + * This callback must set *\a out_length and return a pointer, representing a continuous + * region of the string that starts at the byte at index \a offset. Returning a region that + * spans past the end of the string is allowed. + */ typedef const char * (*b_cstring_func) (const struct b_cstring_s *cstr, size_t offset, size_t *out_length); +/** + * An abstract string which is not necessarily continuous. Its data can be read using + * {@link b_cstring_get}, which internally invokes the {@link b_cstring_func} callback. + */ typedef struct b_cstring_s { size_t length; b_cstring_func func; @@ -61,13 +74,57 @@ typedef struct b_cstring_s { } user3; } b_cstring; +/** + * Convenience function which makes a cstring pointing to a buffer. + */ static b_cstring b_cstring_make_buf (const char *data, size_t length); + +/** + * Retrieves a pointer to a continuous region of the string. + * \a offset specifies the starting offset of the region to retrieve, and must be < cstr.length. + * \a maxlen specifies the maximum length of the returned region, and must be > 0. + * The length of the region will be stored in *\a out_chunk_len, and it will always be > 0. + * It is possible that the returned region spans past the end of the string, unless limited + * by \a maxlen. The pointer to the region will be returned; it will point to the byte + * at offset exactly \a offset into the string. + */ static const char * b_cstring_get (b_cstring cstr, size_t offset, size_t maxlen, size_t *out_chunk_len); + +/** + * Asserts that the range given by \a offset and \a length is valid for the string. + */ static void b_cstring_assert_range (b_cstring cstr, size_t offset, size_t length); + +/** + * Copies a range to an external buffer. + */ static void b_cstring_copy_to_buf (b_cstring cstr, size_t offset, size_t length, char *dest); + +/** + * Performs a memcmp-like operation on the given ranges of two cstrings. + */ static int b_cstring_memcmp (b_cstring cstr1, b_cstring cstr2, size_t offset1, size_t offset2, size_t length); + +/** + * Allocates a buffer for a range and copies it. The buffer is allocated using {@link BAlloc}. + * An extra null byte will be appended. On failure, returns NULL. + */ static char * b_cstring_strdup (b_cstring cstr, size_t offset, size_t length); +/** + * Macro which iterates the continuous regions of a range within a cstring. + * For reach region, the statements in \a body are executed, in order. + * \a cstr is the string to be iterated. + * \a offset and \a length specify the range of the string to iterate; they must + * refer to a valid range for the string. + * \a rel_pos_var, \a chunk_data_var and \a chunk_length_var specify names of variables + * which will be available in \a body. + * \a rel_pos_var will hold the offset of the current continuous region, relative to the beginning. + * \a chunk_data_var will hold a pointer (const char *) to the beginning of the region, and + * \a chunk_length_var will hold its length. + * + * See the implementation of {@link b_cstring_copy_to_buf} for a usage example. + */ #define B_CSTRING_LOOP_RANGE(cstr, offset, length, rel_pos_var, chunk_data_var, chunk_length_var, body) \ { \ size_t rel_pos_var = 0; \ @@ -79,6 +136,10 @@ static char * b_cstring_strdup (b_cstring cstr, size_t offset, size_t length); } \ } +/** + * Like {@link B_CSTRING_LOOP_RANGE}, but iterates the entire string, + * i.e. offset==0 and length==cstr.length. + */ #define B_CSTRING_LOOP(cstr, rel_pos_var, chunk_data_var, chunk_length_var, body) B_CSTRING_LOOP_RANGE(cstr, 0, (cstr).length, rel_pos_var, chunk_data_var, chunk_length_var, body) static const char * b_cstring__buf_func (const b_cstring *cstr, size_t offset, size_t *out_length) |