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:

How to convert TBuf16 to a char 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 TBuf8 to wchar_t

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 TText16 to char

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 char array and a wide char 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 wide-char 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(); 
}