// Desc1.cpp
//
// Copyright (c) 1999-2007 Symbian Software Ltd.  All rights reserved.
//
// $Change: 937687 $

// This exercise is designed to build familiarity with descriptors.
//
// The exercise consists of three parts. In the first part, the comparison
// is made between the C string and the EPOC descriptors. You are asked to 
// build and run the exercise, and observe the output of the console based
// application.
//
// In the second part of the exercise, you are introduced to a TPtr class.
// You are asked to perform basic string operation using methods available 
// to a TPtr class.
//
// In the third part of the exercises, string manipulation is preformed
// using TBuf and TBufC classes, highlighting the differences between the two.

// PROJECT HEADERS
#include "eustd.h"

// Common literal text
_LIT(KSpace,                "\n");
_LIT(KTxtHelloWorld,        "Hello World");
_LIT(KTxtPressToContinue,   " \nPress Any Key To Continue\n");
_LIT(KPartOne,              "PART ONE\n\n");
_LIT(KPartTwo,              "PART TWO\n");
_LIT(KPartThree,            "PART THREE\n\n");

// Common format strings
_LIT(KPtrLengthSize,        "Ptr()=%x; Length()=%d; Size()=%d\n");
_LIT(KMaxLength,            "MaxLength()=%d\n");
_LIT(KTPtr,                 "\nTPtr:");
_LIT(KTPtrC,                "\nTPtrC:");
_LIT(KTBufC,                "\nTBufC:");
_LIT(KTBuf,                 "\nTBuf:");

