elementlist.h

来自「series60 应用程序开发的源代码 series60 应用程序开发的源代码」· C头文件 代码 · 共 177 行

#ifndef ELEMENTLIST_H
#define ELEMENTLIST_H

// INCLUDES

// System includes
#include <e32base.h>
#include <s32strm.h>
#include <s32std.h>

// User includes

// FORWARD DECLARATIONS
class CChemicalElement;

// CONSTANTS
const TInt KElementListGranularity = 4;
_LIT(KElementListDelimiter,",");

// CLASS DECLARATION

/**
*
* @class    elementlist.h
* @brief    Class to represent a list of chemical elements. The internal representation used to
*            store the list is not presented to the user via a public API, hence the implementation
*            can easily be modified to use any conceivable array or list type object...
*
* Copyright (c) EMCC Software Ltd 2003
* @version 1.0
*/
class CElementList : public CBase
{
public:
    /**
    * Getter for number of elements stored in the list
    * @return the number of elements stored in the list
    */
    virtual TInt NumberOfElements() const = 0;

    /**
    * Returns the element at the specified zero based index--const overload
    * @param aIndex The zero based index of the element required. Must be greater than zero, and less than
    * NumberOfElements()-1
    * @return A const reference to the element specified by aIndex
    * @panic KElementListPanicElementIndexOutOfRange if aIndex < 0 or aIndex > NumberOfElements()-1
    */
    virtual const CChemicalElement& At(TInt aIndex) const = 0;

    /**
    * Returns the element at the specified zero based index--non-const overload
    * @param aIndex The zero based index of the element required. Must be greater than or equal to zero,
    * and less than NumberOfElements()
    * @return A non-const (i.e. modifiable) reference to the element specified by aIndex
    * @panic KPanicElementIndexOutOfRange if aIndex < 0 or aIndex >= NumberOfElements()
    */
    virtual CChemicalElement& At(TInt aIndex) = 0;

    /**
    * Appends the given element onto the end of the list. Note that ownership of the element is passed to the
    * list, as denoted by the use of a CChemicalElement*.
    * @param aElement The element to be appended to the end of the list. Note its ownership is transferred, so
    * responsibility for aElement's destruction is no longer the responsibility of the caller.
    * @panic KElementListPanicNullElement If aElement==0
    */
    virtual void AppendL(const CChemicalElement* aElement) = 0;

    /**
    * Appends a new element onto the end of the list, specified descriptor containing comma-delimited data
    * of the form:
    * name, symbol, atomic_number, relative_atomic_mass, type, radioactive
    * where:
    * name: the name of the element;
    * symbol: the symbol of the element (maximum of KMaxSymbolLength characters);
    * atomic_number: the atomic number (integer);
    * relatvie_atomic_mass: the relative atomic mass (real);
    * type: either m (for metal), s (for semi-metal), n (for non-metal)
    * radioactive: either r (for radioactive) or n (for non-radioactive)
    * e.g. to constuct an element representing helium, specify:
    * _LIT(KHelium,"Helium,He,2,4,n,n");
    * myElementList->AppendL(KHelium);
    * @leave KErrGeneral If aElementCommaDelimitedString is of an invalid format.
    */
    virtual void AppendL(const TDesC& aElementCommaDelimitedString);

    /**
    * Appends a new element onto the end of the list, specified as separate descriptor representations of
    * each of the data members.
    * @
    */
    virtual void AppendL(const TDesC& aName, const TDesC& aSymbol, const TDesC& aAtomicNumber,
        const TDesC& aRelativeAtomicMass, const TDesC& aType, const TDesC& aRadioactive);

    /**
    * Deletes all of the elements owned by the list, and returns the memory allocated to them to the global heap.
    * Effectively resets the list to be empty.
    */
    virtual void DeleteAllElements() = 0;

    /**
    * Searches the list for an element with name aName, and returns its zero-based index if found.
    * @param aName The name to search for.
    * @return The zero-based index of the element within the list.
    * @leave KErrNotFound If an element with name aName is not found.
    */
    virtual TInt FindElementByNameL(const TDesC& aName) const = 0;

    /**
    * Searches the list for an element with symbol aSymbol, and returns its zero-based index if found.
    * @param aSymbol The symbol to search for.
    * @return The zero-based index of the element within the list.
    * @leave KErrNotFound If an element with symbol aSymbol is not found.
    */
    virtual TInt FindElementBySymbolL(const TDesC& aSymbol) const = 0;

    /**
    * Searches the list for an element with atomic number aAtomicNumber, and returns its zero-based index if found.
    * @param aName The atomic number to search for.
    * @return The zero-based index of the element within the list.
    * @leave KErrNotFound If an element with atomic number aAtomicNumber is not found.
    */
    virtual TInt FindElementByAtomicNumberL(TInt aAtomicNumber) const = 0;

    /**
    * Re-orders the list in ascending name order (i.e. alphabetical by name)
    */
    virtual void SortByNameL() = 0;

    /**
    * Re-orders the list in ascending symbol order (i.e. alphabetical by symbol)
    */
    virtual void SortBySymbolL() = 0;

    /**
    * Re-orders the list in ascending atomic number order (i.e. smallest atomic number first)
    */
    virtual void SortByAtomicNumberL() = 0;

    /**
    * Re-orders the list in ascending relative atomic mass order (i.e. lightest element first)
    */
    virtual void SortByRelativeAtomicMassL() = 0;

    /**
    * Function to externalise the element into a write stream
    * @param aStream the write stream to externalise to
    */
    void ExternalizeL(RWriteStream& aStream) const;

    /**
    * Function to internalise the element from a read stream
    * param aStream the write stream to internalise from
    */
    void InternalizeL(RReadStream& aStream);

    /**
    * Stores the element list in a given store, returning the stream ID
    * @param aStore the stream store in which to store the element list
    * @return The stream ID of the newly created store
    */
    TStreamId StoreL(CStreamStore& aStore) const;

    /**
    * Restores the element list from the given store and stream
    * @param aStore the store containing the stream
    * @param aStreamID the ID of the stream within the store that contains the element list
    */
    void RestoreL(CStreamStore& aStore, TStreamId aStreamId);


private:
    TInt ExtractUntilNextDelimiter(const TDesC& aString, TPtrC& aNextToken, TPtrC& aRemainingTokens) const;
};
#endif // #ifndef ELEMENTLIST_H

// End of File