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-E81D72B2-BA77-5F4E-8742-3812A60A4DAC" xml:lang="en"><title>How to |
12 <concept id="GUID-E81D72B2-BA77-5F4E-8742-3812A60A4DAC" xml:lang="en"><title>How to use modifiable buffer descriptor — TBuf<TInt></title><shortdesc>Modifiable buffer descriptors are useful for holding strings |
13 use modifiable buffer descriptor — TBuf<TInt></title><shortdesc>Modifiable buffer descriptors are useful for holding strings or |
13 or data and providing safe ways to access and modify that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 data and providing safe ways to access and modify that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
14 <ul> |
16 <li id="GUID-F276E9FE-B839-54ED-9F50-8E45CB094922"><p>For text data, it is |
15 <li id="GUID-F276E9FE-B839-54ED-9F50-8E45CB094922"><p>For text data, |
17 usual to construct a <codeph>TBuf<TInt></codeph> type and allow the appropriate |
16 it is usual to construct a <codeph>TBuf<TInt></codeph> type and |
18 variant, either a <codeph>TBuf8<TInt></codeph> or a <codeph>TBuf16<TInt></codeph> to |
17 allow the appropriate variant, either a <codeph>TBuf8<TInt></codeph> or a <codeph>TBuf16<TInt></codeph> to be selected at build time.</p> </li> |
19 be selected at build time.</p> </li> |
18 <li id="GUID-9860DB57-62C3-5295-B00E-5F629771FED9"><p>For binary data, |
20 <li id="GUID-9860DB57-62C3-5295-B00E-5F629771FED9"><p>For binary data, an |
19 an explicit <codeph>TBuf8<TInt></codeph> is used.</p> </li> |
21 explicit <codeph>TBuf8<TInt></codeph> is used.</p> </li> |
20 <li id="GUID-34C95FAB-0F58-5B61-B9FC-A31588855F96"><p>It is rare to |
22 <li id="GUID-34C95FAB-0F58-5B61-B9FC-A31588855F96"><p>It is rare to use an |
21 use an explicit <codeph>TBuf16<TInt></codeph>.</p> </li> |
23 explicit <codeph>TBuf16<TInt></codeph>.</p> </li> |
|
24 </ul> |
22 </ul> |
25 <p>Although, the following notes refer to the build independent types; they |
23 <p>Although, the following notes refer to the build independent types; |
26 are equally valid for the explicit 8 bit and 16 bit types.</p> |
24 they are equally valid for the explicit 8 bit and 16 bit types.</p> |
27 <section id="GUID-824524FB-98B7-4CDA-A3FD-233C7C0DDD5F"><title>Constructing |
25 <section id="GUID-824524FB-98B7-4CDA-A3FD-233C7C0DDD5F"><title>Constructing |
28 a TBuf<TInt></title> <p>A modifiable buffer descriptor can be constructed |
26 a TBuf<TInt></title> <p>A modifiable buffer descriptor can be constructed |
29 in a number of ways:</p> <ul> |
27 in a number of ways:</p> <ul> |
30 <li id="GUID-BCFAA769-D038-5A09-B6BF-586C93F08B0B"><p>as an empty buffer descriptor.</p> </li> |
28 <li id="GUID-BCFAA769-D038-5A09-B6BF-586C93F08B0B"><p>as an empty |
31 <li id="GUID-9DE61358-D6B9-54CA-9FED-11AC29443093"><p>as an empty buffer descriptor |
29 buffer descriptor.</p> </li> |
32 but giving it a length.</p> </li> |
30 <li id="GUID-9DE61358-D6B9-54CA-9FED-11AC29443093"><p>as an empty |
33 <li id="GUID-50FB7967-79C8-5F8C-8569-36B40D14894E"><p>by copying data from |
31 buffer descriptor but giving it a length.</p> </li> |
34 any other type of descriptor.</p> </li> |
32 <li id="GUID-50FB7967-79C8-5F8C-8569-36B40D14894E"><p>by copying data |
35 <li id="GUID-26E1FDDC-F0BB-5441-8F81-EF2CFA61787A"><p>by copying data from |
33 from any other type of descriptor.</p> </li> |
36 another modifiable buffer descriptor of the same size.</p> </li> |
34 <li id="GUID-26E1FDDC-F0BB-5441-8F81-EF2CFA61787A"><p>by copying data |
37 </ul> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object. |
35 from another modifiable buffer descriptor of the same size.</p> </li> |
38 The buffer descriptor is uninitialised, i.e. it contains no data. The assignment |
36 </ul> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object. The buffer descriptor is uninitialised, i.e. it contains |
39 operator or the <codeph>Copy()</codeph> function can be used to put data into |
37 no data. The assignment operator or the <codeph>Copy()</codeph> function |
40 the buffer descriptor after construction:</p> <codeblock id="GUID-01CA390C-ECC4-56C2-A1F6-F62C2AA75E57" xml:space="preserve">_LIT(KText,"Hello World!"); |
38 can be used to put data into the buffer descriptor after construction:</p> <codeblock id="GUID-01CA390C-ECC4-56C2-A1F6-F62C2AA75E57" xml:space="preserve">_LIT(KText,"Hello World!"); |
41 ... |
39 ... |
42 TBuf<16> buf1; // length of buf1 is 0 |
40 TBuf<16> buf1; // length of buf1 is 0 |
43 ... |
41 ... |
44 buf1 = KText; // data assigned</codeblock> <p>The source descriptor is a |
42 buf1 = KText; // data assigned</codeblock> <p>The source descriptor |
45 literal which is converted to descriptor type.</p> <p>The following code fragment |
43 is a literal which is converted to descriptor type.</p> <p>The following |
46 constructs a <codeph>TBuf<16></codeph> object and sets it length to 12. |
44 code fragment constructs a <codeph>TBuf<16></codeph> object and |
47 No data is assigned into the descriptor.</p> <codeblock id="GUID-FA8A1FE8-7809-5E28-B3EB-420B405DDC32" xml:space="preserve">... |
45 sets it length to 12. No data is assigned into the descriptor.</p> <codeblock id="GUID-FA8A1FE8-7809-5E28-B3EB-420B405DDC32" xml:space="preserve">... |
48 TBuf<16> buf1(12); // length of buf1 is 12 |
46 TBuf<16> buf1(12); // length of buf1 is 12 |
49 ...</codeblock> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object, |
47 ...</codeblock> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object, initialised with the 12 characters making |
50 initialised with the 12 characters making up the English language phrase "Hello |
48 up the English language phrase "Hello World!".</p> <codeblock id="GUID-74B4614D-4273-5F9E-8A2D-1E9A8A3960D8" xml:space="preserve">_LIT(KText,"Hello World!"); |
51 World!".</p> <codeblock id="GUID-74B4614D-4273-5F9E-8A2D-1E9A8A3960D8" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
52 ... |
49 ... |
53 TBuf<16> buf1(KText);</codeblock> <p>The following code fragment constructs |
50 TBuf<16> buf1(KText);</codeblock> <p>The following code fragment |
54 a <codeph>TBuf<16></codeph> object from another <codeph>TBuf<16></codeph> object. |
51 constructs a <codeph>TBuf<16></codeph> object from another <codeph>TBuf<16></codeph> object. This is, in effect, copy construction.</p> <codeblock id="GUID-BE55436F-FDB8-5768-947F-801D02FDA631" xml:space="preserve">_LIT(KText,"Hello World!"); |
55 This is, in effect, copy construction.</p> <codeblock id="GUID-BE55436F-FDB8-5768-947F-801D02FDA631" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
56 ... |
52 ... |
57 TBuf<16> buf1(KText); |
53 TBuf<16> buf1(KText); |
58 TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1</codeblock> <p>In |
54 TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1</codeblock> <p>In both of these cases, the resulting length of the descriptor |
59 both of these cases, the resulting length of the descriptor is 12.</p> <p>A |
55 is 12.</p> <p>A non-modifiable buffer descriptor can also be constructed |
60 non-modifiable buffer descriptor can also be constructed from 'C' style zero |
56 from 'C' style zero terminated string. However, this is rarely necessary |
61 terminated string. However, this is rarely necessary but may make it easier |
57 but may make it easier to port legacy 'C' code.</p> </section> |
62 to port legacy 'C' code.</p> </section> |
58 <section id="GUID-8A534041-1730-43FB-8FCD-4C5BFDAAE730"><title>Replacing |
63 <section id="GUID-8A534041-1730-43FB-8FCD-4C5BFDAAE730"><title>Replacing data</title> <p>Data |
59 data</title> <p>Data within a modifiable buffer descriptor can be |
64 within a modifiable buffer descriptor can be completely replaced through the |
60 completely replaced through the assignment operator or by using the <codeph>Copy()</codeph> function.</p> <codeblock id="GUID-D990C115-DD84-5E04-89DA-F483A63D03FA" xml:space="preserve">_LIT(KText,"Hello World!"); |
65 assignment operator or by using the <codeph>Copy()</codeph> function.</p> <codeblock id="GUID-D990C115-DD84-5E04-89DA-F483A63D03FA" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
66 _LIT(KNewText,"New text"); |
61 _LIT(KNewText,"New text"); |
67 _LIT(KReplaced,"Replaced"); |
62 _LIT(KReplaced,"Replaced"); |
68 ... |
63 ... |
69 TBuf<16> buf1(KText); |
64 TBuf<16> buf1(KText); |
70 TBuf<16> buf2; |
65 TBuf<16> buf2; |
73 ... |
68 ... |
74 buf2 = KNewText; // buf2 now contains "New text". |
69 buf2 = KNewText; // buf2 now contains "New text". |
75 // the literal is converted to a descriptor |
70 // the literal is converted to a descriptor |
76 // type. |
71 // type. |
77 buf2.Copy(KReplaced); // buf2 content replaced using Copy()</codeblock> </section> |
72 buf2.Copy(KReplaced); // buf2 content replaced using Copy()</codeblock> </section> |
78 <section id="GUID-E49444E0-457E-4645-A1D5-C350FF998F9A"><title>Accessing and |
73 <section id="GUID-E49444E0-457E-4645-A1D5-C350FF998F9A"><title>Accessing |
79 changing data</title> <p>Once a modifiable buffer descriptor has been constructed, |
74 and changing data</title> <p>Once a modifiable buffer descriptor has |
80 the functions in the base classes, <codeph>TDesC</codeph> and <codeph>TDes</codeph>, |
75 been constructed, the functions in the base classes, <codeph>TDesC</codeph> and <codeph>TDes</codeph>, are available to be access and change |
81 are available to be access and change the data.</p> <codeblock id="GUID-386035F7-1C0F-5CB3-BA5B-5E0EF18DF6F8" xml:space="preserve">_LIT(KText,"Hello World!"); |
76 the data.</p> <codeblock id="GUID-386035F7-1C0F-5CB3-BA5B-5E0EF18DF6F8" xml:space="preserve">_LIT(KText,"Hello World!"); |
82 ... |
77 ... |
83 TBufC<16> buf1(KText); |
78 TBufC<16> buf1(KText); |
84 ... |
79 ... |
85 buf1.Length();</codeblock> <p>and</p> <codeblock id="GUID-7BCC4118-4294-5607-A92B-5DBA9E68CBEE" xml:space="preserve">_LIT(KText,"Hello World!"); |
80 buf1.Length();</codeblock> <p>and</p> <codeblock id="GUID-7BCC4118-4294-5607-A92B-5DBA9E68CBEE" xml:space="preserve">_LIT(KText,"Hello World!"); |
86 ... |
81 ... |
87 TBufC<16> buf1(KText); // length is 12 |
82 TBufC<16> buf1(KText); // length is 12 |
88 ... |
83 ... |
89 buf1.Delete(6,6); // length is now 6, leaving "Hello" in |
84 buf1.Delete(6,6); // length is now 6, leaving "Hello" in |
90 // the buffer</codeblock> </section> |
85 // the buffer</codeblock> </section> |
91 <section id="GUID-970BCE5F-CC4D-4F60-91A9-6107975E9C3F"><title>Illegal access |
86 <section id="GUID-970BCE5F-CC4D-4F60-91A9-6107975E9C3F"><title>Illegal |
92 causing an exception</title> <p>The following code fragment raises a panic |
87 access causing an exception</title> <p>The following code fragment |
93 because of an attempt to assign too much data. The maximum length of the buffer |
88 raises a panic because of an attempt to assign too much data. The |
94 descriptor is 16 but the length of the data to be copied is 31:</p> <codeblock id="GUID-38DC46A1-E2A0-52DD-A821-F0D6B2C45430" xml:space="preserve">_LIT(KText,"Hello World! The sun is shining"); |
89 maximum length of the buffer descriptor is 16 but the length of the |
|
90 data to be copied is 31:</p> <codeblock id="GUID-38DC46A1-E2A0-52DD-A821-F0D6B2C45430" xml:space="preserve">_LIT(KText,"Hello World! The sun is shining"); |
95 ... |
91 ... |
96 TBufC<16> buf1(KText);</codeblock> <p>The following code fragment raises |
92 TBufC<16> buf1(KText);</codeblock> <p>The following code fragment |
97 a panic because of an attempt to delete data outside the boundary defined |
93 raises a panic because of an attempt to delete data outside the boundary |
98 by the descriptor:</p> <codeblock id="GUID-71FB3EFC-BFBA-5072-ADD2-3471E2A08D0C" xml:space="preserve">_LIT(KText,"Hello World!"); |
94 defined by the descriptor:</p> <codeblock id="GUID-71FB3EFC-BFBA-5072-ADD2-3471E2A08D0C" xml:space="preserve">_LIT(KText,"Hello World!"); |
99 ... |
95 ... |
100 TBufC<16> buf1(KText); |
96 TBufC<16> buf1(KText); |
101 buf1.Delete(99,1);</codeblock> </section> |
97 buf1.Delete(99,1);</codeblock> </section> |
102 </conbody><related-links> |
98 </conbody><related-links> |
103 <link> |
99 <link href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita"> |
104 <desc><xref href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita">Literal Descriptors</xref></desc> |
100 <linktext>Literal Descriptors</linktext></link> |
105 </link> |
|
106 </related-links></concept> |
101 </related-links></concept> |