The qDecoder Project

qString.c File Reference

Advanced String API. More...


Functions

char * qStrTrim (char *str)
 Remove white spaces(including CR, LF) from head and tail of the string.
char * qStrTrimTail (char *str)
 Remove tailing white spaces(including CR, LF) of the string.
char * qStrUnchar (char *str, char head, char tail)
 Remove character from head and tail of the string.
char * qStrReplace (const char *mode, char *srcstr, const char *tokstr, const char *word)
 Replace string or tokens as word from source string with given mode.
char * qStrCpy (char *dst, size_t size, const char *src)
 Copy src string to dst.
char * qStrDupf (const char *format,...)
 Duplicate a formatted string.
char * qStrUpper (char *str)
 Convert character to bigger character.
char * qStrLower (char *str)
 Convert character to lower character.
char * qStrRev (char *str)
 Reverse the order of characters in the string.
char * qStrTok (char *str, const char *delimiters, char *retstop, int *offset)
 Split string into tokens.
Q_ENTRYqStrTokenizer (const char *str, const char *delimiters)
 String Tokenizer.
char * qStrCommaNumber (int number)
 Convert integer to comma string.
char * qStrCatf (char *str, const char *format,...)
 Append formatted string to the end of the source str.
char * qStrDupBetween (const char *str, const char *start, const char *end)
 Duplicate a substing set.
char * qStrUnique (const char *seed)
 Generate unique id.
bool qStrIsAlnum (const char *str)
 Test for an alpha-numeric string.
bool qStrIsEmail (const char *email)
 Test for an email-address formatted string.
bool qStrIsUrl (const char *url)
 Test for an URL formatted string.
char * qStrConvEncoding (const char *str, const char *fromcode, const char *tocode, float mag)
 Convert character encoding.


Detailed Description

Advanced String API.


Function Documentation

char* qStrTrim ( char *  str  ) 

Remove white spaces(including CR, LF) from head and tail of the string.

Parameters:
str source string
Returns:
a pointer of source string if rsuccessful, otherewise returns NULL
Note:
This modify source string directly.

char* qStrTrimTail ( char *  str  ) 

Remove tailing white spaces(including CR, LF) of the string.

Parameters:
str source string
Returns:
a pointer of source string if rsuccessful, otherewise returns NULL
Note:
This modify source string directly.

char* qStrUnchar ( char *  str,
char  head,
char  tail 
)

Remove character from head and tail of the string.

Parameters:
str source string
head heading character
tail tailing character
Returns:
a pointer of source string if rsuccessful, otherewise returns NULL
Note:
This modify source string directly.
   char *str = strdup("   \"hello world\"   ");
   qStrTrim(str); // to remove white spaces
   qStrUnchar(str, '"', '"'); // to unquote

char* qStrReplace ( const char *  mode,
char *  srcstr,
const char *  tokstr,
const char *  word 
)

Replace string or tokens as word from source string with given mode.

Parameters:
mode replacing mode
srcstr source string
tokstr token or string
word target word to be replaced
Returns:
a pointer of malloced or source string depending on the mode if rsuccessful, otherewise returns NULL
Note:
The mode argument has two separated character. First character is used to decide replacing method and can be 't' or 's'. The character 't' and 's' stand on [t]oken and [s]tring.
When 't' is given each character of the token string(third argument) will be compared with source string individually. If matched one is found. the character will be replaced with given work.

If 's' is given instead of 't'. Token string will be analyzed only one chunk word. So the replacement will be occured when the case of whole word matched.

Second character is used to decide returning memory type and can be 'n' or 'r' which are stand on [n]ew and [r]eplace.

When 'n' is given the result will be placed into new array so you should free the return string after using. Instead of this, you can also use 'r' character to modify source string directly. In this case, given source string should have enough space. Be sure that untouchable value can not be used for source string.

So there are four associatable modes such like below.

Mode "tn" : [t]oken replacing & putting the result into [n]ew array. Mode "tr" : [t]oken replacing & [r]eplace source string directly. Mode "sn" : [s]tring replacing & putting the result into [n]ew array. Mode "sr" : [s]tring replacing & [r]eplace source string directly.

   char srcstr[256], *retstr;
   char mode[4][2+1] = {"tn", "tr", "sn", "sr"};

   for(i = 0; i < 4; i++) {
     strcpy(srcstr, "Welcome to the qDecoder project.");
     printf("before %s : srcstr = %s\n", mode[i], srcstr);

     retstr = qStrReplace(mode[i], srcstr, "the", "_");
     printf("after  %s : srcstr = %s\n", mode[i], srcstr);
     printf("            retstr = %s\n\n", retstr);
     if(mode[i][1] == 'n') free(retstr);
   }

   --[Result]--
   before tn : srcstr = Welcome to the qDecoder project.
   after  tn : srcstr = Welcome to the qDecoder project.
               retstr = W_lcom_ _o ___ qD_cod_r proj_c_.

   before tr : srcstr = Welcome to the qDecoder project.
   after  tr : srcstr = W_lcom_ _o ___ qD_cod_r proj_c_.
               retstr = W_lcom_ _o ___ qD_cod_r proj_c_.

   before sn : srcstr = Welcome to the qDecoder project.
   after  sn : srcstr = Welcome to the qDecoder project.
               retstr = Welcome to _ qDecoder project.

   before sr : srcstr = Welcome to the qDecoder project.
   after  sr : srcstr = Welcome to _ qDecoder project.
               retstr = Welcome to _ qDecoder project.

