/*

* Copyright (c) 2005-2007 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:  Digit string handler class

*

*/

#ifndef VPBKENGUTILS_RDIGITSTRING_H

#define VPBKENGUTILS_RDIGITSTRING_H

// INCLUDES

#include <e32std.h>

namespace VPbkEngUtils {

// FORWARD DECLARATIONS

class TFixedDigitString;

// CLASS DECLARATIONS

/**

 * Variable-length digit string.

 * Phone number matching helper class: encodes decimal digit characters to BCD 

 * (Binary Coded Decimal) format for efficient matching.

 */

class RDigitString

    {

    public:

        /**

         * Default constructor. Resets this digit string to empty.

         */

        RDigitString();

        /**

         * Releases resources used for storing the digit string. This object

         * must not be used after Close() has been called to it.

         */

        void Close();

        /**

         * Returns the length of this digit string.

         *

         * @return the number of digits in this digit string,

         */

        TInt Length() const;

        /**

         * Returns true if this digit string is empty.

         */

        TBool IsEmpty() const;

        /**

         * Returns the maximum number of digits this object may contain.

         */

        static TInt MaxLength();

        /**

         * Returns non-modifiable decimal digit at position aIndex.

         *

         * @pre  aIndex >= 0 && aIndex < Length()

         * @post result >= 0 && result <= 9

         */

        TInt operator[](TInt aIndex) const;

        /**

         * Compares the digits in this string to another digit string.

         *

         * @param aOther    the other digit string to compare this string with.

         * @param aNumDigits    the number of digits to compare. Zero means

         *                      all digits are compared. 

         * @return  true if aNumDigits digits match, false otherwise. Undefined

         *          if aNumDigits < 0 || aNumDigits > MaxLength().

         */

        TBool Compare(const RDigitString& aOther, TInt aNumDigits) const;

        /**

         * Resets this digit string to empty.

         *

         * @post Length() == 0

         */

        void Reset();

        /**

         * Encodes digit characters from text to this digit string.

         *

         * @param aDigitsText   text to encode decimal digit characters from.

         *                      Nondigit characters are skipped.

         * @exception KErrOverflow  If aDigitsText contains too many digits to

         *                          fit into this data structure. If this

         *                          function leaves this object's state is 

         *                          unchanged.

         * @exception KErrNoMemory  If encoding runs out of memory. If this 

         *                          function leaves this object's state is 

         *                          unchanged.

         */

        void EncodeDigitsL(const TDesC& aDigitsText);

    private:  // Data

        /// Number of active elements in iDigits

        TInt16 iSubCount;

        /// Maxmimum size of the array iDigits points to

        TInt16 iSubCapacity;

        /// Own. Encoded digits

        TFixedDigitString* iDigits;

    };

} // namespace VPbkEngUtils

#endif  // VPBKENGUTILS_RDIGITSTRING_H