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 INCLUDED_FRAMEWORK_INC_CLASSES_CHECKEDITERATOR_HXX
  21 #define INCLUDED_FRAMEWORK_INC_CLASSES_CHECKEDITERATOR_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <sal/log.hxx>
  26 #include <sal/types.h>
  27
  28 #include <iterator>
  29
  30 namespace framework{
  31
  32 /*-************************************************************************************************************
  33     @short          implement a iterator which support 2 end states!
  34     @descr          For our search methods we need a "walking" iterator object with special functionality!
  35                     We must check for 3 different states of an iterator - normal position, exact end, after end.
  36                     It's necessary to detect if we have not found a entry and must return our default or
  37                     default already returned and we must break loop!
  38                     see using in class FilterCache too for further information!
  39
  40     @Attention      If your wish to debug this inline code ...
  41                     under windows and msdev you can use "set ENVCFLAGS=/Ob0" to do that!
  42     @devstatus      ready to use
  43     @threadsafe     no
  44 *//*-*************************************************************************************************************/
  45
  46 template< class TContainer >
  47 class CheckedIterator
  48 {
  49
  50     //  public methods
  51
  52     public:
  53
  54         // constructor / destructor
  55
  56         /*-****************************************************************************************************
  57             @short      standard constructor
  58             @descr      Set default values on members.
  59                         We set it internal to E_UNKNOWN to detect uninitialized instances of this class.
  60                         If we found one - we know: "We must call initialize first!"
  61         *//*-*****************************************************************************************************/
  62
  63         inline CheckedIterator()
  64                 :   m_eEndState ( E_UNKNOWN )
  65                 ,   m_pContainer( NULL      )
  66         {
  67         }
  68
  69         // interface methods
  70
  71         /*-****************************************************************************************************
  72             @short      initialize instance with valid container
  73             @descr      Set new container at an instance of this class. The other member will set automatically!
  74                         m_pPosition = first element in container
  75                         m_eEndState = BEFOREEND
  76             @param      "rContainer", must be a valid reference to an existing container.
  77             @onerror    An assertion is thrown.
  78         *//*-*****************************************************************************************************/
  79
  80         inline void initialize( const TContainer& rContainer )
  81         {
  82             // Check incoming parameter. We don't accept all!
  83             SAL_WARN_IF( &rContainer==NULL, "fwk", "CheckedIterator::initialize(): Invalid parameter detected!" );
  84             SAL_WARN_IF( m_eEndState!=E_UNKNOWN, "fwk", "CheckedIterator::initialize(): Instance already initialized! Don't do it again." );
  85
  86             if( m_eEndState == E_UNKNOWN )
  87             {
  88                 // Set new container and update other member.
  89                 m_pContainer = &rContainer;
  90                 m_eEndState  = E_BEFOREEND;
  91                 m_pPosition  = m_pContainer->begin();
  92             }
  93         }
  94
  95         /*-****************************************************************************************************
  96             @short      set internal states to E_END
  97             @descr      Sometimes we need a "walking" check-iterator which is initialized with the END-state!
  98                         We need it to return one default value if no other ones exist ...
  99
 100             @seealso    using in class FilterCache!
 101         *//*-*****************************************************************************************************/
 102
 103         inline void setEnd()
 104         {
 105             m_pContainer = NULL;
 106             m_eEndState  = E_END;
 107         }
 108
 109         /*-****************************************************************************************************
 110             @short      set internal states to E_AFTEREND
 111             @descr      Sometimes we need a "walking" check-iterator which is initialized with AFTEREND-state!
 112                         We need it if we don't have a container but must prevent us against further searching!
 113
 114             @seealso    using in class FilterCache!
 115         *//*-*****************************************************************************************************/
 116
 117         inline void setAfterEnd()
 118         {
 119             m_pContainer = NULL;
 120             m_eEndState  = E_AFTEREND;
 121         }
 122
 123         /*-****************************************************************************************************
 124             @short      reset this iterator
 125             @descr      It must be called on an already initialized iterator.
 126                         Means the member m_pContainer must be valid. Otherwise the reaction
 127                         isn't defined.
 128         *//*-*****************************************************************************************************/
 129
 130         inline void reset()
 131         {
 132             m_eEndState  = E_UNKNOWN;
 133             m_pContainer = NULL;
 134         }
 135
 136         /*-****************************************************************************************************
 137             @short      step to next element in container.
 138             @descr      If end of container is reached we change our internal "m_eEndState".
 139                         If end reached for first time; we set it to E_END;
 140                         If you step to next element again; we set it to E_AFTEREND.
 141                         So you have a chance to differ between "exact end" and "after end"!
 142
 143             @seealso    method isEnd()
 144             @seealso    method isAfterEnd()
 145             @return     A reference to our changed object himself.
 146         *//*-*****************************************************************************************************/
 147
 148         inline CheckedIterator& operator++()
 149         {
 150             // Warn programmer if he forget to initailize object!
 151             SAL_WARN_IF( m_pContainer==NULL, "fwk", "CheckedIterator::operator++(): Object not initialized!" );
 152             // Step to next element if any exist or set our end states.
 153             switch( m_eEndState )
 154             {
 155                 case E_BEFOREEND:   {
 156                                         ++m_pPosition;
 157                                         // If iterator reaching end ... set right state!
 158                                         if( m_pPosition == m_pContainer->end() )
 159                                         {
 160                                             m_eEndState = E_END;
 161                                         }
 162                                     }
 163                                     break;
 164                 case E_END      :   {
 165                                         // Set state only ... iterator already points to end of container!
 166                                         m_eEndState = E_AFTEREND;
 167                                     }
 168                                     break;
 169             }
 170             return *this;
 171         }
 172
 173         /*-****************************************************************************************************
 174             @short      return true if internal iterator was not initialized before
 175             @descr      These will be true, if use start a new search by using these iterator mechanism!
 176
 177             @seealso    class FilterCache
 178             @return     True if internalk state E_UNKNOWN - false otherwise.
 179         *//*-*****************************************************************************************************/
 180
 181         inline bool isUninitialized()
 182         {
 183             return( m_eEndState == E_UNKNOWN );
 184         }
 185
 186         /*-****************************************************************************************************
 187             @short      return true if internal iterator reached end of container
 188             @descr      These will be true if you step to the end of internal container.
 189
 190             @seealso    method isAfterEnd()
 191             @return     True if end reached; false otherwise.
 192         *//*-*****************************************************************************************************/
 193
 194         inline bool isEnd()
 195         {
 196             // Is true if one end state is set!
 197             return  (
 198                         ( m_eEndState == E_END      )   ||
 199                         ( m_eEndState == E_AFTEREND )
 200                     );
 201         }
 202
 203         /*-****************************************************************************************************
 204             @short      return true if you call operator++ again and end already reached
 205             @descr      These indicate, that end already reached but you call operator++ again and again!
 206
 207             @seealso    method isEnd()
 208             @return     True if end multiple reached; false otherwise.
 209         *//*-*****************************************************************************************************/
 210
 211         inline bool isAfterEnd()
 212         {
 213             // Is true only, if special end state is set!
 214             return( m_eEndState == E_AFTEREND );
 215         }
 216
 217         /*-****************************************************************************************************
 218             @short      support readonly access to container entry
 219             @descr      Use it to get the value of current container item.
 220             @return     A reference to value of container entry.
 221         *//*-*****************************************************************************************************/
 222
 223         inline typename TContainer::const_iterator getEntry()
 224         {
 225             // Warn programmer if he forget to initialize these object ...
 226             SAL_WARN_IF( m_pContainer==NULL, "fwk", "CheckedIterator::getEntry(): Object not initialized!" );
 227             // or try to read a non existing element!
 228             SAL_WARN_IF( m_eEndState!=E_BEFOREEND, "fwk", "CheckedIterator::getEntry(): Wrong using of class detected!" );
 229
 230             return m_pPosition;
 231         }
 232
 233     //  private member
 234
 235     private:
 236
 237         // This enum defines our four states for an iterator position in current container.
 238         enum EEndState
 239         {
 240             E_UNKNOWN   ,
 241             E_BEFOREEND ,
 242             E_END       ,
 243             E_AFTEREND
 244         };
 245
 246         const TContainer*           m_pContainer;   // pointer to current container
 247         EEndState                   m_eEndState;   // "position state" of iterator!
 248         typename TContainer::const_iterator  m_pPosition;   // point to actual element in container
 249 };
 250
 251 }       //  namespace framework
 252
 253 #endif // INCLUDED_FRAMEWORK_INC_CLASSES_CHECKEDITERATOR_HXX
 254
 255 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */