|
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-4C1F3DB3-039C-57D6-987F-4A26E1E056E6" xml:lang="en"><title>How to use the non-modifiable pointer descriptor - TPtrC</title><shortdesc>Non-modifiable pointer descriptors are useful for referencing |
|
13 constant strings or data; for example, accessing strings built into ROM |
|
14 resident code, or passing a reference to data in RAM which must not be modified |
|
15 through that reference.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><ul id="UL_83DD0FC743444EBB91D9DADAD05AA845"><li id="LI_1AE27A9C48A742059A1F92645EE8DC40">For text data, it is usual to construct a <codeph>TPtrC</codeph> type and allow the appropriate variant, either a <codeph>TPtrC8</codeph> or a <codeph>TPtrC16</codeph> to be selected at build time.</li><li id="LI_46611661D34840A984E5DB5E1B2F5C83">For binary data, an explicit <codeph>TPtrC8</codeph> is used.</li><li id="LI_8E40A85E05F34A24B96A6985B0219F26">It is rare to use an explicit <codeph>TPtrC16</codeph>.</li></ul> |
|
16 <section id="SECTION_5C848D1949114AB4B5B04399DE2E1D0C"> |
|
17 <title>Constructing a <codeph>TPtrC</codeph></title> |
|
18 <p>A non-modifiable pointer descriptor can be constructed in a number |
|
19 of ways:</p> |
|
20 <ul id="UL_285D678E37474863A9CDE0AC07563A22"> |
|
21 <li id="LI_FA3C5DEF26314DC4AD26D1C643A63439"> |
|
22 <p>any other descriptor.</p> |
|
23 </li> |
|
24 <li id="LI_5762D37490F24F0CA795213A8E9FF639"> |
|
25 <p>another non-modifiable pointer descriptor.</p> |
|
26 </li> |
|
27 <li id="LI_D44E9FC98D16448585130B89B27ECEE6"> |
|
28 <p>a pointer into memory and specifying the length of the |
|
29 data.</p> |
|
30 </li> |
|
31 <li id="LI_0270E00C05DD473C911B6EF4CC297814"> |
|
32 <p>a zero terminated string.</p> |
|
33 </li> |
|
34 </ul> |
|
35 <p>The following code fragment constructs a <codeph>TPtrC</codeph> to |
|
36 represent the data already represented by any other type of descriptor.</p> |
|
37 <p>The source descriptor is a literal which is converted to descriptor |
|
38 type.</p> |
|
39 <codeblock xml:space="preserve">_LIT(KText,"Hello World!"); |
|
40 ... |
|
41 TBufC<16> buf1(KText); // buf1 is the existing descriptor |
|
42 ... |
|
43 TPtrC ptr(buf1); // data in buf1 now accessible through ptr</codeblock> |
|
44 <p>The following code fragment constructs a <codeph>TPtrC</codeph> to |
|
45 represent the data already represented by another <codeph>TPtrC</codeph>.</p> |
|
46 <codeblock xml:space="preserve">_LIT(KText,"Hello World!"); |
|
47 ... |
|
48 TBufC<16> buf1(KText); // buf1 is the existing descriptor |
|
49 ... |
|
50 TPtrC ptr1(buf1); // data in buf1 now accessible through ptr1 |
|
51 TPtrC ptr2(ptr1); // data also accessible through ptr2</codeblock> |
|
52 <p>Although rarely used (possibly in porting legacy 'C' code), the |
|
53 following code fragment defines a constant <q>C</q> style non-Unicode |
|
54 string and then constructs the non-modifiable pointer descriptor for that |
|
55 string. The explicit 8 bit variant is used here. The descriptor is separate |
|
56 from the data it represents.</p> |
|
57 <codeblock xml:space="preserve">const TText8* cstr = (TText8*)"Hello World!"; |
|
58 ... |
|
59 TPtrC8 ptr(cstr); |
|
60 ... |
|
61 ptr.Length(); // The length is 12. |
|
62 ptr.Ptr(); // The address of the descriptor's data, |
|
63 // i.e. 'C' string.</codeblock> |
|
64 <p>The following code fragment shows construction from a pointer into |
|
65 memory and a length. The example assumes that both the pointer and the length |
|
66 have valid values:</p> |
|
67 <codeblock xml:space="preserve">TUint8* memptr; |
|
68 TInt length; |
|
69 ... |
|
70 TPtrC8 ptr(memptr,length);</codeblock></section> |
|
71 <section id="SECTION_BCAA81088E1E4473887D1E62F77AE2B1"> |
|
72 <title>Accessing data</title><p>Once a |
|
73 non-modifiable pointer descriptor has been constructed, the functions in the |
|
74 base class, <codeph>TDesC</codeph>, are available to access the |
|
75 data.</p><p>For example, given a pointer descriptor labelled ptr:#</p><codeblock xml:space="preserve">_LIT(KText,"Hello World!"); |
|
76 ... |
|
77 TBufC<16> buf1(KText); // buf1 is the existing descriptor |
|
78 ... |
|
79 TPtrC ptr(buf1); // data in buf1 now accessible through ptr |
|
80 ... |
|
81 ptr.Length(); // returns the length of the data (i.e. 12)</codeblock> |
|
82 |
|
83 |
|
84 </section> |
|
85 </conbody><related-links><link href="GUID-112AAFA5-B4C9-5B62-A106-FB5097C13A0E.dita"><linktext>Dynamic Buffers</linktext></link></related-links></concept> |