/*
* 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