framework/inc/classes/checkediterator.hxx

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