<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-80F2DEC8-152F-4681-A9D0-8EB776131313" xml:lang="en"><title>String

Conversions</title><shortdesc>In 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. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-1">       <title>Symbian

descriptors and C strings compared</title>       <p>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.  </p><p>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.

 </p><p>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 <codeph>strcat</codeph> or <codeph>wcscat</codeph>.</p><p>The

table below contains a comparison of standard C string functions and Symbian

counter parts:</p><table id="GUID-0580FD76-A651-4F23-81FF-4460DAF1992E">

<tgroup cols="3"><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>

<tbody>

<row>

<entry><p><b>C function</b></p></entry>

<entry><p><b>Symbian</b></p></entry>

<entry><p><b>Description</b></p></entry>

</row>

<row>

<entry><codeph>sprintf, swprintf</codeph></entry>

<entry><codeph>TDes::Format</codeph></entry>

<entry><p>Write formatted data to a string.</p></entry>

</row>

<row>

<entry><codeph>strcat, wcscat, strncat, wcsncat </codeph></entry>

<entry><codeph>TDes::Append</codeph></entry>

<entry><p>Append a string to another. </p></entry>

</row>

<row>

<entry><codeph>strcmp, strncmp, wcsncmp </codeph></entry>

<entry><codeph>TDesC::Compare</codeph></entry>

<entry><p>Compare strings lexicographically. </p></entry>

</row>

<row>

<entry><codeph>strcpy, wcscpy strncpy, wcsncpy </codeph></entry>

<entry><codeph>TDes::Copy </codeph></entry>

<entry><p>Copy a string to another. </p></entry>

</row>

<row>

<entry><codeph>strchr, wcschr</codeph></entry>

<entry><codeph>TDesC::Locate </codeph></entry>

<entry><p>Find a character in a string. </p></entry>

</row>

<row>

<entry><codeph>strrchr, wcsrchr</codeph></entry>

<entry><codeph>TDesC:: LocateReverse </codeph></entry>

<entry><p>Scan the index of the first character from a string that does not

exist in the alphabet array. </p></entry>

</row>

<row>

<entry><codeph>strspn, wcsspn</codeph></entry>

<entry><p>None </p></entry>

<entry><p>Scan index of the first character from string that doesn't exist

in alphabet array. </p></entry>

</row>

<row>

<entry><codeph>strcspn, wcscspn</codeph></entry>

<entry><p>None </p></entry>

<entry><p>Scan the index of the first occurrence of a character in a string

that belongs to the set of characters. </p></entry>

</row>

<row>

<entry><codeph>strstr, wcsstr</codeph></entry>

<entry><codeph>TDesC::Find </codeph></entry>

<entry><p>Find a substring. </p></entry>

</row>

<row>

<entry><codeph>strtok, wcstok</codeph></entry>

<entry><codeph>TLex::</codeph></entry>

<entry><p>Find the next token in a string. </p></entry>

</row>

<row>

<entry><codeph>strlen, wcslen</codeph></entry>

<entry><codeph>TDesC::Length</codeph></entry>

<entry><p>Get the length of a string. </p></entry>

</row>

<row>

<entry><codeph>strcoll, wcscoll</codeph></entry>

<entry><codeph>TDesC::CompareC </codeph></entry>

<entry><p>Compare strings using locale-specific information. </p></entry>

</row>

<row>

<entry><codeph>strftime, wcsftime</codeph></entry>

<entry><p>Using <codeph>TDes::Format</codeph> and <codeph>TTime </codeph></p></entry>

<entry><p>Format a time string. </p></entry>

</row>

</tbody>

</tgroup>

</table>     </section>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-2">       <title>How

to convert <codeph>TBuf16</codeph> to a <codeph>char</codeph> buffer</title> 

     <p>A <codeph>TBuf16</codeph> buffer can be converted to a <codeph>char</codeph> buffer

using the <codeph>wcstombs</codeph> API. The example below illustrates how

the conversion can be done.</p><codeblock xml:space="preserve">#include &lt;e32base.h&gt;

#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);

}

</codeblock>     </section>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-3">       <title>How

to convert <codeph>TBuf8</codeph> to <codeph>wchar_t</codeph></title>    

  <p>A <codeph>TBuf8</codeph> buffer can be converted to <codeph>wchar_t</codeph> using

the <codeph>mbstowcs</codeph> API.</p><codeblock xml:space="preserve">#include &lt;e32base.h&gt;

#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);

 }

</codeblock>     </section>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-4">       <title>How

to convert <codeph>TText16</codeph> to <codeph>char</codeph></title>     

 <p>The <codeph>wcstombs</codeph> API can be used to convert a <codeph>TText16</codeph> buffer

to a <codeph>char</codeph> buffer. This is one of the examples of converting

from a Symbian data type to a C data type.</p><codeblock xml:space="preserve">#include &lt;e32def.h&gt;

#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);

}

</codeblock>     </section>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-5">       <title>How

to convert a <codeph>char</codeph> array and a <codeph>wide char</codeph> array</title> 

     <p>To use both <codeph>char</codeph> and <codeph>wide char</codeph> pointers

or array in the program, the user must convert buffers from a <codeph>char</codeph> to

a <codeph>wide char</codeph> and vice versa. Wide character APIs provide methods

to: </p><ul>

<li><p>convert a <codeph>char</codeph> array to a <codeph>wide char</codeph> array</p></li>

<li><p>convert a <codeph>wide char</codeph> array to a <codeph>char</codeph> array </p></li>

</ul><p><b>Converting a <codeph>char</codeph> array to a <codeph>wide char</codeph> array</b></p><p>The <codeph>mbstowcs</codeph> API

can be used to convert a <codeph>char</codeph> array to a <codeph>wide char</codeph> array.</p><codeblock xml:space="preserve">#include &lt;stdlib.h&gt;

#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);

}

</codeblock><p><b>Converting a <codeph>wide char</codeph> array to a <codeph>char</codeph> array </b></p><p>The <codeph>wcstombs</codeph> API

can be used to convert a <codeph>wide char</codeph> array to a <codeph>char</codeph> array. </p><codeblock xml:space="preserve">#include &lt;stdlib.h&gt;

#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);

}

</codeblock>     </section>

<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-10-1-11-1-1-5-1-3-1-7-1-10-1-3-6">       <title>How

to declare a <codeph>wide-char</codeph> string</title>       <p>To declare

a <codeph>wide-char</codeph> string, prefix the string with 'L'

[Capital L].  </p><codeblock xml:space="preserve">#include &lt;wchar.h&gt;

int main(void)

{

     wchar_t *wptr = L"This is a wide char string";

     wprintf(L"%ls\n",wptr);

     getwchar(); 

}

</codeblock>     </section>