|
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-807B5CEE-CC1E-5A40-911F-3C5D5FA3633A" xml:lang="en"><title>How to |
|
13 use standard buffer operations</title><shortdesc>Explains the functions to read, write, insert, delete and compress |
|
14 data in buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>Dynamic buffers have the expected standard buffer operations.</p> |
|
16 <section id="GUID-7AC34BEB-0BAB-462D-A170-B42446625805"><title>InsertL() example</title> <p>You can insert data into a buffer |
|
17 using <codeph>InsertL()</codeph>. In the following example code fragment, |
|
18 data is inserted into the buffer initially, and then some more data inserted |
|
19 into the middle of the first data.</p> <codeblock id="GUID-0237C066-1F66-5D54-BA06-5FBFC8C0F1F4" xml:space="preserve"> // insert text into buffer |
|
20 _LIT8(KTxtHello,"Hello!"); |
|
21 _LIT8(KWorld," world"); |
|
22 ... |
|
23 aBuf->InsertL(0,KTxtHello); |
|
24 writeBuf(aBuf); // gives “Hello!” |
|
25 aBuf->InsertL(5,KWorld); |
|
26 writeBuf(aBuf); // gives “Hello world!”</codeblock> <p>In common with all |
|
27 functions that expand the size of the buffer, <codeph>InsertL()</codeph> may |
|
28 fail, by leaving. When you program with dynamic buffers, you must ensure that |
|
29 all potential leaves are handled correctly.</p> <p><codeph>InsertL()</codeph>, |
|
30 and the entire dynamic buffer API, deals only with 8-bit byte data. When interfacing |
|
31 with descriptors which contain text, you should take special precautions to |
|
32 ensure that UNICODE is handled correctly.</p> </section> |
|
33 <section id="GUID-9C234566-872B-44E0-BBB4-8892FB58E1DD"><title>Read() example</title> <p>Data can be read from a buffer by |
|
34 specifying a start position and a target descriptor. The number of bytes to |
|
35 be read may be specified explicitly, as here, or by the descriptor length. |
|
36 Another <codeph>Read()</codeph> variant, specifying the target as a <codeph>TAny*</codeph>, |
|
37 is provided.</p> <p>The following code fragment follows from the previous |
|
38 one:</p> <codeblock id="GUID-33E8D519-72DB-5BFA-8904-BC63B3F13820" xml:space="preserve"> // read from buffer into descriptor |
|
39 TBuf8<10> des; |
|
40 aBuf->Read(3,des,5); // puts "lo wo" into des.</codeblock> </section> |
|
41 <section id="GUID-DB7447A4-FA97-4727-B92D-E61556EA4AF5"><title>Write() example</title> <p><codeph>Write()</codeph> overwrites |
|
42 existing data in the buffer. Because the buffer is not expanded, <codeph>Write()</codeph> cannot |
|
43 leave. You must ensure that the region you select in the buffer already exists: |
|
44 if <codeph>Write()</codeph> attempts to write beyond the end of the data already |
|
45 in the buffer, a panic occurs.</p> <codeblock id="GUID-F5A86813-3C56-58B1-AAB0-E888E61BF736" xml:space="preserve"> // [over]write some stuff in buffer |
|
46 _LIT8(KFolks,"folks"); |
|
47 aBuf->Write(6,KFolks); |
|
48 writeBuf(aBuf); // gives “Hello folks!”</codeblock> </section> |
|
49 <section id="GUID-53F96FF4-38D1-4F4B-93DD-AA6B85FF8C99"><title>Delete() example</title> <p><codeph>Delete()</codeph> deletes |
|
50 data in the buffer. It can never fail.</p> <codeblock id="GUID-AA268BA8-CF54-5D93-A869-0EB291F5CE5A" xml:space="preserve"> // delete stuff |
|
51 aBuf->Delete(5,6); |
|
52 writeBuf(aBuf); // gives “Hello!”</codeblock> </section> |
|
53 <section id="GUID-D06541B3-1FA0-4511-91AA-8F8F33CBD273"><title>Compress() example</title> <p><codeph>Compress()</codeph> ensures |
|
54 that the buffer data occupies the minimum space. In the case of flat buffers, |
|
55 this re-allocates the cell to the size of the data in the buffer. In the case |
|
56 of segmented buffers, it may shuffle data so as to occupy the minimum number |
|
57 of segments.</p> <codeblock id="GUID-4F22F39C-756E-5665-AE58-816237D771C6" xml:space="preserve">// compress |
|
58 aBuf->Compress(); |
|
59 writeBuf(aBuf);</codeblock> </section> |
|
60 </conbody></concept> |