// Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
// which accompanies this distribution, and is available
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// A string class implementation which allows quick addition of partial strings
// (no copying) by using an internal array of fragmented strings.
// The class allows comprehensive character based matching functionality 
// along with infinite depth marking.
// 
//

#ifndef __CFRAGMENTEDSTRING_H__
#define __CFRAGMENTEDSTRING_H__

// includes
#include <e32base.h>
#include <cstack.h>


//
// CFragmentedString

//##ModelId=3B666BC6034A



class CFragmentedString : protected CArrayPtrFlat<HBufC>
/**  
Utility that allows a single string to be built from an array of consecutive sub-strings.

The sub-strings can be inserted by reference or copied.

The object maintains information that points to a current position within the string. A typical 
use is to test the contents of the string using one of the Match...() functions, and then use 
ConsumeMatched() to advance past the matched area.

The class also supports inserting an unlimited number of marks in the string, and performing 
operations relative to the head (i.e. last inserted) mark. 
    @publishedAll
    @released
*/
	{
protected:
	class TStringMark
	/** A mark at a string position. */
		{
	public:
		/** Constructor.

		@param aIndex Array index of the marked sub-string
		@param aCharacter Character position within the sub-string for the mark
		*/
		TStringMark(TInt aIndex, TInt aCharacter)
		: iMarkIndex(aIndex), iMarkCharacter(aCharacter)
		{
		}

	public:
		/** Array index of the marked sub-string. */
		TInt iMarkIndex;
		/** Character position within the sub-string for the mark. */
		TInt iMarkCharacter;
		};
	/** A stack of string position marks. */
	typedef CStack<TStringMark, ETrue> CMarkStack;

public:
	/** Defines possible results of a string matching operation for this class. */
	enum TStringMatch 
		{ 
		/** There was no match. */
		ENoMatch, 
		/** There was a complete match. */
		EMatch,
		/** String contained insufficient data to perform the match operation.

		This can mean that the start of the target string was matched, but the string 
		being searched ended before a complete match was found. */
		EInsufficientData
		};

public:
	IMPORT_C CFragmentedString();
	//##ModelId=3B666BC700AD
	IMPORT_C ~CFragmentedString();

	//##ModelId=3B666BC70099
	IMPORT_C void AddStringL(HBufC* aString); // this version is more efficient
	//##ModelId=3B666BC700A3
	IMPORT_C void AddStringL(const TDesC& aString);
	
	//##ModelId=3B666BC70090
	IMPORT_C TInt Length() const;
	//##ModelId=3B666BC70071
	IMPORT_C HBufC* StringL() const;
	//##ModelId=3B666BC70068
	IMPORT_C HBufC* ContentL() const;
	//##ModelId=3B666BC70067
	IMPORT_C void Reset();

	//##ModelId=3B666BC7005D
	IMPORT_C TStringMatch Match(const TDesC& aString);
	//##ModelId=3B666BC70049
	IMPORT_C TStringMatch MatchRange(const TUint aLower, const TUint aUpper);
	//##ModelId=3B666BC7003F
	IMPORT_C TStringMatch MatchSelect(const TDesC& aSelection);
	//##ModelId=3B666BC70037
	IMPORT_C TStringMatch MatchNotSelect(const TDesC& aSelection);
	//##ModelId=3B666BC70036
	IMPORT_C void ConsumeMatched();

	//##ModelId=3B666BC70035
	IMPORT_C HBufC* MarkedL();
	//##ModelId=3B666BC7002B
	IMPORT_C HBufC* MarkedWithInitialTextL(const TDesC& aInitialText);
	//##ModelId=3B666BC70022
	IMPORT_C void Mark(); // Mark can leave
	//##ModelId=3B666BC70021
	IMPORT_C void DeleteMark();
	//##ModelId=3B666BC70018
	IMPORT_C void ResetToMark();

	//##ModelId=3B666BC7000E
	IMPORT_C void ReplaceMarkedL(HBufC* aString);
	//##ModelId=3B666BC70005
	IMPORT_C void ReplaceMarkedAndSkipL(HBufC* aString);
	//##ModelId=3B666BC70003
	IMPORT_C void InsertStringL(HBufC* aString);

protected:
	//##ModelId=3B666BC603E1
	IMPORT_C void DeleteToMark(const TStringMark& aStringMark);
	//##ModelId=3B666BC603C4
	IMPORT_C void InsertStringToL(HBufC* aString, TInt aStringIndex, TInt aLengthIntoString);
	//##ModelId=3B666BC70072
	HBufC* StringL(TInt aStartIndex, TInt aStartCharacter, TInt aEndIndex, TInt aEndCharacter, const TDesC* aInitialText=NULL) const;
	//##ModelId=3B666BC603C3
	void StartMatch();
	//##ModelId=3B666BC603B8
	CFragmentedString::TStringMatch DoMatchSelect(const TDesC& aSelection, TBool aInSelection);
	//##ModelId=3B666BC603AE
	TBool FindNextMatchChar(TUint& aChar);

protected:
	//##ModelId=3B666BC603A4
	/** Result of the last match operation. */
	TStringMatch iMatched;

	/** Array index of the sub-string found in the last match operation. */
	//##ModelId=3B666BC6039A
	TInt iMatchedToIndex;
	/** Current character position within the iMatchedToIndex sub-string found in the last match operation. */
	//##ModelId=3B666BC60390
	TInt iMatchedToCharacter;
	/** Array index of the current sub-string. */
	//##ModelId=3B666BC60386
	TInt iCurrentIndex;
	/** Current character position within the current sub-string. */
	//##ModelId=3B666BC6037C
	TInt iCurrentCharacter;
	/** Stack of marks in the string.

	Mark() pushes a mark on the stack; DeleteMark() pops one off.
	*/
	//##ModelId=3B666BC60372
	CMarkStack iMarkStack;
	};

#endif // __CFRAGMENTEDSTRING_H__