framework/inc/classes/checkediterator.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: checkediterator.hxx,v $
  10  * $Revision: 1.15 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_
  32 #define __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <macros/debug.hxx>
  39
  40 //_________________________________________________________________________________________________________________
  41 //      interface includes
  42 //_________________________________________________________________________________________________________________
  43
  44 //_________________________________________________________________________________________________________________
  45 //      other includes
  46 //_________________________________________________________________________________________________________________
  47 #include <sal/types.h>
  48
  49 #ifndef __SGI_STL_ITERATOR
  50 #include <iterator>
  51 #endif
  52
  53 //_________________________________________________________________________________________________________________
  54 //      namespace
  55 //_________________________________________________________________________________________________________________
  56
  57 namespace framework{
  58
  59 //_________________________________________________________________________________________________________________
  60 //      exported const
  61 //_________________________________________________________________________________________________________________
  62
  63 //_________________________________________________________________________________________________________________
  64 //      exported definitions
  65 //_________________________________________________________________________________________________________________
  66
  67 /*-************************************************************************************************************//**
  68     @short          implement a iterator which support 2 end states!
  69     @descr                      For our search methods we need a "walking" iterator object with special functionality!
  70                     We must check for 3 different states of an iterator - normal position, exact end, after end.
  71                     It's neccessary to detect if we have not found a entry and must return our default or
  72                     default already returned and we must break loop!
  73                     see using in class FilterCache too for further informations!
  74
  75     @Attention          If your wish to debug this inline code ...
  76                     under windows and msdev you can use "set ENVCFLAGS=/Ob0" to do that!
  77
  78     @implements         -
  79     @base                       -
  80
  81     @devstatus          ready to use
  82     @threadsafe         no
  83 *//*-*************************************************************************************************************/
  84
  85 template< class TContainer >
  86 class CheckedIterator
  87 {
  88     //-------------------------------------------------------------------------------------------------------------
  89     //  public methods
  90     //-------------------------------------------------------------------------------------------------------------
  91
  92     public:
  93
  94         //---------------------------------------------------------------------------------------------------------
  95         // constructor / destructor
  96         //---------------------------------------------------------------------------------------------------------
  97
  98         /*-****************************************************************************************************//**
  99             @short              standard constructor
 100             @descr              Set default values on members.
 101                         We set it internal to E_UNKNOWN to detect uninitialized instances of this class.
 102                         If we found one - we know: "We must call initialize first!"
 103
 104             @seealso    -
 105
 106             @param              -
 107             @return             -
 108
 109             @onerror    -
 110         *//*-*****************************************************************************************************/
 111
 112         inline CheckedIterator()
 113                 :   m_eEndState ( E_UNKNOWN )
 114                 ,   m_pContainer( NULL      )
 115         {
 116         }
 117
 118         //---------------------------------------------------------------------------------------------------------
 119         // interface methods
 120         //---------------------------------------------------------------------------------------------------------
 121
 122         /*-****************************************************************************************************//**
 123             @short              initialize instance with valid container
 124             @descr              Set new container at an instance of this class. The other member will set automaticly!
 125                         m_pPosition = first element in container
 126                         m_eEndState = BEFOREEND
 127
 128             @seealso    -
 129
 130             @param      "rContainer", must be a valid reference to an existing container.
 131             @return             -
 132
 133             @onerror    An assertion is thrown.
 134         *//*-*****************************************************************************************************/
 135
 136         inline void initialize( const TContainer& rContainer )
 137         {
 138             // Check incoming parameter. We don't accept all!
 139             LOG_ASSERT2( &rContainer==NULL      , "CheckedIterator::initialize()", "Invalid parameter detected!"                        )
 140             LOG_ASSERT2( m_eEndState!=E_UNKNOWN , "CheckedIterator::initialize()", "Instance already initialized! Don't do it again."   )
 141
 142             if( m_eEndState == E_UNKNOWN )
 143             {
 144                 // Set new container and actualize other member.
 145                 m_pContainer = &rContainer          ;
 146                 m_eEndState  = E_BEFOREEND          ;
 147                 m_pPosition  = m_pContainer->begin();
 148             }
 149         }
 150
 151         /*-****************************************************************************************************//**
 152             @short              set internal states to E_END
 153             @descr              Sometimes we need a "walking" check-iterator which is initialized with the END-state!
 154                         We need it to return one default value if no other ones exist ...
 155
 156             @seealso    using in class FilterCache!
 157
 158             @param              -
 159             @return             -
 160
 161             @onerror    -
 162         *//*-*****************************************************************************************************/
 163
 164         inline void setEnd()
 165         {
 166             m_pContainer = NULL  ;
 167             m_eEndState  = E_END ;
 168         }
 169
 170         /*-****************************************************************************************************//**
 171             @short              set internal states to E_AFTEREND
 172             @descr              Sometimes we need a "walking" check-iterator which is initialized with AFTEREND-state!
 173                         We need it if we don't have a container but must prevent us against further searching!
 174
 175             @seealso    using in class FilterCache!
 176
 177             @param              -
 178             @return             -
 179
 180             @onerror    -
 181         *//*-*****************************************************************************************************/
 182
 183         inline void setAfterEnd()
 184         {
 185             m_pContainer = NULL       ;
 186             m_eEndState  = E_AFTEREND ;
 187         }
 188
 189         /*-****************************************************************************************************//**
 190             @short      reset this iterator
 191             @descr      It must be called on an already initialized iterator.
 192                         Means the member m_pContainer must be valid. Otherwhise the reaction
 193                         isn't defined.
 194
 195             @param      -
 196             @return     -
 197
 198             @onerror    -
 199         *//*-*****************************************************************************************************/
 200
 201         inline void reset()
 202         {
 203             m_eEndState  = E_UNKNOWN;
 204             m_pContainer = NULL;
 205         }
 206
 207         /*-****************************************************************************************************//**
 208             @short              step to next element in container.
 209             @descr              If end of container is reached we change our internal "m_eEndState".
 210                         If end reached for first time; we set it to E_END;
 211                         If you step to next element again; we set it to E_AFTEREND.
 212                         So you have a chance to differ between "exact end" and "after end"!
 213
 214             @seealso    method isEnd()
 215             @seealso    method isAfterEnd()
 216
 217             @param              -
 218             @return             A reference to our changed object himself.
 219
 220             @onerror    -
 221         *//*-*****************************************************************************************************/
 222
 223         inline CheckedIterator& operator++()
 224         {
 225             // Warn programmer if he forget to initailize object!
 226             LOG_ASSERT2( m_pContainer==NULL, "CheckedIterator::operator++()", "Object not initialized!" )
 227             // Step to next element if any exist or set our end states.
 228             switch( m_eEndState )
 229             {
 230                 case E_BEFOREEND:       {
 231                                         ++m_pPosition;
 232                                         // If iterator reaching end ... set right state!
 233                                         if( m_pPosition == m_pContainer->end() )
 234                                         {
 235                                             m_eEndState = E_END;
 236                                         }
 237                                     }
 238                                     break;
 239                 case E_END              :       {
 240                                         // Set state only ... iterator already points to end of container!
 241                                         m_eEndState = E_AFTEREND;
 242                                     }
 243                                     break;
 244             }
 245             return *this;
 246         }
 247
 248         /*-****************************************************************************************************//**
 249             @short              return true if internal iterator was not initialized before
 250             @descr              These will be true, if use start a new search by using these iterator mechanism!
 251
 252             @seealso    class FilterCache
 253
 254             @param              -
 255             @return             True if internalk state E_UNKNOWN - false otherwise.
 256
 257             @onerror    -
 258         *//*-*****************************************************************************************************/
 259
 260         inline sal_Bool isUninitialized()
 261         {
 262             return( m_eEndState == E_UNKNOWN );
 263         }
 264
 265         /*-****************************************************************************************************//**
 266             @short              return true if internal iterator reached end of container
 267             @descr              These will be true if you step to the end of internal container.
 268
 269             @seealso    method isAfterEnd()
 270
 271             @param              -
 272             @return             True if end reached; false otherwise.
 273
 274             @onerror    -
 275         *//*-*****************************************************************************************************/
 276
 277         inline sal_Bool isEnd()
 278         {
 279             // Is true if one end state is set!
 280             return      (
 281                         ( m_eEndState == E_END          )       ||
 282                         ( m_eEndState == E_AFTEREND     )
 283                     );
 284         }
 285
 286         /*-****************************************************************************************************//**
 287             @short              return true if you call operator++ again and end already reached
 288             @descr              These indicate, that end already reached but you call operator++ again and again!
 289
 290             @seealso    method isEnd()
 291
 292             @param              -
 293             @return             True if end multiple reached; false otherwise.
 294
 295             @onerror    -
 296         *//*-*****************************************************************************************************/
 297
 298         inline sal_Bool isAfterEnd()
 299         {
 300             // Is true only, if special end state is set!
 301             return( m_eEndState == E_AFTEREND );
 302         }
 303
 304         /*-****************************************************************************************************//**
 305             @short              support readonly access to container entry
 306             @descr              Use it to get the value of current container item.
 307
 308             @seealso    -
 309
 310             @param              -
 311             @return             A reference to value of container entry.
 312
 313             @onerror    -
 314         *//*-*****************************************************************************************************/
 315
 316         inline typename TContainer::const_iterator getEntry()
 317         {
 318             // Warn programmer if he forget to initialize these object ...
 319             LOG_ASSERT2( m_pContainer==NULL, "CheckedIterator::getEntry()", "Object not initialized!" )
 320             // or try to read a non existing element!
 321             LOG_ASSERT2( m_eEndState!=E_BEFOREEND, "CheckedIterator::getEntry()", "Wrong using of class detected!" )
 322
 323             return m_pPosition;
 324         }
 325
 326     //-------------------------------------------------------------------------------------------------------------
 327     //  private member
 328     //-------------------------------------------------------------------------------------------------------------
 329
 330     private:
 331
 332         // These enum defines our four states for an iterator position in curent container.
 333         enum EEndState
 334         {
 335             E_UNKNOWN   ,
 336             E_BEFOREEND ,
 337             E_END               ,
 338             E_AFTEREND
 339         };
 340
 341         const TContainer*           m_pContainer    ;   // pointer to current container
 342         EEndState                   m_eEndState     ;   // "position state" of iterator!
 343         typename TContainer::const_iterator  m_pPosition     ;   // point to actual element in container
 344 };
 345
 346 }               //      namespace framework
 347
 348 #endif  //      #ifndef __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_