rsmbmusicaplibvector.h

索爱手机代码

/* Copyright (C) 2006 Sony Ericsson Mobile Communications Japan, Inc. */
/*--------------------------------------------------------------------*/
// FileName:
//	RSmbMusicAPLibVector.h
//
// Description:
//	PTX810 Music傾僾儕 儈儏乕僕僢僋嫟捠儔僀僽儔儕
/*--------------------------------------------------------------------*/
//曄峏棜楌
//擔晅			|曄峏幰			|撪梕
//--------------+---------------+--------------------------------------
//2006/09/23	|SEMC崃绮		|僼傽僀儖僔僗僥儉嫟捠儔僀僽儔儕偐傜愗傝弌偟

/** @file RSmbMusicAPLibVector.h
 *  STL 偺 @<vector@> 憡摉丅
 *
 *  $Revision: 1.2 $ $Date: 2006/04/05 17:21:27 $
 */

#ifndef __RSMBMUSICAPLIB_VECTOR_H__
#define __RSMBMUSICAPLIB_VECTOR_H__

#include    "SmbMusicAPLibConfig.h"
#include    "TSmbMusicAPLibIterator.h"      // for iterator, reverse_iterator

class CBufFlat;

SEMCJ_NAMESPACE_BEGIN
MUSICAPLIB_NAMESPACE_BEGIN

struct TSmbMusicAPLib_NotDelete;

/**
 *  摦揑攝楍僐儞僥僫丅
 *
 *  梫慺悢傪幚峴帪偵寛掕丒曄峏偱偒傞丄摦揑攝楍僐儞僥僫丅
 *  std::vector<T> 傪愝寁儌僨儖偲偟丄儔儞僟儉傾僋僙僗斀暅巕傪僒億乕僩偡傞丅
 *
 *  SymbianOS 偵傕 Dynamic Arrays 偲憤徧偝傟傞僐儞僥僫孮偼偁傞偑丄
 *      - 斀暅巕傪採嫙偟側偄
 *      - 抣偺僙儅儞僥傿僋僗偑摿桳 - 梫慺偺 ctor/dtor 偼摦偐偝偢價僢僩揑偵抣僐僺乕偡傞
 *      - 僐儞僥僫帺懱偺僐僺乕偼晄壜 - RArray<T> 傕僴儞僪儖偩偗偺 shallow copy
 *
 *  偲偄偭偨揰偱 C++昗弨僗僞僀儖偵姷傟偨僾儘僌儔儅傪屗榝傢偣傞偺偱丄std::vector<T> 偲
 *  摨堦僙儅儞僥傿僋僗偺僒僽僙僢僩傪愝偗傞偙偲偵偡傞丅
 *
 *  final 偱偁傝丄攈惗棙梡傪梊掕偟側偄丅
 *
 *  @param[in]  T               僐儞僥僫梫慺偺宆丅梫媮帠崁偼 std::vector<T> 偵摨偠丅
 *  @param[in]  DeletePolicy    梫慺偺嶍彍億儕僔乕丅僐儞僥僫偐傜梫慺偑嶍彍偝傟傞偲偒 DeletePolicy::Destroy(T*&) 偑屇傃弌偝傟傞丅
 *
 *  @note   幚憰偵偼 class CBufFlat 傪梡偄偰偄傞丅棟桼偼埲壓丅
 *          - 慡梫慺偑楢懕儊儌儕堟偵奿擺偝傟偰偄傞偙偲傪 std::vector<T> 摨條偵曐徹偡傞丅
 *          - Dynamic Arrays 偺 RAray<T>, CArrayFixFlat<T> 摍偼丄暔棟妱傝摉偰梕検傪塀偟偰偍傝丄reserve(size_type), capcity() 偑幚尰偱偒側偄丅
 *
 *  @attention  僥儞僾儗乕僩僷儔儊乕僞 @a DeletePolicy 偼丄std::vector<T> 旕屳姺偺僆儕僕僫儖偱偁傞丅
 *              SymbianOS 偱偼丄僗儅乕僩億僀儞僞偺幚尰偼晄壜擻側偺偱丄C* 僋儔僗僆僽僕僃僋僩傪強桳尃埾戸偱奿擺偡傞庤抜偑昁梫丄偲峫偊偨丅
 *
 *  @attention  @a DeletePolicy 偼丄僗儅乕僩億僀儞僞傎偳姰慡側摟夁懳嶔偱偼側偄丅
 *              杮僐儞僥僫偑曉偟偨嶲徠愭偺 @a T 梫慺傪丄棙梡幰偑捈愙偳偆憖嶌偟偨偐偼丄専抦偱偒傞偼偢偼側偄偐傜偩丅
 *              @code
 *  typedef RSmbMusicAPLibVector<CFoo*, TSmbMusicAPLib_Delete> T;
 *  T vec;
 *  CleanupReleasePushL( vec );
 *      ...
 *  vec.Pop_back();     // OKay. vec 偑 delete 傕偟偰偔傟傞丅
 *      ...
 *  vec.Clear();        // 摨偠偔 Okay
 *      ...
 *  vec[i] = CFoo::NewL(); // NG! 儊儌儕儕乕僋...
 *              @endcode
 *              忋婰椺偺応崌丄棙梡幰偑(偄偮傕偺傛偆偵)堄幆偟偰丄
 *              @code
 *  CFoo* foo = CFoo::NewL();   // 怴偟偄僆僽僕僃僋僩偼丄
 *  delete vec[i];              // 婛懚偺傪攋婞偟偰偐傜丄
 *  vec[i] = foo;               // 抲偒姺偊傞丅
 *              @endcode
 *              偲偡傞偟偐側偄丅
 *
 *  @see    @ref Usage_RSmbMusicAPLibVector "摦揑攝楍僐儞僥僫 RSmbMusicAPLibVector 偺棙梡曽朄"
 */
