/*

* Copyright (c) 2002-2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Provides formatting (grouping) for plain phone numbers

*

*

*/

#ifndef C_NUMBER_GROUPING_H

#define C_NUMBER_GROUPING_H

// #define __TEST_AS_EXE__ // put this in if you want all the test code to run and swap the mmps...

#include "NumberGroupingStd.h"

class TResourceReader;

class CRegularExpression;

class CPNGNumberGroupingExtension;

/**

* Engine class to format plain phone numbers by inserting grouping separators.

*  Both unformatted and formatted buffers are maintained by this class.

*  A reversed formatted buffer is also available to assist the client in performing wrapping.

*

* @lib NumberGrouping.lib

*/

NONSHARABLE_CLASS(CPNGNumberGrouping) : public CBase

{

/** 

* Central Repository key values for KNumberGrouping key in NumberGroupingCRKeys.h

*/

public:

    enum TNumberGroupingCRValues

        {

        /** Number grouping disabled */

        ENumberGroupingDisabled = 0,

        /** Number grouping enabled (USA) */

        ENumberGroupingEnabled = 1

        };

public:

	IMPORT_C static CPNGNumberGrouping*	NewL(TInt aMaxLength = 0, TBool aReversed = EFalse);

	IMPORT_C static CPNGNumberGrouping*	NewLC(TInt aMaxLength = 0, TBool aReversed = EFalse);

	IMPORT_C ~CPNGNumberGrouping();

	IMPORT_C TInt	Insert(TInt aIndex, TText aChar);

	IMPORT_C TInt	Delete(TInt aIndex);

	IMPORT_C TInt	Append(TText aChar);

    /**

    * Sets the new unformatted phone number.

    *

    * Formatting does not actually occur until an API is called that accesses in some way the formatted buffer

    * or one of its characteristics

    *

    * @param    aNumber Ungrouped phone number to be copied into the NumberGrouping engine's unformatted buffer

    * @return   KErrOverflow if the number is too long for the length of the unformatted buffer

    */

    IMPORT_C TInt	Set(const TDesC& aNumber);

    /**

    * @return   Length of the currently formatted (grouped) buffer

    */

    IMPORT_C TInt   Length() const;

    /**

    * @return   Length of the currently unformatted buffer

    */

    IMPORT_C TInt   UnFormattedLength() const;

	/**

    * This returns the maximum size of the unformatted buffer. This is the value that was provided during

    * construction.

    *

    * Descriptors provided to Set() must be shorter than this length.

    *

    * @return   maximum length of the unformatted buffer.

    */

    IMPORT_C TInt			MaxDisplayLength() const;

    /**

    * Routine to determine if the character at a given position in the formatted phone number

    * is a space character derived from the number grouping. That is, not part of the supplied phone number

    * proper, but a space character from the number grouping.

    *

    * A client can check the descriptor returned by FormattedNumber() directly to perform a simple test

    * of whether the character is a Space or not (whether or not derived from number grouping formatting)

    *

    * Note also that this returns EFalse if the character is some other formatting character besides

    * space.  To determine that, use IsCharacterInsertedByNumberGrouping().

    *

    * @param    aPos    The index of the character of interest

    * @return   EFalse  iff the characer at aPos in the formatted buffer is a space coming from grouping

    */

	IMPORT_C TBool			IsSpace(TInt aPos) const;

	/**

    * Access to section of the formatted buffer.

    * This routine returns a descriptor for the indicated range in the formatted (grouped) internal

    * buffer.  If there are spaces at either end of the indicated section of the formatted buffer, then

    * the returned descriptor is adjusted to point to the trimmed buffer in order to avoid the spaces.

    *

    * @param    aFrom   Inclusive starting index

    * @param    aTo     Inclusive end index

    * @return   reference to const non-modifiable descriptor for the indicated, trimmed text

    */

    IMPORT_C const TDesC&	FormattedNumber(TInt aFrom, TInt aTo) const;

    IMPORT_C const TDesC&	FormattedNumber() const;

    /**

    * Access to part of the reverse formatted number. If there are spaces at either end of the indicated

    * section of the formatted buffer, then the returned descriptor is adjusted to point to the trimmed

    * buffer in order to avoid the spaces.

    *

    * Returns KNullDesC if the feature has not been enabled by passing ETrue to the

    * parameter aReversed during construction

    *

    * @param    aFrom   lower (inclusive) limit of the text to look at

    * @param    aTo     upper (inclusive) limit of the text to look at

    * @return   Reference to descriptor containing the selected text

    */

	IMPORT_C const TDesC&	ReverseFormattedNumber(TInt aFrom, TInt aTo) const;

    /**

    * Access to the reverse formatted number

    *

    * Returns KNullDesC if the feature has not been enabled by passing ETrue to the

    * parameter aReversed during construction

    *

    * @return   Reference to descriptor containing the reverse formatted text

    */

	IMPORT_C const TDesC&	ReverseFormattedNumber() const;

	IMPORT_C const TDesC&	Selection(TInt aFrom, TInt aTo) const;

	IMPORT_C const TDesC&	UnFormattedNumber(TInt aFrom, TInt aTo) const;

	IMPORT_C const TDesC&	UnFormattedNumber() const;

    /**

    * This method allows the client to determine if the indexed character is a number grouping supplied

    * character. Specifically, this means that this character originates in the number grouping formatting

    * and not from the supplied unformatted phone number.

    *

    * Where the number has not been grouped (e.g. because there is an invalid phone number character in the

    * supplied descriptor), this method returns EFalse, even if the character pointed to may be of the nature

    * of a number grouping character. Use IsChangedByGrouping() to see if the number has been changed by

    * grouping at all.

    *

    * Where a client is interested purely in the nature of the characters rather than whether they come from

    * grouping or not, he may examine the examine the text via the descriptor reference returned by

    * FormattedNumber().

    *

    * @since    Series 60 2.6

    * @param    aPos    The index provided is for the formatted number.

    * @return   EFalse  iff the character at the supplied index is part of the supplied phone number

    */

    IMPORT_C TBool IsCharacterInsertedByNumberGrouping(TInt aPos) const;

    /**

    * Method to determine if the current number has been changed by number grouping.

    * If this returns EFalse, then FormattedNumber() and UnFormattedNumber() refer to descriptors of with identical

    * content.

    * If this method returns ETrue, then the descriptors that would be returned by the two accessor APIs refer

    * to descriptors with different content.

    *

    * @since    Series 60 2.6

    * @return   ETrue iff formatting of the number has made an effective difference.

    */

    IMPORT_C TBool IsChangedByGrouping() const;

    /**

    * @return   return iLanguage.

    */

    inline TLanguage  Language() const;

public:

	TLanguage	iForceLanguage;

private: // private classes and enums

    class TPNGSeparator

        {

        public:

        TPNGSeparator();

        TPNGSeparator( TInt aPos, TText aSeparatorCharacter );

        public:

        TInt iPosition;

        TText iSeparatorCharacter;

        };

	class TPNGGroupingInfo

    	{

        public:

		TPNGGroupingInfo();

	    public:

		TInt			        iMinNumberOfDigits;

		TInt			        iMaxNumberOfDigits;

        RArray<TPNGSeparator>   iAfterPositions; // Positions of separators "after" the beginning

		TPNGSeparator			iBeforePosition; // Positions of separators "before" the end

	    };

    // Constant for no pattern in use:

    enum

        {

        ENoMatchedPattern = -1

        };

private: // Constructors

    CPNGNumberGrouping( TInt aMaxLength, TBool aReserved);

	void ConstructL();

private:

	TLanguage doReadLanguageFromSharedData() const;

	void	doReadFormatInfoFromResourceFileL();

	void	doClearGroupingItemsList();

	void	doClearFormattedNumbers();

	void	doNumberGroupingL() const;

	void	doNumberSquashing() const;

    /**

    * Read and process a single NUMBER_GROUPING_ITEM resource structure

    */

    void ReadGroupingSchemeL(

        TResourceReader& aResourceReader,

        RPointerArray<TDesC>& aGroupingPatternsList,

        TInt& aMaxExtraCharacters );

    /**

    * Read and skip a single NUMBER_GROUPING_ITEM resource structure

    */

    void SkipGroupingSchemeL( TResourceReader& aResourceReader ) const;

    /**

    * Process the format pattern for "after positions"

    */

    void ParseForAfterPositions(

        const TDesC& aFormatPattern,

        TPNGGroupingInfo* aGroupingInfo,

        const TDesC& aWildcardedMatchingPattern,

        TInt& aMaxExtraCharacters,

        TBool& trailingPossible ) const;

    /**

    * Process the format pattern for a before positions

    */

    void ParseForBeforePosition(

        const TDesC& aFormatPattern,

        CPNGNumberGrouping::TPNGGroupingInfo* aGroupingInfo,

        TInt& aMaxExtraCharacters

        ) const;

   /**

    * This routine is used to find a wildcarded version of the matching pattern

    * provided in the "initialDigits" element for a grouping scheme read from resource.

    * It uses the services of the CRegularExpression class, an instance of which is constructed

    * with the provided aMatchString pattern only.

    *

    * The client must supply a modifiable descriptor long enough to hold the wildcarded version

    * of the pattern.

    *

    * For each character index, if there is only one possible valid character, this puts in that

    * character.  If there are more than one, then the supplied aWildcardChar is inserted. The

    * initialDigits element uses a full stop as a numeric wildcard; this is replaced with the nominated

    * wildcard.

    *

    * Rules: (where 'n, has been passed is used as the wildcard)

    *   "<a numeric digit>" -> "<a numeric digit>"

    *   ( e.g. "1"         ->  "1" )

    *   "+"         ->  "+"

    *   "."         ->  "n"

    *   "[0-3]"     ->  "n"

    *

    * @param    aMatchString        Regular expression to provide example of

    * @param    aWildcardChar       The character to put in the example pattern if there is no single

    *                               valid character at that point

    * @param    aWildcardMatchString     Descriptor to write the wildcarded match pattern into

    */

	void    GetWildcardVersionOfMatchStringL(

        const TDesC& aMatchString,

        TText aWildcard,

        TDes& aWildcardMatchString ) const;

    /**

    * This method expresses the policy of what characters may form part of a phone number

    * Note that this method is valid even it there is no formatting going on.  It is an intrinsic

    * test on the character itself

    */

    TBool   IsValidPhoneNumberCharacter(TText aCharacter) const;

    /**

    * Examines the unformatted number, counting how many digits are found before non-digit

    * characters or the end is encountered.

    * Returns 0 if Set() has not been called.

    */

    TInt LengthToGroup() const;

    /**

    * Perform number grouping using pattern at given index.  Grouping is only applied to the leading

    * aLengthToGroup characters.

    */

    void doNumberGroupingForPatternL( TInt aMatchedPattern, TInt aLengthToGroup ) const;

private: // private data

	HBufC*							iUnformattedNumber;

	mutable TPtrC					iUnformattedNumberPtr;

	mutable HBufC*					iFormattedNumber;

	mutable TPtrC					iFormattedNumberPtr;

	mutable HBufC*					iReverseFormattedNumber;

	mutable TPtrC					iReverseFormattedNumberPtr;

	mutable TPtrC					iSelectionPtr;

	mutable TLanguage				iLanguage;				// the system language

	TInt							iMaxUnformattedLength;

	TBool							iReversed;

	CRegularExpression*				iRegExp;				// the patterns for matching

	RPointerArray<TPNGGroupingInfo>	iGroupingItemsList;		// the formatting info

    mutable TInt                    iMatchedPatternIndex;   // keep track of what pattern is matched

    CPNGNumberGroupingExtension*    iExtension;

};

inline TLanguage CPNGNumberGrouping::Language() const

    {

    return iLanguage;

    }

#endif // C_NUMBER_GROUPING_H

// End of File