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-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A" xml:lang="en"><title>How to |
12 <concept id="GUID-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A" xml:lang="en"><title>How to use the non-modifiable buffer descriptor — TBufC<TInt></title><shortdesc>Non-modifiable buffer descriptors are useful for holding |
13 use the non-modifiable buffer descriptor — TBufC<TInt></title><shortdesc>Non-modifiable buffer descriptors are useful for holding constant |
13 constant strings or data and providing safe ways to access that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 strings or data and providing safe ways to access that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
14 <ul> |
16 <li id="GUID-74A075D5-195D-5BB7-BC40-D683635BE6F7"><p>For text data, it is |
15 <li id="GUID-74A075D5-195D-5BB7-BC40-D683635BE6F7"><p>For text data, |
17 usual to construct a <codeph>TBufC<TInt></codeph> type and allow the appropriate |
16 it is usual to construct a <codeph>TBufC<TInt></codeph> type and |
18 variant, either a <codeph>TBufC8<TInt></codeph> or a <codeph>TBufC16<TInt></codeph> to |
17 allow the appropriate variant, either a <codeph>TBufC8<TInt></codeph> or a <codeph>TBufC16<TInt></codeph> to be selected at build time.</p> </li> |
19 be selected at build time.</p> </li> |
18 <li id="GUID-0AA8DD41-55DF-5448-A5D5-DC403E60C3A4"><p>For binary data, |
20 <li id="GUID-0AA8DD41-55DF-5448-A5D5-DC403E60C3A4"><p>For binary data, an |
19 an explicit <codeph>TBufC8<TInt></codeph> is used.</p> </li> |
21 explicit <codeph>TBufC8<TInt></codeph> is used.</p> </li> |
20 <li id="GUID-441D5170-8C00-5BE6-AF0C-44DB149E87F1"><p>It is rare to |
22 <li id="GUID-441D5170-8C00-5BE6-AF0C-44DB149E87F1"><p>It is rare to use an |
21 use an explicit <codeph>TBufC16<TInt></codeph>.</p> </li> |
23 explicit <codeph>TBufC16<TInt></codeph>.</p> </li> |
|
24 </ul> |
22 </ul> |
25 <p>Data cannot be changed through this descriptor although it can be replaced |
23 <p>Data cannot be changed through this descriptor although it can |
26 using the assignment operators.</p> |
24 be replaced using the assignment operators.</p> |
27 <p>By using the <codeph>Des()</codeph> function to construct a <codeph>TPtr/TPtr8/TPtr16</codeph> modifiable |
25 <p>By using the <codeph>Des()</codeph> function to construct a <codeph>TPtr/TPtr8/TPtr16</codeph> modifiable pointer descriptor for the |
28 pointer descriptor for the buffer's data, it becomes possible to modify that |
26 buffer's data, it becomes possible to modify that data.</p> |
29 data.</p> |
27 <p>Although, the following notes refer to the build independent types; |
30 <p>Although, the following notes refer to the build independent types; they |
28 they are equally valid for the explicit 8 bit and 16 bit types.</p> |
31 are equally valid for the explicit 8 bit and 16 bit types.</p> |
29 <section id="GUID-5591AC50-485E-413D-B3A7-BCE59F3B634D"><title>Constructing |
32 <section id="GUID-5591AC50-485E-413D-B3A7-BCE59F3B634D"><title>Constructing a TBufC<TInt></title> <p>A non-modifiable |
30 a TBufC<TInt></title> <p>A non-modifiable buffer descriptor can |
33 buffer descriptor can be constructed in a number of ways:</p> <ul> |
31 be constructed in a number of ways:</p> <ul> |
34 <li id="GUID-8328A45B-EB36-5C80-9B3D-969DA033B71E"><p>as an empty buffer descriptor.</p> </li> |
32 <li id="GUID-8328A45B-EB36-5C80-9B3D-969DA033B71E"><p>as an empty |
35 <li id="GUID-D0CDC7BA-A2A2-5953-8700-F43FF5FD2AE2"><p>by copying data from |
33 buffer descriptor.</p> </li> |
36 any other type of descriptor.</p> </li> |
34 <li id="GUID-D0CDC7BA-A2A2-5953-8700-F43FF5FD2AE2"><p>by copying data |
37 <li id="GUID-A7CC00D3-16AB-5D2F-B25E-011D689C3BA9"><p>by copying data from |
35 from any other type of descriptor.</p> </li> |
38 another non-modifiable buffer descriptor of the same size.</p> </li> |
36 <li id="GUID-A7CC00D3-16AB-5D2F-B25E-011D689C3BA9"><p>by copying data |
39 </ul> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object. |
37 from another non-modifiable buffer descriptor of the same size.</p> </li> |
40 The buffer descriptor is uninitialised, i.e. it contains no data. The assignment |
38 </ul> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object. The buffer descriptor is uninitialised, i.e. it contains |
41 operator can be used to put data into the buffer descriptor after construction:</p> <codeblock id="GUID-BED8AC0B-4F0B-5859-994B-723F4B8F84A1" xml:space="preserve">_LIT(KText,"Hello World!"); |
39 no data. The assignment operator can be used to put data into the |
|
40 buffer descriptor after construction:</p> <codeblock id="GUID-BED8AC0B-4F0B-5859-994B-723F4B8F84A1" xml:space="preserve">_LIT(KText,"Hello World!"); |
42 ... |
41 ... |
43 TBufC<16> buf1; // length of buf1 is 0 |
42 TBufC<16> buf1; // length of buf1 is 0 |
44 ... |
43 ... |
45 buf1 = KText; // data assigned</codeblock> <p>The following code fragment |
44 buf1 = KText; // data assigned</codeblock> <p>The following code |
46 constructs a <codeph>TBufC<16></codeph> object, initialised with the 12 |
45 fragment constructs a <codeph>TBufC<16></codeph> object, initialised |
47 characters making up the English language phrase "Hello World!".</p> <p>The |
46 with the 12 characters making up the English language phrase "Hello |
48 source descriptor is a literal which is converted to descriptor type.</p> <codeblock id="GUID-737E0C5F-AE11-586D-B81C-0E3D1AD96414" xml:space="preserve">_LIT(KText,"Hello World!"); |
47 World!".</p> <p>The source descriptor is a literal which is converted |
|
48 to descriptor type.</p> <codeblock id="GUID-737E0C5F-AE11-586D-B81C-0E3D1AD96414" xml:space="preserve">_LIT(KText,"Hello World!"); |
49 ... |
49 ... |
50 TBufC<16> buf1(KText); // length of buf1 is 12</codeblock> <p>The following |
50 TBufC<16> buf1(KText); // length of buf1 is 12</codeblock> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object, initialised with the content of another <codeph>TBufC<16></codeph> object.</p> <codeblock id="GUID-A8A21448-DBE4-5F68-8CA0-57298E04036C" xml:space="preserve">_LIT(KText,"Hello World!"); |
51 code fragment constructs a <codeph>TBufC<16></codeph> object, initialised |
|
52 with the content of another <codeph>TBufC<16></codeph> object.</p> <codeblock id="GUID-A8A21448-DBE4-5F68-8CA0-57298E04036C" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
53 ... |
51 ... |
54 TBufC<16> buf1(KText); |
52 TBufC<16> buf1(KText); |
55 TBufC<16> buf2(buf1); // data copied from descriptor buf1 |
53 TBufC<16> buf2(buf1); // data copied from descriptor buf1 |
56 // length of buf2 is 12</codeblock> </section> |
54 // length of buf2 is 12</codeblock> </section> |
57 <section id="GUID-1C814D9C-5F53-4885-90B9-B83480CF623E"><title>Replacing data</title> <p>Data within a non-modifiable buffer |
55 <section id="GUID-1C814D9C-5F53-4885-90B9-B83480CF623E"><title>Replacing |
58 descriptor can be completely replaced by using the assignment operator:</p> <codeblock id="GUID-C3F90B27-EB1C-5864-A80A-0D0C77BB67FC" xml:space="preserve">_LIT(KText,"Hello World!"); |
56 data</title> <p>Data within a non-modifiable buffer descriptor can |
|
57 be completely replaced by using the assignment operator:</p> <codeblock id="GUID-C3F90B27-EB1C-5864-A80A-0D0C77BB67FC" xml:space="preserve">_LIT(KText,"Hello World!"); |
59 _LIT(KNewText,"New text"); |
58 _LIT(KNewText,"New text"); |
60 ... |
59 ... |
61 TBufC<16> buf1(KText); |
60 TBufC<16> buf1(KText); |
62 TBufC<16> buf2; |
61 TBufC<16> buf2; |
63 ... |
62 ... |
64 buf2 = buf1; // buf2 now contains "Hello World!" |
63 buf2 = buf1; // buf2 now contains "Hello World!" |
65 ... |
64 ... |
66 buf2 = KNewText; // buf2 now contains "New text". |
65 buf2 = KNewText; // buf2 now contains "New text". |
67 // the literal is converted to a descriptor |
66 // the literal is converted to a descriptor |
68 // type.</codeblock> <p>To prevent data replacement, |
67 // type.</codeblock> <p>To prevent data |
69 declare <codeph>buf2</codeph> as const.</p> </section> |
68 replacement, declare <codeph>buf2</codeph> as const.</p> </section> |
70 <section id="GUID-5F3BEAB3-B469-4673-A3D8-04DB697B8D0F"><title>Constructing a modifiable pointer descriptor to change the |
69 <section id="GUID-5F3BEAB3-B469-4673-A3D8-04DB697B8D0F"><title>Constructing |
71 data</title> <p>The data contained in non-modifiable buffer descriptor <codeph>TBufC<TInt></codeph> <i>can</i> be |
70 a modifiable pointer descriptor to change the data</title> <p>The |
72 changed by constructing a <codeph>TPtr</codeph> modifiable pointer descriptor |
71 data contained in non-modifiable buffer descriptor <codeph>TBufC<TInt></codeph> <i>can</i> be changed by constructing a <codeph>TPtr</codeph> modifiable |
73 using the<codeph>Des()</codeph> member function and then changing the data |
72 pointer descriptor using the<codeph>Des()</codeph> member function |
74 through that <codeph>TPtr</codeph>.</p> <p>The maximum length of the <codeph>TPtr</codeph> is |
73 and then changing the data through that <codeph>TPtr</codeph>.</p> <p>The maximum length of the <codeph>TPtr</codeph> is the value |
75 the value of the <codeph>TBufC<TInt></codeph> template parameter.</p> <p>The |
74 of the <codeph>TBufC<TInt></codeph> template parameter.</p> <p>The following code fragment shows data being changed:</p> <codeblock id="GUID-02B09EBC-3E58-51B1-8D14-E388250A674A" xml:space="preserve">_LIT(KText,"Hello World!"); |
76 following code fragment shows data being changed:</p> <codeblock id="GUID-02B09EBC-3E58-51B1-8D14-E388250A674A" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
77 _LIT(KExtraText," & Hi"); |
75 _LIT(KExtraText," & Hi"); |
78 ... |
76 ... |
79 TBufC<16> buf1(KText); |
77 TBufC<16> buf1(KText); |
80 ... |
78 ... |
81 TPtr ptr = buf1.Des(); |
79 TPtr ptr = buf1.Des(); |
82 ... |
80 ... |
83 ptr.Delete((ptr.Length()-1),1); |
81 ptr.Delete((ptr.Length()-1),1); |
84 ptr.Append(KExtraText); |
82 ptr.Append(KExtraText); |
85 ...</codeblock> <p>This deletes the last character in <codeph>buf1</codeph> and |
83 ...</codeblock> <p>This deletes the last character in <codeph>buf1</codeph> and adds the characters " & Hi" so that <codeph>buf1</codeph> now contains the text "Hello World & Hi" and |
86 adds the characters " & Hi" so that <codeph>buf1</codeph> now contains |
84 its length is 16. Note that the length of both <codeph>buf1</codeph> and <codeph>ptr</codeph> change to reflect the data that they now |
87 the text "Hello World & Hi" and its length is 16. Note that the length |
85 both represent.</p> <p>Note that any attempt to append more data raises |
88 of both <codeph>buf1</codeph> and <codeph>ptr</codeph> change to reflect the |
86 a panic.</p> </section> |
89 data that they now both represent.</p> <p>Note that any attempt to append |
87 <section id="GUID-9DD4E5D1-B0A0-41BC-AE54-FC062D21173C"><title>Accessing |
90 more data raises a panic.</p> </section> |
88 data</title> <p>Once a non-modifiable buffer descriptor has been constructed, |
91 <section id="GUID-9DD4E5D1-B0A0-41BC-AE54-FC062D21173C"><title>Accessing data</title> <p>Once a non-modifiable buffer descriptor |
89 the functions in the base class, <codeph>TDesC</codeph>, are available |
92 has been constructed, the functions in the base class, <codeph>TDesC</codeph>, |
90 to access the data.</p> <codeblock id="GUID-CE288FF9-26F7-533D-ADC4-E535035039B2" xml:space="preserve">_LIT(KText,"Hello World!"); |
93 are available to access the data.</p> <codeblock id="GUID-CE288FF9-26F7-533D-ADC4-E535035039B2" xml:space="preserve">_LIT(KText,"Hello World!"); |
|
94 ... |
91 ... |
95 TBufC<16> buf1(KText); |
92 TBufC<16> buf1(KText); |
96 ...</codeblock> <codeblock id="GUID-656150B0-C7DF-54B7-9127-6BE685EEEA83" xml:space="preserve">buf1.Length();</codeblock> </section> |
93 ...</codeblock> <codeblock id="GUID-656150B0-C7DF-54B7-9127-6BE685EEEA83" xml:space="preserve">buf1.Length();</codeblock> </section> |
97 </conbody><related-links> |
94 </conbody><related-links> |
98 <link> |
95 <link href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita"> |
99 <desc><xref href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita">Literal Descriptors</xref></desc> |
96 <linktext>Literal Descriptors</linktext></link> |
100 </link> |
|
101 </related-links></concept> |
97 </related-links></concept> |