TB10.1 Example Applications: examples/Base/BufsAndStrings/Desc/Pointer/Pointer.cpp Source File

00001 // Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
+00002 // All rights reserved.
+00003 // This component and the accompanying materials are made available
+00004 // under the terms of "Eclipse Public License v1.0"
+00005 // which accompanies this distribution, and is available
+00006 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
+00007 //
+00008 // Initial Contributors:
+00009 // Nokia Corporation - initial contribution.
+00010 //
+00011 // Contributors:
+00012 //
+00013 // Description:
+00014 // Examples to demonstrate the basic ideas of
+00015 // pointer descriptors. 
+00016 //
+00017 
+00018 #include "CommonFramework.h"
+00019 
+00020 //
+00021 // Common literal text
+00022 //
+00023 _LIT(KTxtHiTHere,"Hi there");
+00024 _LIT(KTxtHaveNiceDay,"Have a nice day!");
+00025 
+00026 //
+00027 // Common format strings
+00028 //
+00029 _LIT(KCommonFormat1,"\"%s\"\n");
+00030 _LIT(KCommonFormat3,"length=%d; size=%d;\n");
+00031 _LIT(KCommonFormat5,"Ptr()=%x; Length()=%d; Size()=%d\n");
+00032 _LIT(KCommonFormat16,"MaxLength()=%d\n");
+00033 _LIT(KCommonFormat17,"\"%S\"; ");
+00034 _LIT(KCommonFormat18,"Length()=%d; Size()=%d; ");
+00035 
+00036 // Do the example
+00037 LOCAL_C void doExampleL()
+00038     {
+00039                                 // Define a constant C style (ASCII) string
+00040         const TText8* cstr8 = (TText8*)"Hello World!";
+00041 
+00042                                 // Look at it.
+00043 
+00044         TBuf<12> temp;
+00045         temp.Copy(TPtrC8(cstr8));
+00046         console->Printf(temp);
+00047 
+00048                                 // A TPtrC8 descriptor represents the
+00049                         // ASCII text; contrast this with the
+00050                         // basic C string  
+00051         TPtrC8 ptrC8(cstr8);
+00052 
+00053                                 // Look at:
+00054                                 //   1. Address of C string
+00055                                 //   2. Length of the C string
+00056                                 //   3. Size of the string.
+00057                                 // Size is 13 bytes to allow for 
+00058                                 // the terminating NULL.
+00059                     // 
+00060         _LIT(KFormat2,"\nNarrow C string at %x; ");
+00061         console->Printf(KFormat2,cstr8);
+00062         console->Printf(KCommonFormat3,12,sizeof("Hello World!"));
+00063 
+00064                                 // Look at:
+00065                                 //   1. Address of descriptor
+00066                                 //   2. Address of descriptor data area
+00067                                 //   3. Length  of descriptor
+00068                                 //   4. Size of descriptor
+00069                                 // Address of descriptor data area is the 
+00070                                 // same as the address of the C string. 
+00071                                 // The Size of the descriptor data is only
+00072                                 // 12 bytes (1 byte for each character).
+00073         _LIT(KFormat4,"8-bit pointer-descriptor at %x; ");
+00074         console->Printf(KFormat4,&ptrC8);
+00075         console->Printf(KCommonFormat5,ptrC8.Ptr(),ptrC8.Length(),ptrC8.Size());                
+00076                                                                 
+00077                 
+00078                                 // Define a constant C style (Wide) string
+00079         const TText16*  cstr16 = (TText16*)L"Hello World!";
+00080 
+00081                                 // A TPtrC16 descriptor represents the
+00082                         // wide (i.e. double-byte character) text;
+00083                         // contrast this with the basic C string.  
+00084         TPtrC16 ptrC16(cstr16);
+00085         
+00086         _LIT(KFormat7,"\nWide C string at %x; ");
+00087         console->Printf(KFormat7,cstr16);
+00088         console->Printf(KCommonFormat3,12,sizeof(L"Hello World!"));
+00089         
+00090                                 // Look at:
+00091                                 //   1. Address of descriptor
+00092                                 //   2. Address of descriptor data area
+00093                                 //   3. Length  of descriptor
+00094                                 //   4. Size of descriptor
+00095                                 // Address of descriptor data area is the
+00096                                 // same as the address of the C string.
+00097                                 // The size of descriptor data is only
+00098                                 // 24 bytes (2 bytes for each character).
+00099         _LIT(KFormat6,"16-bit pointer-descriptor at %x; ");
+00100         console->Printf(KFormat6,&ptrC16);
+00101         console->Printf(KCommonFormat5,ptrC16.Ptr(),ptrC16.Length(),ptrC16.Size());             
+00102         
+00103                 
+00104                                 // Use the _S macro to define a constant 
+00105                                 // C style string of the appropriate width.
+00106                                 // The TText variant is defined at build
+00107                                 // time as  TText16 
+00108                                 // (In earlier times this could also have been TText8,
+00109                                 //  but in all current versions, TText16 is the standard).
+00110         const TText* cstr = _S("Hello World!"); 
+00111 
+00112                                 // TPtrC descriptor represents the text;
+00113                                 // the TPtrC variant is defined at build 
+00114                                 // time as TPtrC16.
+00115         TPtrC ptrc(cstr);
+00116         
+00117         _LIT(KFormat8,"\nBuild-dependent TText at %x; ");
+00118         console->Printf(KFormat8,cstr);
+00119         console->Printf(KCommonFormat3,12,sizeof( 
+00120                                                                   #ifdef _UNICODE
+00121                                                                   L"Hello world!"
+00122                                                                   #else
+00123                                                                   "Hello world!"
+00124                                                                   #endif
+00125                                                   )
+00126                                    );
+00127         
+00128                                 // Look at descriptor basics.
+00129         _LIT(KTxtBuildDependentptdesc,"Build-dependent pointer-descriptor");
+00130         console->Printf(KTxtBuildDependentptdesc);
+00131         
+00132         _LIT(KFormat9," at %x; ");
+00133         console->Printf(KFormat9,&ptrc);
+00134         _LIT(KFormat10,"Ptr()=%x;\n");
+00135         console->Printf(KFormat10,ptrc.Ptr());
+00136         _LIT(KFormat11," Length()=%d; Size()=%d\n");
+00137         console->Printf(KFormat11,ptrc.Length(),ptrc.Size());
+00138 
+00139                                 // The _LIT macro is most useful. It constructs
+00140                     // a family of constant descriptor classes TLitC<Tint>. 
+00141                     // The constant generated by the _LIT macro:
+00142                     //   1. can be passed as 'const TDesC&' type
+00143                     //   2. has an address-of operator 'operator&()' which returns a 'const TDesC*' type
+00144                     //   3. can be passed as a TRefByValue<const TDesC>
+00145                                 //
+00146                                 // The _L macro constructs a TPtrC but should be avoided 
+00147                     // where possible on the grounds of efficiency.
+00148                     // Use the _LIT macro instead.
+00149                                 
+00150         console->Printf(_L("\nThe _L macro constructs a TPtrC"));
+00151         // * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+00152         // * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+00153         
+00154         _LIT(KTxtTPtrBasicConcepts,"\n-->TPtr basic concepts");
+00155         console->Printf(KTxtTPtrBasicConcepts);
+00156         _LIT(KTxtPressToContinue," (press any key to continue)\n");
+00157         console->Printf(KTxtPressToContinue);
+00158         console->Getch();
+00159                                         
+00160                                 // Set up an area and initialise to a 
+00161                                 // C style string (including the NULL).
+00162                                 // The need for the NULL forces cstr to
+00163                                 // have a length of 16.
+00164         TText str[16] =  {'H', 'a', 'v', 'e', ' ', 'a',
+00165                                           ' ', 'n', 'i', 'c', 'e',
+00166                                           ' ', 'd', 'a', 'y', '\0'};
+00167 
+00168                                 // Look at it.
+00169         console->Printf(KCommonFormat1,&str[0]);
+00170 
+00171                                 // TPtr descriptor represents the text.
+00172                                 // Descriptor length is 15 but max length
+00173                                 // is 16. The descriptor does not need the
+00174                                 // terminating NULL, so in this example,
+00175                                 // the last data position is spare. 
+00176         TPtr  ptr(&str[0],15,16);
+00177 
+00178                                 // Look at:
+00179                                 //   1. Address of the C string
+00180                                 //   2. Length of the C string
+00181                                 //   3. Size of the string
+00182                                 // Size is 16 bytes to allow for
+00183                                 // the terminating NULL.
+00184         _LIT(KFormat12,"C string at %x; ");
+00185         console->Printf(KFormat12,str);
+00186         _LIT(KFormat13,"length=%d; size=%d\n");
+00187         console->Printf(KFormat13,15,sizeof(str));
+00188 
+00189                         // Look at:
+00190                                 //   1. Address of descriptor
+00191                                 //   2. Address of descriptor area
+00192                                 //   3. Length of descriptor
+00193                                 //   4. Size of descriptor
+00194                                 //   5. Max length of descriptor 
+00195                                 // Address of descriptor data area is the 
+00196                                 // same as the address of cstr[]. The
+00197                                 // descriptor length is 15 but the maximum
+00198                                 // length is 16.
+00199         _LIT(KFormat14,"Descriptor at %x; ");
+00200         console->Printf(KFormat14,&ptr);
+00201         _LIT(KFormat15,"Ptr()=%x; Length()=%d; Size()=%d; ");
+00202         console->Printf(KFormat15,ptr.Ptr(),ptr.Length(),ptr.Size());
+00203         console->Printf(KCommonFormat16,ptr.MaxLength());
+00204 
+00205                                 // The data can be replaced using the 
+00206                                 // assignment operator. Note the reference to
+00207                     // the TLitC<> KTxtHiTHere constructed using the _LIT macro.
+00208         ptr = KTxtHiTHere;                       
+00209 
+00210                                 // Length of descriptor is now 8 but maximum
+00211                                 // length remains at 16.
+00212                                 // Size is 16 
+00213                                 // Text in ptr's data area (i.e. in the area 
+00214                                 // defined by str[]) is 
+00215                                 // now "Hi there")
+00216         console->Printf(KCommonFormat17,&ptr);
+00217         console->Printf(KCommonFormat18,ptr.Length(),ptr.Size());
+00218         console->Printf(KCommonFormat16,ptr.MaxLength());
+00219                                         
+00220                                 // Length can be changed; data represented 
+00221                                 // by the descriptor is now "Hi"
+00222         ptr.SetLength(2);
+00223                     
+00224         console->Printf(KCommonFormat17,&ptr);
+00225         console->Printf(KCommonFormat18,ptr.Length(),ptr.Size());
+00226         console->Printf(KCommonFormat16,ptr.MaxLength());
+00227 
+00228                                 // Length can be set to zero; NO data 
+00229                                 // is now represented by the
+00230                                 // descriptor but maximum length is still 16
+00231         ptr.Zero();
+00232         console->Printf(KCommonFormat17,&ptr);
+00233         console->Printf(KCommonFormat18,ptr.Length(),ptr.Size());
+00234         console->Printf(KCommonFormat16,ptr.MaxLength());
+00235 
+00236                                 // Replace text with text of length 16, 
+00237                                 // the maximum. 
+00238         ptr = KTxtHaveNiceDay;
+00239         console->Printf(KCommonFormat17,&ptr);
+00240         console->Printf(KCommonFormat18,ptr.Length(),ptr.Size());
+00241         console->Printf(KCommonFormat16,ptr.MaxLength());
+00242 
+00243                                 // adding another character causes panic !!
+00244                                 // length would be > maximum.
+00245                                 // 
+00246                                 // Remove the "//" marks on the next line
+00247                                 // to see this happen
+00248         //ptr.Append('@');
+00249     }
+00250 
+00251 
+00252     
+00253 
+00254 
+00255 
+00256 
+00257         
+00258         
+