7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-F46D5A5B-EC44-53B0-9A11-886735B28610" xml:lang="en"><title>How to |
12 <concept id="GUID-F46D5A5B-EC44-53B0-9A11-886735B28610" xml:lang="en"><title>How to use the modifiable pointer descriptor — TPtr</title><shortdesc>Modifiable pointer descriptors are useful for referencing |
13 use the modifiable pointer descriptor — TPtr</title><shortdesc>Modifiable pointer descriptors are useful for referencing strings |
13 strings or data which can be accessed and changed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 or data which can be accessed and changed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
14 <ul> |
16 <li id="GUID-80F50BD5-A919-5EB3-B28E-4BDF7A2A0121"><p>For text data, it is |
15 <li id="GUID-80F50BD5-A919-5EB3-B28E-4BDF7A2A0121"><p>For text data, |
17 usual to construct a <codeph>TPtr</codeph> type and allow the appropriate |
16 it is usual to construct a <codeph>TPtr</codeph> type and allow the |
18 variant, either a <codeph>TPtr</codeph> or a <codeph>TPtrC</codeph> to be |
17 appropriate variant, either a <codeph>TPtr</codeph> or a <codeph>TPtrC</codeph> to be selected at build time.</p> </li> |
19 selected at build time.</p> </li> |
18 <li id="GUID-965CB6DC-DE3E-5744-A6D8-10C9A0567011"><p>For binary data, |
20 <li id="GUID-965CB6DC-DE3E-5744-A6D8-10C9A0567011"><p>For binary data, an |
19 an explicit <codeph>TPtr8</codeph> is used.</p> </li> |
21 explicit <codeph>TPtr8</codeph> is used.</p> </li> |
20 <li id="GUID-40B8DB60-33DB-56D3-BDE7-263B1B48840E"><p>It is rare to |
22 <li id="GUID-40B8DB60-33DB-56D3-BDE7-263B1B48840E"><p>It is rare to use an |
21 use an explicit <codeph>TPtr16</codeph>.</p> </li> |
23 explicit <codeph>TPtr16</codeph>.</p> </li> |
|
24 </ul> |
22 </ul> |
25 <section id="GUID-AEBBFA2C-D87D-48F8-ADBF-0A042F371EC1"><title>Constructing a TPtr</title> <p>A modifiable pointer descriptor |
23 <section id="GUID-AEBBFA2C-D87D-48F8-ADBF-0A042F371EC1"><title>Constructing |
26 can be constructed in a number of ways:</p> <ul> |
24 a TPtr</title> <p>A modifiable pointer descriptor can be constructed |
27 <li id="GUID-C3767C93-A5BA-5B09-A90D-FAD74E9CDC3F"><p>another modifiable pointer |
25 in a number of ways:</p> <ul> |
28 descriptor.</p> </li> |
26 <li id="GUID-C3767C93-A5BA-5B09-A90D-FAD74E9CDC3F"><p>another modifiable |
|
27 pointer descriptor.</p> </li> |
29 <li id="GUID-9704F005-0931-5DA0-B4C7-7F263270300C"><p>from a non-modifiable |
28 <li id="GUID-9704F005-0931-5DA0-B4C7-7F263270300C"><p>from a non-modifiable |
30 buffer descriptor using the <codeph>Des()</codeph> function</p> </li> |
29 buffer descriptor using the <codeph>Des()</codeph> function</p> </li> |
31 <li id="GUID-2F09FD0B-7FE7-5D4E-B353-233B2609F9FC"><p>from an explicit pointer |
30 <li id="GUID-2F09FD0B-7FE7-5D4E-B353-233B2609F9FC"><p>from an explicit |
32 into memory and specifying a maximum length.</p> </li> |
31 pointer into memory and specifying a maximum length.</p> </li> |
33 <li id="GUID-F9C4E446-B390-56AD-8771-A0C393ADA246"><p>from an explicit pointer |
32 <li id="GUID-F9C4E446-B390-56AD-8771-A0C393ADA246"><p>from an explicit |
34 into memory and specifying the length of the data and a maximum length.</p> </li> |
33 pointer into memory and specifying the length of the data and a maximum |
35 </ul> <p>The following code fragment constructs a <codeph>TPtr</codeph> to |
34 length.</p> </li> |
36 represent the data already represented by another <codeph>TPtr</codeph>:</p> <codeblock id="GUID-B9296BAB-8B81-52C4-9730-2290C357656A" xml:space="preserve">TPtr ptr1; |
35 </ul> <p>The following code fragment constructs a <codeph>TPtr</codeph> to represent the data already represented by another <codeph>TPtr</codeph>:</p> <codeblock id="GUID-B9296BAB-8B81-52C4-9730-2290C357656A" xml:space="preserve">TPtr ptr1; |
37 ... |
36 ... |
38 TPtr ptr2(ptr1); |
37 TPtr ptr2(ptr1); |
39 ...</codeblock> <p>The following code fragment constructs a <codeph>TPtr</codeph> for |
38 ...</codeblock> <p>The following code fragment constructs a <codeph>TPtr</codeph> for a non-modifiable buffer descriptor, a <codeph>TBufC<TInt></codeph>, using the <codeph>Des()</codeph> function. Data that would normally |
40 a non-modifiable buffer descriptor, a <codeph>TBufC<TInt></codeph>, using |
39 be unmodifiable through the <codeph>TBufC<TInt></codeph> can be |
41 the <codeph>Des()</codeph> function. Data that would normally be unmodifiable |
40 changed through the <codeph>TPtr</codeph>.</p> <p>The source are literals |
42 through the <codeph>TBufC<TInt></codeph> can be changed through the <codeph>TPtr</codeph>.</p> <p>The |
41 which are converted to descriptor type.</p> <codeblock id="GUID-86F2890B-6AD2-5637-90B6-469554026C12" xml:space="preserve">_LIT(KText,"Hello World!"); |
43 source are literals which are converted to descriptor type.</p> <codeblock id="GUID-86F2890B-6AD2-5637-90B6-469554026C12" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
44 _LIT(KExtraText," & Hi"); |
42 _LIT(KExtraText," & Hi"); |
45 ... |
43 ... |
46 TBufC<16> buf1(KText); |
44 TBufC<16> buf1(KText); |
47 ... |
45 ... |
48 TPtr ptr = buf1.Des(); |
46 TPtr ptr = buf1.Des(); |
49 ... |
47 ... |
50 ptr.Delete((ptr.Length()-1),1); |
48 ptr.Delete((ptr.Length()-1),1); |
51 ptr.Append(KExtraText);</codeblock> <p>Define a <codeph>TText</codeph> area |
49 ptr.Append(KExtraText);</codeblock> <p>Define a <codeph>TText</codeph> area initialised to contain the string "Have a nice day":</p> <p>The following code fragments show the construction of a <codeph>TPtr</codeph> using a pointer and specifying a length and a maximum length. This |
52 initialised to contain the string "Have a nice day":</p> <p>The following |
50 technique is not commonly used. Literals are a much better way of |
53 code fragments show the construction of a <codeph>TPtr</codeph> using a pointer |
51 defining string constants.</p> <codeblock id="GUID-998F1C38-942B-53F5-BBC5-E33781AF1253" xml:space="preserve">TText str[16] = {'H', 'a', 'v', 'e', ' ', 'a', |
54 and specifying a length and a maximum length. This technique is not commonly |
|
55 used. Literals are a much better way of defining string constants.</p> <codeblock id="GUID-998F1C38-942B-53F5-BBC5-E33781AF1253" xml:space="preserve">TText str[16] = {'H', 'a', 'v', 'e', ' ', 'a', |
|
56 ' ', 'n', 'i', 'c', 'e', |
52 ' ', 'n', 'i', 'c', 'e', |
57 ' ', 'd', 'a', 'y', '\0'};</codeblock> <codeblock id="GUID-EF4302BB-F536-5B20-B109-1505688B8B60" xml:space="preserve">TPtr ptr(&str[0],15,16);</codeblock> <p>The |
53 ' ', 'd', 'a', 'y', '\0'};</codeblock> <codeblock id="GUID-EF4302BB-F536-5B20-B109-1505688B8B60" xml:space="preserve">TPtr ptr(&str[0],15,16);</codeblock> <p>The descriptor <codeph>ptr</codeph> represents the data in <codeph>str</codeph> and is constructed to have a current length of 15 (the |
58 descriptor <codeph>ptr</codeph> represents the data in <codeph>str</codeph> and |
54 length of the text, excluding the zero terminator) and a maximum length |
59 is constructed to have a current length of 15 (the length of the text, excluding |
55 of 16 (the actual length of <codeph>str</codeph>). Once the descriptor |
60 the zero terminator) and a maximum length of 16 (the actual length of <codeph>str</codeph>). |
56 has been constructed, it has no further use for the zero terminator.</p> <codeblock id="GUID-23A4799F-7B57-5B2B-B549-2BD168D208EC" xml:space="preserve">TPtr ptr(&str[0],15,16);</codeblock> </section> |
61 Once the descriptor has been constructed, it has no further use for the zero |
57 <section id="GUID-AA957AF0-8791-446C-B6E3-DD5EDB642E9E"><title>Replacing |
62 terminator.</p> <codeblock id="GUID-23A4799F-7B57-5B2B-B549-2BD168D208EC" xml:space="preserve">TPtr ptr(&str[0],15,16);</codeblock> </section> |
58 data through the TPtr</title> <p>Data can be completely replaced using |
63 <section id="GUID-AA957AF0-8791-446C-B6E3-DD5EDB642E9E"><title>Replacing data through the TPtr</title> <p>Data can be completely |
59 the assignment operator or the <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> function.:</p> <codeblock id="GUID-DBF0A411-CA03-5EAD-AFCD-1617C52C195F" xml:space="preserve">_LIT(KText,"Hi there"); |
64 replaced using the assignment operator or the <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> function.:</p> <codeblock id="GUID-DBF0A411-CA03-5EAD-AFCD-1617C52C195F" xml:space="preserve">_LIT(KText,"Hi there"); |
|
65 ... |
60 ... |
66 ptr = KText; |
61 ptr = KText; |
67 ... |
62 ... |
68 ptr.Copy(KText);</codeblock> <p>Note the use of the <codeph>_LIT</codeph> macro |
63 ptr.Copy(KText);</codeblock> <p>Note the use of the <codeph>_LIT</codeph> macro to define the source string. A literal is converted into a |
69 to define the source string. A literal is converted into a descriptor type.</p> <p>The |
64 descriptor type.</p> <p>The length of <codeph>ptr</codeph> is now |
70 length of <codeph>ptr</codeph> is now 8 but the maximum length remains unchanged. |
65 8 but the maximum length remains unchanged. The size depends on the |
71 The size depends on the build variant. In a non-Unicode build, this is 8 but |
66 build variant. In a non-Unicode build, this is 8 but in a Unicode |
72 in a Unicode build, this becomes 16 (two bytes for every character).</p> </section> |
67 build, this becomes 16 (two bytes for every character).</p> </section> |
73 <section id="GUID-4A13D438-C058-4370-970E-1139708758E3"><title>Changing the length of data</title> <p>The length of the data |
68 <section id="GUID-4A13D438-C058-4370-970E-1139708758E3"><title>Changing |
74 represented can be changed. </p> <codeblock id="GUID-0AE02AC5-2E85-5950-894A-FF7B6C8C5856" xml:space="preserve">_LIT(KText,"Hi there"); |
69 the length of data</title> <p>The length of the data represented can |
|
70 be changed. </p> <codeblock id="GUID-0AE02AC5-2E85-5950-894A-FF7B6C8C5856" xml:space="preserve">_LIT(KText,"Hi there"); |
75 ... |
71 ... |
76 ptr = KText; |
72 ptr = KText; |
77 ptr.SetLength(2); |
73 ptr.SetLength(2); |
78 ptr.Zero(); |
74 ptr.Zero(); |
79 </codeblock> <p>For example, after <codeph>ptr.SetLength(2)</codeph>, the |
75 </codeblock> <p>For example, after <codeph>ptr.SetLength(2)</codeph>, the descriptor represents the string "Hi". The length can even |
80 descriptor represents the string "Hi". The length can even be set to zero |
76 be set to zero so that after <codeph>ptr.Zero()</codeph>, the descriptor |
81 so that after <codeph>ptr.Zero()</codeph>, the descriptor represents no data. |
77 represents no data. Nevertheless, the maximum length remains unchanged.</p> </section> |
82 Nevertheless, the maximum length remains unchanged.</p> </section> |
|
83 </conbody><related-links> |
78 </conbody><related-links> |
84 <link> |
79 <link href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita"><linktext>Literal |
85 <desc><xref href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita">Literal Descriptors</xref></desc> |
80 Descriptors</linktext></link> |
86 </link> |
|
87 </related-links></concept> |
81 </related-links></concept> |