char* qStrCpy ( char *  dst,
size_t  size,
const char *  src 
)

Copy src string to dst.

The dst string arrary will be always terminated by NULL character.

Parameters:
dst a pointer of the string to be copied
size the size of dst character arrary
src a pointer of source string
Returns:
always returns a pointer of dst

char* qStrDupf ( const char *  format,
  ... 
)

Duplicate a formatted string.

Parameters:
format string format
Returns:
a pointer of malloced string if successful, otherwise returns NULL

char* qStrUpper ( char *  str  ) 

Convert character to bigger character.

Parameters:
str a pointer of source string
Returns:
always returns a pointer of str
Note:
This modify str directly.

char* qStrLower ( char *  str  ) 

Convert character to lower character.

Parameters:
str a pointer of source string
Returns:
always returns a pointer of str
Note:
This modify str directly.

char* qStrRev ( char *  str  ) 

Reverse the order of characters in the string.

Parameters:
str a pointer of source string
Returns:
always returns a pointer of str
Note:
This modify str directly.

char* qStrTok ( char *  str,
const char *  delimiters,
char *  retstop,
int *  offset 
)

Split string into tokens.

Parameters:
str source string
delimiters string that specifies a set of delimiters that may surround the token being extracted
retstop stop delimiter character will be stored. it can be NULL if you don't want to know.
offset integer pointer used for store last position. (must be reset to 0)
Returns:
a pointer to the first byte of a token if successful, otherwise returns NULL.
   char *str = strdup("Hello,world|Thank,you");
   char *token;
   int offset = 0;
   while((token = qStrTok(str, "|,", NULL, &offset)) != NULL) {
     printf("%s\n", token);
  }

Note:
This mau modify str argument. The major difference between qStrTok() and standard strtok() is that qStrTok() can returns empty string tokens. If the str is "a:b::d", qStrTok() returns "a", "b", "", "d". But strtok() returns "a","b","d".

Q_ENTRY* qStrTokenizer ( const char *  str,
const char *  delimiters 
)

String Tokenizer.

Parameters:
str source string
delimiters string that specifies a set of delimiters that may surround the token being extracted
Returns:
a pointer to the Q_ENTRY list
Note:
Tokens will be stored at Q_ENTRY list with key 1, 2, 3, 4, 5...
   FILE *fp = fopen("/etc/passwd", "r");
   char *buf;
   while((buf = qFileReadLine(fp)) != NULL) {
     qStrTrimTail(buf);
      Q_ENTRY *tokens = qStrTokenizer(buf, ":");
      printf("%s\n", tokens->getStr(tokens, "1"));
      tokens->free(tokens);
   }
   fclose(fp);

char* qStrCommaNumber ( int  number  ) 

Convert integer to comma string.

Parameters:
number integer
Returns:
a pointer of malloced string which contains comma separated number if successful, otherwise returns NULL

char* qStrCatf ( char *  str,
const char *  format,
  ... 
)

Append formatted string to the end of the source str.

Parameters:
str a pointer of original string
format string format to append
Returns:
a pointer of str if successful, otherwise returns NULL

char* qStrDupBetween ( const char *  str,
const char *  start,
const char *  end 
)

Duplicate a substing set.

Parameters:
str a pointer of original string
start substring which is started with this
end substring which is ended with this
Returns:
a pointer of malloced string if successful, otherwise returns NULL

char* qStrUnique ( const char *  seed  ) 

Generate unique id.

Parameters:
seed additional seed string. this can be NULL
Returns:
a pointer of malloced string
Note:
The length of returned string is 32+1 bytes long including terminating NULL character. Because it uses random() internally, it's good idea to call srandom() once before use.

bool qStrIsAlnum ( const char *  str  ) 

Test for an alpha-numeric string.

Parameters:
str a pointer of string
Returns:
true for ok, otherwise returns false
   if(qStrIsAlnum("hello1234") == true) {
     printf("It is alpha-numeric string.");
   }

bool qStrIsEmail ( const char *  email  ) 

Test for an email-address formatted string.

Parameters:
email email-address formatted string
Returns:
true if successful, otherwise returns false

bool qStrIsUrl ( const char *  url  ) 

Test for an URL formatted string.

Parameters:
url URL formatted string
Returns:
true if successful, otherwise returns false

char* qStrConvEncoding ( const char *  str,
const char *  fromcode,
const char *  tocode,
float  mag 
)

Convert character encoding.

Parameters:
str additional seed string. this can be NULL
fromcode encoding type of str
tocode encoding to convert
mag magnification between fromcode and tocode
Returns:
a pointer of malloced converted string if successful, otherwise returns NULL
   qCharEncode("KOREAN_EUCKR_STRING", "EUC-KR", "UTF-8", 1.5);


Copyright (c) 2008 The qDecoder Project