template<typename T, class DeletePolicy = TSmbMusicAPLib_NotDelete>
class RSmbMusicAPLibVector
    {
    typedef RSmbMusicAPLibVector<T, DeletePolicy>   vector_type;    /**< 偙偺儀僋僩儖偺宆丅 */

public:
    typedef T                   value_type;         /**< 抣梫慺偺宆丅 */
    typedef value_type*         pointer;            /**< 抣梫慺傪巜偡億僀儞僞偺宆丅 */
    typedef const value_type*   const_pointer;      /**< const側抣梫慺傪巜偡億僀儞僞偺宆丅 */
    typedef value_type&         reference;          /**< 抣梫慺偺嶲徠宆丅 */
    typedef const value_type&   const_reference;    /**< const側抣梫慺偺嶲徠宆丅 */
    typedef detail::TSmbMusicAPLib_normal_iterator<pointer, vector_type>        iterator;       /**< 抣梫慺傪巜偡斀暅巕偺宆丅 */
    typedef detail::TSmbMusicAPLib_normal_iterator<const_pointer, vector_type>  const_iterator; /**< const側抣梫慺傪巜偡斀暅巕偺宆丅 */
    typedef TSmbMusicAPLib_reverse_iterator<iterator>       reverse_iterator;       /**< 媡峴斀暅巕偺宆丅 */
    typedef TSmbMusicAPLib_reverse_iterator<const_iterator> const_reverse_iterator; /**< 媡峴斀暅巕(const)偺宆丅 */
    typedef size_t              size_type;          /**< 梫慺悢側偳偺昞尰偵梡偄傞宆丅 */
    typedef ptrdiff_t           difference_type;    /**< 梫慺娫偺嫍棧側偳偺昞尰偵梡偄傞宆丅 */

public:
    /**
     *  僨僼僅儖僩僐儞僗僩儔僋僞丅
     *
     *  挿偝僛儘偺儀僋僩儖傪嶌惉偡傞丅
     */
    RSmbMusicAPLibVector();
    /**
     *  僐儞僗僩儔僋僞丅
     *
     *  慡梫慺偑 @a aVal 偺抣偵弶婜壔偝傟偨挿偝 @a aNum 偺儀僋僩儖傪惗惉偡傞丅
     *
     *  @param[in]  aNum    儀僋僩儖偺挿偝丅
     *  @param[in]  aVal    梫慺偺弶婜抣丅
     *  @attention  Leave 偟偆傞丅 STL僐儞僥僫偲摨偠乽抣偺僙儅儞僥傿僋僗乿偲偟偨偄偨傔丄SymbianOS 偺尨懃奜偱偁傞偙偲偼彸抦偺忋偱丄偁偊偰偙偆偟偰偄傞丅
     *              偨偩偟丄Leave 敪惗帪偱傕儊儌儕儕乕僋偼敪惗偝偣側偄丄懳嶔幚憰偼堊偝傟偰偄傞丅
     */
    explicit RSmbMusicAPLibVector( size_type aNum, const value_type& aVal=T() );
    /**
     *  僐僺乕僐儞僗僩儔僋僞丅
     *
     *  @param[in]  aRhs    僐僺乕尦丅
     *  @attention  Leave 偟偆傞丅 STL僐儞僥僫偲摨偠乽抣偺僙儅儞僥傿僋僗乿偲偟偨偄偨傔丄SymbianOS 偺尨懃奜偱偁傞偙偲偼彸抦偺忋偱丄偁偊偰偙偆偟偰偄傞丅
     *              偨偩偟丄Leave 敪惗帪偱傕儊儌儕儕乕僋偼敪惗偝偣側偄丄懳嶔幚憰偼堊偝傟偰偄傞丅
     */
    RSmbMusicAPLibVector( const RSmbMusicAPLibVector& aRhs );
    /**
     *  僐儞僗僩儔僋僞丅
     *
     *  斖埻 [@a aFirst, @a aLast) 偺梫慺偺抣僐僺乕偐傜惉傞丄挿偝 @a aFirst - @a aLast 偺儀僋僩儖傪嶌惉偡傞丅
     *
     *  @param[in]  aFirst  擖椡奐巒埵抲丅
     *  @param[in]  aLast   擖椡廔椆埵抲丅
     *  @attention  僀僥儗乕僞宆 @a InputIterator 傊偺梫媮帠崁偼 STL 偵摨偠丅
     *  @attention  Leave 偟偆傞丅 STL僐儞僥僫偲摨偠乽抣偺僙儅儞僥傿僋僗乿偲偟偨偄偨傔丄SymbianOS 偺尨懃奜偱偁傞偙偲偼彸抦偺忋偱丄偁偊偰偙偆偟偰偄傞丅
     *              偨偩偟丄Leave 敪惗帪偱傕儊儌儕儕乕僋偼敪惗偝偣側偄丄懳嶔幚憰偼堊偝傟偰偄傞丅
     */
    template<typename InputIterator>
    RSmbMusicAPLibVector( InputIterator aFirst, InputIterator aLast );
    /**
     *  僨僗僩儔僋僞丅
     *
     *  Release() 傪屇傃弌偡丅
     *
     *  @attention  SymbianOS 偵偍偗傞 R* 僋儔僗偺尨懃偐傜偼偼偢傟傞偑丄robustness 偺偨傔偵僨僗僩儔僋僞傪愝偗傞丅
     */
    ~RSmbMusicAPLibVector();

    /**
     *  梫慺偺戙擖丅
     *
     *  帺屓偵娷傑傟傞慡梫慺傪徚嫀偟丄師偵 [@a aFirst, @a aLast) 偺斖埻偺梫慺偺抣僐僺乕傪憓擖偡傞丅
     *
     *  @param[in]  aFirst  擖椡奐巒埵抲丅
     *  @param[in]  aLast   擖椡廔椆埵抲丅
     */
    template<typename InputIterator>
    void AssignL( InputIterator aFirst, InputIterator aLast );
    /**
     *  梫慺偺戙擖丅
     *
     *  帺屓偵娷傑傟傞慡梫慺傪徚嫀偟丄師偵梫慺 @a aVal 偺抣僐僺乕傪 @a aNum 屄憓擖偡傞丅
     *
     *  @param[in]  aNum    梫慺悢丅
     *  @param[in]  aVal    梫慺丅
     */
    void AssignL( size_type aNum, const value_type& aVal );
    /**
     *  戙擖墘嶼巕丅
     *
     *  @param[in]  aRhs    僐僺乕尦丅
     *  @return *this 傪曉偡丅
     *  @attention  Leave 偟偆傞丅
     */
    RSmbMusicAPLibVector& operator=( const RSmbMusicAPLibVector& aRhs );

    /**
     *  嵟弶偺梫慺傪億僀儞僩偡傞斀暅巕傪曉偡丅
     *
     *  @return 嵟弶偺梫慺傪億僀儞僩偡傞斀暅巕丅
     */
    iterator Begin();
    /**
     *  嵟弶偺梫慺傪億僀儞僩偡傞斀暅巕傪曉偡丅
     *
     *  @return 嵟弶偺梫慺傪億僀儞僩偡傞斀暅巕丅
     */
    const_iterator Begin() const;
    /**
     *  嵟屻偺梫慺偺捈屻偺梫慺傪億僀儞僩偡傞斀暅巕傪曉偡丅
     *
     *  @return 嵟屻偺梫慺偺捈屻偺梫慺傪億僀儞僩偡傞斀暅巕丅
     */
    iterator End();
    /**
     *  嵟屻偺梫慺偺捈屻偺梫慺傪億僀儞僩偡傞斀暅巕傪曉偡丅
     *
     *  @return 嵟屻偺梫慺偺捈屻偺梫慺傪億僀儞僩偡傞斀暅巕丅
     */
    const_iterator End() const;

    /**
     *  End() 傪巜偡媡峴斀暅巕傪曉偡丅
     *
     *  @return End() 傪巜偡媡峴斀暅巕丅
     */
    reverse_iterator RBegin();
    /**
     *  End() const 傪巜偡媡峴斀暅巕傪曉偡丅
     *
     *  @return End() const 傪巜偡媡峴斀暅巕丅
     */
    const_reverse_iterator RBegin() const;
    /**
     *  Begin() 傪巜偡媡峴斀暅巕傪曉偡丅
     *
     *  @return Begin() 傪巜偡媡峴斀暅巕丅
     */
    reverse_iterator REnd();
    /**
     *  Begin() const 傪巜偡媡峴斀暅巕傪曉偡丅
     *
     *  @return Begin() const 傪巜偡媡峴斀暅巕丅
     */
    const_reverse_iterator REnd() const;

    /**
     *  偙偺儀僋僩儖偺梫慺悢傪曉偡丅
     *
     *  @return 偙偺儀僋僩儖偺梫慺悢丅
     */
    size_type Size() const;
    /**
     *  儀僋僩儖偺嵟戝壜擻梫慺悢傪曉偡丅
     *
     *  @return KMaxTInt / sizeof(value_type) 傪曉偡丅
     */
    size_type Max_size() const;
    /**
     *  偙偺儀僋僩儖偺僒僀僘傪曄峏偡傞丅
     *
     *  偙偺儀僋僩儖偺僒僀僘傪 @a aNum 偵曄峏偡傞丅
     *  @a aNum > Size() 偺応崌丄@a aNum 偺抣僐僺乕 @a aNum - Size() 屄偑枛旜偵憓擖偝傟傞丅
     *  @a aNum < Size() 偺応崌丄枛旜 Size() - @a aNum 屄偺梫慺偑嶍彍偝傟傞丅
     *
     *  @param[in]  aNum    梫慺悢丅
     *  @param[in]  aVal    @a aNum > Size() 偺応崌偵枛旜偵憓擖偡傞抣丅
     */
    void ResizeL( size_type aNum, const value_type& aVal=T() );
    /**
     *  偙偺儀僋僩儖偺梕検傪曉偡丅
     *
     *  @return 偙偺儀僋僩儖偑摦揑儊儌儕偺嵞妱傝摉偰傪峴偆偙偲側偔奿擺壜擻側嵟戝梫慺悢丅
     *  @attention  Size() const 偲偼堄枴偑堎側傞丅
     *  @see    ReserveL()
     */
    size_type Capacity() const;
    /**
     *  偙偺儀僋僩儖偑嬻偱偁傞偐傪曉偡丅
     *
     *  @return Size() 偑 0 側傜偽恀傪丄偦偆偱側偗傟偽婾傪曉偡丅
     */
    TBool Empty() const;
    /**
     *  梕検傪妋曐偡傞丅
     *
     *  彮側偔偲傕 @a aNum 屄偺梫慺傪奿擺偱偒傞儊儌儕梕検傪妋曐偡傞丅
     *  惓忢廔椆帪丄 Capacity() >= @a aNum 偑曐徹偝傟傞丅
     *  尰嵼奿擺偝傟偰偄傞梫慺偼塭嬁傪庴偗偢 Size() 傕曄傢傜側偄丅
     *
     *  @param[in]  aNum    梫慺悢丅