--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-80F2DEC8-152F-4681-A9D0-8EB776131313.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,247 @@
+<?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-8-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-8-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 <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);
+}
+</codeblock> </section>
+<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-8-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 <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);
+ }
+</codeblock> </section>
+<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-8-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 <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);
+}
+</codeblock> </section>
+<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-8-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 <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);
+}
+</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 <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);
+}
+</codeblock> </section>
+<section id="GUID-A6479BB3-0176-4321-8D33-1465DCCAB049-GENID-1-8-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 <wchar.h>
+
+int main(void)
+{
+ wchar_t *wptr = L"This is a wide char string";
+
+ wprintf(L"%ls\n",wptr);
+ getwchar();
+}
+</codeblock> </section>
+</conbody></concept>
\ No newline at end of file