diff -r 000000000000 -r bde4ae8d615e os/textandloc/textandlocutils/numbergrouping/inc/NumberGrouping.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/os/textandloc/textandlocutils/numbergrouping/inc/NumberGrouping.h Fri Jun 15 03:10:57 2012 +0200 @@ -0,0 +1,351 @@ +/* +* 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 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& 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) + * "" -> "" + * ( 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 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