String +Conversions

Symbian +descriptors and C strings compared

The main difference between +Symbian descriptors and C strings is that the Symbian descriptors know how +many characters are in a data array. A C string does not know its length, +so when length is needed the NULL character that indicates the end of the +string has to be scanned.

Another difference arises with buffers. +When C code reserves a buffer from the heap or stack, it has to keep the maximum +length somewhere. Many C methods that alter the buffer contents do not respect +the maximum size of the buffer and can override the reserved memory, causing +unknown behavior. Some methods take the maximum length as a parameter but +it is difficult to use those types in functions, since a pointer to an array +and maximum length have to be passed separately. Buffer descriptors can tell +the maximum length, and all the methods they provide respect the buffer limits. +

When using neutral descriptor types there is no need to worry about +character widths. In a C program, the programmer has to explicitly specify +which method to use, for example strcat or wcscat.

The +table below contains a comparison of standard C string functions and Symbian +counter parts:

+ + + +

C function

Symbian

Description

+ + +sprintf, swprintf +TDes::Format +

Write formatted data to a string.

+ + +strcat, wcscat, strncat, wcsncat +TDes::Append +

Append a string to another.

+ + +strcmp, strncmp, wcsncmp +TDesC::Compare +

Compare strings lexicographically.

+ + +strcpy, wcscpy strncpy, wcsncpy +TDes::Copy +

Copy a string to another.

+ + +strchr, wcschr +TDesC::Locate +

Find a character in a string.

+ + +strrchr, wcsrchr +TDesC:: LocateReverse +

Scan the index of the first character from a string that does not +exist in the alphabet array.

+ + +strspn, wcsspn +

None

Scan index of the first character from string that doesn't exist +in alphabet array.

+ + +strcspn, wcscspn +

None

Scan the index of the first occurrence of a character in a string +that belongs to the set of characters.

+ + +strstr, wcsstr +TDesC::Find +

Find a substring.

+ + +strtok, wcstok +TLex:: +

Find the next token in a string.

+ + +strlen, wcslen +TDesC::Length +

Get the length of a string.

+ + +strcoll, wcscoll +TDesC::CompareC +

Compare strings using locale-specific information.

+ + +strftime, wcsftime +

Using TDes::Format and TTime

Format a time string.

+ + + +

How +to convert <codeph>TBuf16</codeph> to a <codeph>char</codeph> buffer +

A TBuf16 buffer can be converted to a char buffer +using the wcstombs API. The example below illustrates how +the conversion can be done.

#include <e32base.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 20 +_LIT(KData,"hello"); + +int main (void) +{ + TBuf16<SIZE> buf(KData); + size_t ret; + char carray[SIZE]; + + ret = wcstombs(carray, (const wchar_t *)buf.PtrZ(), SIZE ); + printf("TBuf converted to char buffer : %s\n",carray); + getchar(); + return (1); +} +

How +to convert <codeph>TBuf8</codeph> to <codeph>wchar_t</codeph> +

A TBuf8 buffer can be converted to wchar_t using +the mbstowcs API.

#include <e32base.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 20 + + int main (void) + { + TBuf8<SIZE> buf(_L8("hello")); + size_t ret; + wchar_t warray[SIZE]; + + ret = mbstowcs(warray, (const char *)buf.PtrZ(), SIZE ); + printf("TBuf8 converted to wchar buffer : %ls\n",warray); + getchar(); + + return (1); + } +

How +to convert <codeph>TText16</codeph> to <codeph>char</codeph> +

The wcstombs API can be used to convert a TText16 buffer +to a char buffer. This is one of the examples of converting +from a Symbian data type to a C data type.

#include <e32def.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 32 + +int main (void) +{ + TText arr[SIZE] = L"abcdef"; + char carray[SIZE]; + size_t ret; + + ret = wcstombs(carray, (const wchar_t *)arr, SIZE); + printf("TText converted to char buffer : %s",carray); + getchar(); + + return (1); +} +

How +to convert a <codeph>char</codeph> array and a <codeph>wide char</codeph> array +

To use both char and wide char pointers +or array in the program, the user must convert buffers from a char to +a wide char and vice versa. Wide character APIs provide methods +to:

convert a char array to a wide char array
convert a wide char array to a char array

Converting a char array to a wide char array

The mbstowcs API +can be used to convert a char array to a wide char array.

#include <stdlib.h> +#include <wchar.h> + +#define ARRAY_SIZE 32 + +int main(void) +{ + char *carray = "char array"; + wchar_t warray[ARRAY_SIZE]; + size_t ret; + + ret = mbstowcs(warray, (const char *)carray, ARRAY_SIZE); + wprintf(L"character array contents : %s\n",carray); + wprintf(L"wide char array contents : %ls\n",warray); + getwchar(); + + return (1); +} +

Converting a wide char array to a char array

The wcstombs API +can be used to convert a wide char array to a char array.

#include <stdlib.h> +#include <wchar.h> + +#define ARRAY_SIZE 32 + +int main(void) +{ + wchar_t *warray = L"wide array"; + char carray[ARRAY_SIZE]; + size_t ret; + + ret = wcstombs(carray, (const wchar_t *)warray, ARRAY_SIZE); + wprintf(L"wide char array contents : %ls\n",warray); + wprintf(L"character array contents : %s\n",carray); + getwchar(); + + return (1); +} +

How +to declare a <codeph>wide-char</codeph> string

To declare +a wide-char string, prefix the string with 'L' +[Capital L].

#include <wchar.h> + +int main(void) +{ + wchar_t *wptr = L"This is a wide char string"; + + wprintf(L"%ls\n",wptr); + getwchar(); +} +