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(); -} -

+ + + + + +String +ConversionsIn case the developer is developing applications where P.I.P.S.-based +functionality is called from a Symbian/S60 application, the need for conversions +between Symbian descriptors and different string types provided by P.I.P.S. +is needed. +

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(); +} +

\ No newline at end of file