// Do the example
LOCAL_C void doExampleL()
    {  
    
    // Beginning of the exercise //

    //////////////////////////////
    //////////PART ONE ///////////
    //////////////////////////////

    console->Printf(KPartOne);

    //TODO
    // Lets start this exercise by comparing the C string with 
    // descriptors. Un-comment the block of code below that
    // compares the C string with the EPOC TBuf descriptor. 
    // NOTE : Size of the C string is 24 bytes to allow for 
    // the terminating NULL. EPOC descriptors don't care about
    // the terminating NULL character. More information on this
    // can be found in the SDK examples.
    // In this example, UNICODE or wide characters
    // are used, which implies that each character occupies 2 bytes.
    
    TText str1[12] =  {'H','e','l','l','o',' ','w', 'o', 'r', 'l', 'd','\0'}; // C style string 

    TPtrC ptrC(str1);   
    TBuf<12> epocString(str1);   
    _LIT(KCTempExample, "C string: %s \n" );  
    console->Printf(KCTempExample, str1);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, str1, ptrC.Length(), sizeof(str1));
    console->Printf(KTBuf);
    console->Printf(epocString);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, epocString.Ptr(), epocString.Length(), epocString.Size()); 
    console->Printf(KMaxLength, epocString.MaxLength());  

    console->Printf(KTxtPressToContinue);
    console->Getch();
    console->ClearScreen();

    //////////////////////////////
    //////////PART TWO ///////////
    //////////////////////////////

    console->Printf(KPartTwo);
    
    // Comments provided below will guide you through this part
    // of the exercise

    TText str[16] =  {'H','e','l','l','o',' ','w', 'o', 'r', 'l', 'd','!','\0'};

    // TPtr descriptor represents the text.
    // Descriptor length is 12 but max length is 13. Since the 
    // descriptor does not need the terminating NULL, in this example,
    // the last data position is spare. 
    // TPtrC descriptor points to the same string. 

    TPtr  tptrDesc(str, 12, 13); 
    TPtrC tptrcDesc(str);
      
    //TODO
    // The Statement below will print out the string using TPtr and TPtrC, 
    // and the information about the pointer value, length and max length.
    // Note that both of these descriptors point to the same data area 
    // (check Ptr() values).
    
    console->Printf(KTPtr);
    console->Printf(tptrDesc);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrDesc.Ptr(), tptrDesc.Length(), tptrDesc.Size()); 
    console->Printf(KMaxLength, tptrDesc.MaxLength());   

    console->Printf(KTPtrC);
    console->Printf(tptrcDesc);   
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrcDesc.Ptr(), tptrcDesc.Length(), tptrcDesc.Size()); 

    //TODO
    // Set the length of the tptrDesc to five and print out the new string
    // with the lenght,size and maxlength information. Check handouts
    // for this section to see what functions are available to you.
    // Print the same string using TPtrC. Compile and run the program. 
    // What do you observe?

    tptrDesc.SetLength(5); 
    console->Printf(KTPtr);
    console->Printf(tptrDesc);  
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrDesc.Ptr(), tptrDesc.Length(), tptrDesc.Size()); 
    console->Printf(KMaxLength, tptrDesc.MaxLength());

    console->Printf(KTPtrC);
    console->Printf(tptrcDesc);   
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrcDesc.Ptr(), tptrcDesc.Length(), tptrcDesc.Size()); 

    console->Printf(KTxtPressToContinue);
    console->Getch();
    console->ClearScreen(); 
    
    //TODO
    // Set the length of the tptrDesc to zero now. Use Zero() function to do that
    // rather than tptrDesc.SetLength(0). Both way would work, however this is
    // just to familiarise yourself with other functions available.. Print string, 
    // pointer, length, size and max length. Compile and run the program.

    tptrDesc.Zero();  
    console->Printf(KTPtr);
    console->Printf(tptrDesc);  
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrDesc.Ptr(), tptrDesc.Length(), tptrDesc.Size()); 
    console->Printf(KMaxLength, tptrDesc.MaxLength());       

    //TODO
    // Un-comment the code below. Compile and run the program.
    // This will cause program to Panic. Using the debugger
    // investigate the cause of this panic and fix the bug in the code 
    // below.
    
    
    tptrDesc.SetLength(13);   
    console->Printf(KTPtr);
    console->Printf(tptrDesc);   
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrDesc.Ptr(), tptrDesc.Length(), tptrDesc.Size()); 
    console->Printf(KMaxLength, tptrDesc.MaxLength());        
 
    console->Printf(KTxtPressToContinue);
    console->Getch();
    console->ClearScreen();  

    //////////////////////////////
    //////////PART THREE /////////
    //////////////////////////////

    console->Printf(KPartThree);

    //TODO
    // This part of the exercise is designed to build familiarity with
    // TBuf and TBufC descriptors. 
    // Have a look at the block of code provided below.
    // Make sure you understand everything before proceeding.
    // Compile and run the program. Observe the output of the application.

    _LIT(KTBufCExample, "I am a long string in TBufC");     
    TBufC<27> bufc(KTBufCExample);
    console->Printf(bufc);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, bufc.Ptr(), bufc.Length(), bufc.Size());
    // console->Printf(KMaxLength, bufc.MaxLength());


    // The code above didn't compile, investigate why ?
    // Fix the bug and recompile and run the program.


    //TODO
    // Un-comment the code below and try to compile and run it.
    // Do you think this will compile the first time and why ?
    
   
    _LIT(KTBufExample, "I am a long string in TBuf");     
    TBuf<26> buf(KTBufExample);
    console->Printf(KSpace);
    console->Printf(buf);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, buf.Ptr(), buf.Length(), buf.Size());
    console->Printf(KMaxLength, buf.MaxLength()); 


    //TODO
    // Create a TPtr to a bufc. Print the string, length and maxlength
    // using TPtr class.

    TPtr tptrToBufC = bufc.Des();
    console->Printf(KSpace);
    console->Printf(tptrToBufC);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrToBufC.Ptr(), tptrToBufC.Length(), tptrToBufC.Size());
    console->Printf(KMaxLength, tptrToBufC.MaxLength());
   
    console->Printf(KTxtPressToContinue);
    console->Getch();
    console->ClearScreen();


    //TODO
    // Delete string "long " from the buffer via TPtr.
    // Use Delete function.

    tptrToBufC.Delete((tptrToBufC.Length() - 21), 5);
     
    //TODO
    // Print the strings using TPtr and TBufC.
    // Observe what is happening with the TBufC.
    
    console->Printf(KTPtr);
    console->Printf(tptrToBufC);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrToBufC.Ptr(), tptrToBufC.Length(), tptrToBufC.Size());
    console->Printf(KMaxLength, tptrToBufC.MaxLength());
    
    console->Printf(KTBufC);
    console->Printf(bufc);
    console->Printf(KPtrLengthSize, bufc.Ptr(), bufc.Length(), bufc.Size());
    //TODO
    // Now lets try the same thing but using TBuf instead of TBufC
    // Un-comment the code below and try to compile it. Will it compile ?
    // Why or why not ? 

/*      
    TPtr tptrToBuf = buf.Des();
    console->Printf(tptrToBuf);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, tptrToBuf.Ptr(), tptrToBuf.Length(), tptrToBuf.Size());
    console->Printf(KMaxLength, tptrToBuf.MaxLength());
*/

    //TODO
    // Modify the TBuf size and print the new status as before

    buf.SetLength(2);
    console->Printf(KTBuf);
    console->Printf(buf);
    console->Printf(KSpace);
    console->Printf(KPtrLengthSize, buf.Ptr(), buf.Length(), buf.Size());
    console->Printf(KMaxLength, buf.MaxLength());   
    } // end doExampleL