<?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 &lt;sys/types.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;wchar.h&gt;

#define SIZE 20
_LIT(KData,"hello");
  
int main (void)
{
    TBuf16&lt;SIZE&gt; 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 &lt;sys/types.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;wchar.h&gt;

#define SIZE 20
 
 int main (void)
 {
     TBuf8&lt;SIZE&gt; 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 &lt;sys/types.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;wchar.h&gt;

#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 &lt;wchar.h&gt;

#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 &lt;wchar.h&gt;

#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>
</conbody></concept>