|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-80F2DEC8-152F-4681-A9D0-8EB776131313" xml:lang="en"><title>String |
|
13 Conversions</title><shortdesc>In case the developer is developing applications where P.I.P.S.-based |
|
14 functionality is called from a Symbian/S60 application, the need for conversions |
|
15 between Symbian descriptors and different string types provided by P.I.P.S. |
|
16 is needed. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <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 |
|
18 descriptors and C strings compared</title> <p>The main difference between |
|
19 Symbian descriptors and C strings is that the Symbian descriptors know how |
|
20 many characters are in a data array. A C string does not know its length, |
|
21 so when length is needed the NULL character that indicates the end of the |
|
22 string has to be scanned. </p><p>Another difference arises with buffers. |
|
23 When C code reserves a buffer from the heap or stack, it has to keep the maximum |
|
24 length somewhere. Many C methods that alter the buffer contents do not respect |
|
25 the maximum size of the buffer and can override the reserved memory, causing |
|
26 unknown behavior. Some methods take the maximum length as a parameter but |
|
27 it is difficult to use those types in functions, since a pointer to an array |
|
28 and maximum length have to be passed separately. Buffer descriptors can tell |
|
29 the maximum length, and all the methods they provide respect the buffer limits. |
|
30 </p><p>When using neutral descriptor types there is no need to worry about |
|
31 character widths. In a C program, the programmer has to explicitly specify |
|
32 which method to use, for example <codeph>strcat</codeph> or <codeph>wcscat</codeph>.</p><p>The |
|
33 table below contains a comparison of standard C string functions and Symbian |
|
34 counter parts:</p><table id="GUID-0580FD76-A651-4F23-81FF-4460DAF1992E"> |
|
35 <tgroup cols="3"><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
36 <tbody> |
|
37 <row> |
|
38 <entry><p><b>C function</b></p></entry> |
|
39 <entry><p><b>Symbian</b></p></entry> |
|
40 <entry><p><b>Description</b></p></entry> |
|
41 </row> |
|
42 <row> |
|
43 <entry><codeph>sprintf, swprintf</codeph></entry> |
|
44 <entry><codeph>TDes::Format</codeph></entry> |
|
45 <entry><p>Write formatted data to a string.</p></entry> |
|
46 </row> |
|
47 <row> |
|
48 <entry><codeph>strcat, wcscat, strncat, wcsncat </codeph></entry> |
|
49 <entry><codeph>TDes::Append</codeph></entry> |
|
50 <entry><p>Append a string to another. </p></entry> |
|
51 </row> |
|
52 <row> |
|
53 <entry><codeph>strcmp, strncmp, wcsncmp </codeph></entry> |
|
54 <entry><codeph>TDesC::Compare</codeph></entry> |
|
55 <entry><p>Compare strings lexicographically. </p></entry> |
|
56 </row> |
|
57 <row> |
|
58 <entry><codeph>strcpy, wcscpy strncpy, wcsncpy </codeph></entry> |
|
59 <entry><codeph>TDes::Copy </codeph></entry> |
|
60 <entry><p>Copy a string to another. </p></entry> |
|
61 </row> |
|
62 <row> |
|
63 <entry><codeph>strchr, wcschr</codeph></entry> |
|
64 <entry><codeph>TDesC::Locate </codeph></entry> |
|
65 <entry><p>Find a character in a string. </p></entry> |
|
66 </row> |
|
67 <row> |
|
68 <entry><codeph>strrchr, wcsrchr</codeph></entry> |
|
69 <entry><codeph>TDesC:: LocateReverse </codeph></entry> |
|
70 <entry><p>Scan the index of the first character from a string that does not |
|
71 exist in the alphabet array. </p></entry> |
|
72 </row> |
|
73 <row> |
|
74 <entry><codeph>strspn, wcsspn</codeph></entry> |
|
75 <entry><p>None </p></entry> |
|
76 <entry><p>Scan index of the first character from string that doesn't exist |
|
77 in alphabet array. </p></entry> |
|
78 </row> |
|
79 <row> |
|
80 <entry><codeph>strcspn, wcscspn</codeph></entry> |
|
81 <entry><p>None </p></entry> |
|
82 <entry><p>Scan the index of the first occurrence of a character in a string |
|
83 that belongs to the set of characters. </p></entry> |
|
84 </row> |
|
85 <row> |
|
86 <entry><codeph>strstr, wcsstr</codeph></entry> |
|
87 <entry><codeph>TDesC::Find </codeph></entry> |
|
88 <entry><p>Find a substring. </p></entry> |
|
89 </row> |
|
90 <row> |
|
91 <entry><codeph>strtok, wcstok</codeph></entry> |
|
92 <entry><codeph>TLex::</codeph></entry> |
|
93 <entry><p>Find the next token in a string. </p></entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><codeph>strlen, wcslen</codeph></entry> |
|
97 <entry><codeph>TDesC::Length</codeph></entry> |
|
98 <entry><p>Get the length of a string. </p></entry> |
|
99 </row> |
|
100 <row> |
|
101 <entry><codeph>strcoll, wcscoll</codeph></entry> |
|
102 <entry><codeph>TDesC::CompareC </codeph></entry> |
|
103 <entry><p>Compare strings using locale-specific information. </p></entry> |
|
104 </row> |
|
105 <row> |
|
106 <entry><codeph>strftime, wcsftime</codeph></entry> |
|
107 <entry><p>Using <codeph>TDes::Format</codeph> and <codeph>TTime </codeph></p></entry> |
|
108 <entry><p>Format a time string. </p></entry> |
|
109 </row> |
|
110 </tbody> |
|
111 </tgroup> |
|
112 </table> </section> |
|
113 <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 |
|
114 to convert <codeph>TBuf16</codeph> to a <codeph>char</codeph> buffer</title> |
|
115 <p>A <codeph>TBuf16</codeph> buffer can be converted to a <codeph>char</codeph> buffer |
|
116 using the <codeph>wcstombs</codeph> API. The example below illustrates how |
|
117 the conversion can be done.</p><codeblock xml:space="preserve">#include <e32base.h> |
|
118 #include <sys/types.h> |
|
119 #include <stdio.h> |
|
120 #include <stdlib.h> |
|
121 #include <wchar.h> |
|
122 |
|
123 #define SIZE 20 |
|
124 _LIT(KData,"hello"); |
|
125 |
|
126 int main (void) |
|
127 { |
|
128 TBuf16<SIZE> buf(KData); |
|
129 size_t ret; |
|
130 char carray[SIZE]; |
|
131 |
|
132 ret = wcstombs(carray, (const wchar_t *)buf.PtrZ(), SIZE ); |
|
133 printf("TBuf converted to char buffer : %s\n",carray); |
|
134 getchar(); |
|
135 return (1); |
|
136 } |
|
137 </codeblock> </section> |
|
138 <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 |
|
139 to convert <codeph>TBuf8</codeph> to <codeph>wchar_t</codeph></title> |
|
140 <p>A <codeph>TBuf8</codeph> buffer can be converted to <codeph>wchar_t</codeph> using |
|
141 the <codeph>mbstowcs</codeph> API.</p><codeblock xml:space="preserve">#include <e32base.h> |
|
142 #include <sys/types.h> |
|
143 #include <stdio.h> |
|
144 #include <stdlib.h> |
|
145 #include <wchar.h> |
|
146 |
|
147 #define SIZE 20 |
|
148 |
|
149 int main (void) |
|
150 { |
|
151 TBuf8<SIZE> buf(_L8("hello")); |
|
152 size_t ret; |
|
153 wchar_t warray[SIZE]; |
|
154 |
|
155 ret = mbstowcs(warray, (const char *)buf.PtrZ(), SIZE ); |
|
156 printf("TBuf8 converted to wchar buffer : %ls\n",warray); |
|
157 getchar(); |
|
158 |
|
159 return (1); |
|
160 } |
|
161 </codeblock> </section> |
|
162 <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 |
|
163 to convert <codeph>TText16</codeph> to <codeph>char</codeph></title> |
|
164 <p>The <codeph>wcstombs</codeph> API can be used to convert a <codeph>TText16</codeph> buffer |
|
165 to a <codeph>char</codeph> buffer. This is one of the examples of converting |
|
166 from a Symbian data type to a C data type.</p><codeblock xml:space="preserve">#include <e32def.h> |
|
167 #include <sys/types.h> |
|
168 #include <stdio.h> |
|
169 #include <stdlib.h> |
|
170 #include <wchar.h> |
|
171 |
|
172 #define SIZE 32 |
|
173 |
|
174 int main (void) |
|
175 { |
|
176 TText arr[SIZE] = L"abcdef"; |
|
177 char carray[SIZE]; |
|
178 size_t ret; |
|
179 |
|
180 ret = wcstombs(carray, (const wchar_t *)arr, SIZE); |
|
181 printf("TText converted to char buffer : %s",carray); |
|
182 getchar(); |
|
183 |
|
184 return (1); |
|
185 } |
|
186 </codeblock> </section> |
|
187 <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 |
|
188 to convert a <codeph>char</codeph> array and a <codeph>wide char</codeph> array</title> |
|
189 <p>To use both <codeph>char</codeph> and <codeph>wide char</codeph> pointers |
|
190 or array in the program, the user must convert buffers from a <codeph>char</codeph> to |
|
191 a <codeph>wide char</codeph> and vice versa. Wide character APIs provide methods |
|
192 to: </p><ul> |
|
193 <li><p>convert a <codeph>char</codeph> array to a <codeph>wide char</codeph> array</p></li> |
|
194 <li><p>convert a <codeph>wide char</codeph> array to a <codeph>char</codeph> array </p></li> |
|
195 </ul><p><b>Converting a <codeph>char</codeph> array to a <codeph>wide char</codeph> array</b></p><p>The <codeph>mbstowcs</codeph> API |
|
196 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> |
|
197 #include <wchar.h> |
|
198 |
|
199 #define ARRAY_SIZE 32 |
|
200 |
|
201 int main(void) |
|
202 { |
|
203 char *carray = "char array"; |
|
204 wchar_t warray[ARRAY_SIZE]; |
|
205 size_t ret; |
|
206 |
|
207 ret = mbstowcs(warray, (const char *)carray, ARRAY_SIZE); |
|
208 wprintf(L"character array contents : %s\n",carray); |
|
209 wprintf(L"wide char array contents : %ls\n",warray); |
|
210 getwchar(); |
|
211 |
|
212 return (1); |
|
213 } |
|
214 </codeblock><p><b>Converting a <codeph>wide char</codeph> array to a <codeph>char</codeph> array </b></p><p>The <codeph>wcstombs</codeph> API |
|
215 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> |
|
216 #include <wchar.h> |
|
217 |
|
218 #define ARRAY_SIZE 32 |
|
219 |
|
220 int main(void) |
|
221 { |
|
222 wchar_t *warray = L"wide array"; |
|
223 char carray[ARRAY_SIZE]; |
|
224 size_t ret; |
|
225 |
|
226 ret = wcstombs(carray, (const wchar_t *)warray, ARRAY_SIZE); |
|
227 wprintf(L"wide char array contents : %ls\n",warray); |
|
228 wprintf(L"character array contents : %s\n",carray); |
|
229 getwchar(); |
|
230 |
|
231 return (1); |
|
232 } |
|
233 </codeblock> </section> |
|
234 <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 |
|
235 to declare a <codeph>wide-char</codeph> string</title> <p>To declare |
|
236 a <codeph>wide-char</codeph> string, prefix the string with 'L' |
|
237 [Capital L]. </p><codeblock xml:space="preserve">#include <wchar.h> |
|
238 |
|
239 int main(void) |
|
240 { |
|
241 wchar_t *wptr = L"This is a wide char string"; |
|
242 |
|
243 wprintf(L"%ls\n",wptr); |
|
244 getwchar(); |
|
245 } |
|
246 </codeblock> </section> |
|
247 </conbody></concept> |