Defines | Functions

src/string.c File Reference

#include "config.h"
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <ctype.h>
#include <errno.h>
#include "libestr.h"
Include dependency graph for string.c:

Defines

#define ERR_ABORT   {r = 1; goto done; }
#define CHECK_STR
#define ASSERT_STR(s)

Functions

int es_extendBuf (es_str_t **ps, es_size_t minNeeded)
es_str_tes_newStr (es_size_t lenhint)
es_str_tes_newStrFromCStr (char *cstr, es_size_t len)
es_str_tes_newStrFromSubStr (es_str_t *str, es_size_t start, es_size_t len)
void es_deleteStr (es_str_t *s)
int es_strbufcmp (es_str_t *s, unsigned char *buf, es_size_t lenBuf)
int es_addChar (es_str_t **ps, unsigned char c)
int es_addBuf (es_str_t **ps1, char *buf, es_size_t lenBuf)
char * es_str2cstr (es_str_t *s, char *nulEsc)
void es_unescapeStr (es_str_t *s)

Detailed Description

Implements string handling

Note:
: for efficiency reasons, later builds may spread the individual functions across different source modules. I was a bit lazy to do this right now and I am totally unsure if it really is worth the effort.

Function Documentation

int es_addBuf ( es_str_t **  ps1,
char *  buf,
es_size_t  lenBuf 
)

Append a memory buffer to a string. This is the method that almost all other append methods actually use.

Parameters:
in/out] ps1 updateable pointer to to-be-appended-to string
[in] buf buffer to append
[in] lenBuf length of buffer
Returns:
0 on success, something else otherwise
int es_addChar ( es_str_t **  ps,
unsigned char  c 
)

Append a character to the current string object. Note that the pointer to the string object may change. This is because we may need to aquire more memory.

Parameters:
in/out] ps string to be extened (updatedable pointer required!)
Returns:
0 on success, something else otherwise
void es_deleteStr ( es_str_t str  ) 

delete a string object.

Parameters:
[in] str string to be deleted.

defined(NDEBUG)

int es_extendBuf ( es_str_t **  ps,
es_size_t  minNeeded 
)

Extend string buffer. This is called if the size is insufficient. Note that the string pointer will be changed.

Parameters:
in/out] ps pointer to (pointo to) string to be extened
[in] minNeeded minimum number of additional bytes needed
Returns:
0 on success, something else otherwise
es_str_t* es_newStr ( es_size_t  lenhint  ) 

Create a new string object.

Parameters:
[in] lenhint expected max length of string. Do not use too large value.
Returns:
pointer to new object or NULL on error
es_str_t* es_newStrFromCStr ( char *  cstr,
es_size_t  len 
)

Create a new string object based on a "traditional" C string.

Parameters:
[in] cstr traditional, ''-terminated C string
[in] len length of str. Use strlen() if you don't know it, but often it the length is known and we use this as a time-safer (if present).
Returns:
pointer to new object or NULL on error
es_str_t* es_newStrFromSubStr ( es_str_t str,
es_size_t  start,
es_size_t  len 
)

Create a new string object from a substring of an existing string. This involves copying the substring.

Parameters:
[in] str original string
[in] start beginning position of substring (0-based)
[in] len length of substring to extract
Returns:
pointer to new object or NULL on error

If start > strlen, a valid (!) empty string will be returned. If start+len > strlen, the rest of the string starting at start will be returned.

char* es_str2cstr ( es_str_t s,
char *  nulEsc 
)

Obtain a traditional C-String from a string object. The string object is not modified. Note that the C string is not necessarily exactly the same string: C Strings can not contain NUL characters, and as such they need to be either encoded or dropped. This is done by this function. The user can specify with which character sequence (a traditional C String) it shall be replaced.

Note:
This function has to do a lot of work, and should not be called unless absolutely necessary. If possible, use the native representation of the string object. For example, you can use the buffer address and string length in most i/o calls, if you use the native versions and avoid the C string i/o calls.
Parameters:
[in] s string object
[in] nulEsc escape sequence for NULs. If NULL, NUL characters will be dropped.
Returns:
NULL in case of error, otherwise a suitably-encoded standard C string. This string is allocated from the dynamic memory pool and must be freed by the caller.
int es_strbufcmp ( es_str_t s,
unsigned char *  b,
es_size_t  len 
)

Compare a string against a buffer. Semantics are the same as strcmp(). This function is required in order to permit simple comparisons against C strings, what otherwise would require conversions. As a side-effect, it can also compare against substrings and other buffers of any type.

Parameters:
[in] s string to compare
[in] b buffer to compare against
[in] len lenght of buffer
Returns:
0 if equal, negative if s<cs, positive if s>cs
void es_unescapeStr ( es_str_t s  ) 

Unescape a string. The escape seqences defined below will be unescaped and replaced by a single character. The string is modified in place (note that space is always sufficient, because the resulting string will be smaller or of equal size). This function can not run into trouble, so it does not return a return status.

The following escape sequences, inspired by the C language, are supported: (Note: double backslashes are for Doxygen, of course this is to be used with single backslashes):

  • \0 NUL
  • \a BEL
  • \b Backspace
  • \f FF
  • \n LF
  • \r CR
  • \t HT
  • \' singlu quotation mark
  • \" double quotation mark
  • \? question mark
  • \\ backslash character
  • \ooo ASCII Character in octal notation (o being octal digit)
  • \xhh ASCC character in hexadecimal notation
  • \xhhhh Unicode characer in headecimal notation All other escape sequences are undefined. Currently, this is interpreted as the escape character itself, but this is not guaranteed. Most importantly, a special meaning may be assigned to any of the currently-unassigned characters in the future.
Parameters:
in/out] s string object to unescape.