Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

Strings


Detailed Description

implementation of strings.

Strings in C are represented by arrays of characters.The end of the string is marked with a special character, the null character, which is simply the character with the value 0. Whenever we write a string, enclosed in double quotes, C automatically creates an array of characters for us, containing that string, terminated by the NULL character.

FIXME: this comment is plain copy/pasted from cdg.c

The symbol table cdgSymbolTable)is used to share strings registered (cdgRegisterString()) to it. Sharing strings speeds up string comparison alot as we dont need strcmp for this any more. A pointer comarison suffices. So we store strings in a hash. But be warned: changing a registered string directly will break things seriously. If you need to change a registered string, make a copy of it (strCopy), manipulate it for your needs and then register it once again.

Data Structures

Typedefs

Functions

Variables


Function Documentation

void _strDeleteSharedString SharedString  sstr  )  [static]
 

deallocated a SharedString.

This function deallocates a SharedString and its workload. Definition at line 335 of file string.c.

References SharedStringStruct::data.

Referenced by _strDeleteStoreEntry(), and strDelete().

void _strDeleteStoreEntry String  key,
SharedString  value
[static]
 

deallocate a key value pair.

This is used to deallocate the key and the value of the _strStore. Definition at line 326 of file string.c.

References _strDeleteSharedString().

Referenced by strFinalize().

SharedString _strLookup String  str  )  [static]
 

lookup a string in the string store.

This function returns a pointer to a SharedString if the given string argument is already shared, or NULL if this string isn't shared yet. Definition at line 169 of file string.c.

References _strStore, and hashGet().

Referenced by _strTryRegister(), strDelete(), and strRegister().

SharedString _strNewSharedString const String  str  )  [static]
 

allocate a new SharedString.

This function constructs a new SharedString. It contains no worload data yet. Definition at line 297 of file string.c.

References SharedStringStruct::counter, and SharedStringStruct::data.

Referenced by strRegister().

String _strTryRegister String  str  )  [static]
 

try to register a new string.

This function only registers new strings. It will not increase the reference counter of an already registered string. In any case it will return a known string. Definition at line 183 of file string.c.

References _strLookup(), and strRegister().

Referenced by strCat().

String strAppend const String  head,
  ...
 

concatenates many strings together.

This function allocates the memory for the result string. The argument strings are not modified by the function. The last string in the argument list must be NULL.

Parameters:
str the head of the string to be produced
... represents the strings to be appended to the head.
Returns:
the new appended string.
Definition at line 272 of file string.c.

References listAppendElement(), listDelete(), and strFromList().

String strCat const String  a,
const String  b
 

concatenates two strings.

This is our version of the standard unix strcat() with the differences that both arguments are const strings. A concatenated shared string of a and b is returned. Both arguments might be NULL.

Returns:
the target concatenated with the source.
Definition at line 202 of file string.c.

References _strTryRegister(), strPrintf(), and strRegister().

String strCopy const String  s  ) 
 

this performs string copying function.

This function constructs a copy of the given source string. The returned string is not shared any more as its source might have been. So in order to manipulate a shared string, first strCopy() it, then alter it and strRegister() it finaly. While copying the string new memory is allocated for you. Take care of it.

Parameters:
s the string that has to be copied.
Returns:
the new copied string.
Definition at line 101 of file string.c.

Referenced by strFromList(), and strRegister().

String strDecode String  word  ) 
 

Translate a string from unicode UTF-8 to ISO-8859-1.

The String will be left untouched if there is any problem while decoding. Definition at line 450 of file string.c.

References strRegister().

void strDelete String  str  ) 
 

unregister a string This function tries deallocate the str string when its reference counter licenses it.

Note, that the pointer str might get invalid or not depending on the reference counter. Definition at line 353 of file string.c.

References _strDeleteSharedString(), _strLookup(), _strStore, SharedStringStruct::counter, and hashRemove().

void strFinalize void   ) 
 

module finalization routine.

This function is only called by blahInitialize() and should not be used from outside It basically deallocates the _strStore. It also closes the conversionHandler. Definition at line 418 of file string.c.

References _strDeleteStoreEntry(), _strStore, hashForEach(), hashForEachFree(), hashListOfKeys(), hashSize(), listElement(), listNext(), and listSize().

Referenced by blahFinalize().

String strFromList List  list  ) 
 

concatenates a list of strings.

This function takes a list of strings and concatenates them together in a newly allocated string. Be sure that all list elements are realy of type string. We can't grant that here. If the list is NULL or empty NULL is returned to you. The return value is a registered string.

Parameters:
list of strings
Returns:
the new appended string.
Definition at line 230 of file string.c.

References listElement(), listNext(), listSize(), strCopy(), and strRegister().

Referenced by strAppend().

void strInitialize void   ) 
 

module initialization routine.

This function is only called by blahInitialize() and should not be used from outside It basically allocates the _strStore. It also sets the conversion handler for String decoding Definition at line 500 of file string.c.

References _strStore, hashNew(), hashStringEqualFunction(), and hashStringHashFunction().

Referenced by blahInitialize().

String strPrintf const String  fmt,
  ...
 

returns a formated string.

This function basically has been taken from the sprintf() manual page. The differences between sprintf() and strPrintf() are that you don't have to bother about memory allocation. We allocate enuf memory to hold the formated result string. Further more then this string is strRegister()ed for you, so you might get an already shared string returned to you. Use strDelete() to indicate your lake of interest on the result string. Definition at line 152 of file string.c.

References strVPrintf().

Referenced by strCat().

String strRegister const String  str  ) 
 

register a string in symbol table.

This function registers a string to be shared. This is done by copying it into the _strStore (leaving the argument string pointer untouched). If the string already exists in symbol table the _stored_ string is returned. If the string doesn't exist then the string is _copied_ and entered in the symbol table; the new string is returned. In no case the memory of string s is referenced by the symbol table. But the returned string is owned by the symbol table and will be shared by other references later on. So be careful and never change a registered string in place. Use strCopy() first to check out a copy of a shared string. If str is NULL then a registered empty string is returned, that is strRegister(NULL) == strRegister(""). Definition at line 380 of file string.c.

References _strLookup(), _strNewSharedString(), _strStore, SharedStringStruct::counter, SharedStringStruct::data, hashSet(), and strCopy().

Referenced by _strTryRegister(), strCat(), strDecode(), strFromList(), and strVPrintf().

int strStoreSize void   ) 
 

return the number of shared strings.

Definition at line 406 of file string.c.

References _strStore, and hashSize().

String strVPrintf const String  fmt,
va_list  ap
 

returns a formated string.

This function is our version of vsprintf(). See strPrintf() for more information. Definition at line 117 of file string.c.

References strRegister().

Referenced by strPrintf().


Variable Documentation

Hashtable _strStore = NULL [static]
 

container for shared strings.

This global variable stores all registered strings Definition at line 61 of file string.c.

Referenced by _strLookup(), strDelete(), strFinalize(), strInitialize(), strRegister(), and strStoreSize().


BLAH 0.95 (20 Oct 2004)