| /************************************************************** | |
| * | |
| * Licensed to the Apache Software Foundation (ASF) under one | |
| * or more contributor license agreements. See the NOTICE file | |
| * distributed with this work for additional information | |
| * regarding copyright ownership. The ASF licenses this file | |
| * to you under the Apache License, Version 2.0 (the | |
| * "License"); you may not use this file except in compliance | |
| * with the License. You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the License. | |
| * | |
| *************************************************************/ | |
| #ifndef __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_ | |
| #define __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_ | |
| //_________________________________________________________________________________________________________________ | |
| // my own includes | |
| //_________________________________________________________________________________________________________________ | |
| #include <macros/debug.hxx> | |
| //_________________________________________________________________________________________________________________ | |
| // interface includes | |
| //_________________________________________________________________________________________________________________ | |
| //_________________________________________________________________________________________________________________ | |
| // other includes | |
| //_________________________________________________________________________________________________________________ | |
| #include <sal/types.h> | |
| #ifndef __SGI_STL_ITERATOR | |
| #include <iterator> | |
| #endif | |
| //_________________________________________________________________________________________________________________ | |
| // namespace | |
| //_________________________________________________________________________________________________________________ | |
| namespace framework{ | |
| //_________________________________________________________________________________________________________________ | |
| // exported const | |
| //_________________________________________________________________________________________________________________ | |
| //_________________________________________________________________________________________________________________ | |
| // exported definitions | |
| //_________________________________________________________________________________________________________________ | |
| /*-************************************************************************************************************//** | |
| @short implement a iterator which support 2 end states! | |
| @descr For our search methods we need a "walking" iterator object with special functionality! | |
| We must check for 3 different states of an iterator - normal position, exact end, after end. | |
| It's necessary to detect if we have not found a entry and must return our default or | |
| default already returned and we must break loop! | |
| see using in class FilterCache too for further informations! | |
| @Attention If your wish to debug this inline code ... | |
| under windows and msdev you can use "set ENVCFLAGS=/Ob0" to do that! | |
| @implements - | |
| @base - | |
| @devstatus ready to use | |
| @threadsafe no | |
| *//*-*************************************************************************************************************/ | |
| template< class TContainer > | |
| class CheckedIterator | |
| { | |
| //------------------------------------------------------------------------------------------------------------- | |
| // public methods | |
| //------------------------------------------------------------------------------------------------------------- | |
| public: | |
| //--------------------------------------------------------------------------------------------------------- | |
| // constructor / destructor | |
| //--------------------------------------------------------------------------------------------------------- | |
| /*-****************************************************************************************************//** | |
| @short standard constructor | |
| @descr Set default values on members. | |
| We set it internal to E_UNKNOWN to detect uninitialized instances of this class. | |
| If we found one - we know: "We must call initialize first!" | |
| @seealso - | |
| @param - | |
| @return - | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline CheckedIterator() | |
| : m_eEndState ( E_UNKNOWN ) | |
| , m_pContainer( NULL ) | |
| { | |
| } | |
| //--------------------------------------------------------------------------------------------------------- | |
| // interface methods | |
| //--------------------------------------------------------------------------------------------------------- | |
| /*-****************************************************************************************************//** | |
| @short initialize instance with valid container | |
| @descr Set new container at an instance of this class. The other member will set automatically! | |
| m_pPosition = first element in container | |
| m_eEndState = BEFOREEND | |
| @seealso - | |
| @param "rContainer", must be a valid reference to an existing container. | |
| @return - | |
| @onerror An assertion is thrown. | |
| *//*-*****************************************************************************************************/ | |
| inline void initialize( const TContainer& rContainer ) | |
| { | |
| // Check incoming parameter. We don't accept all! | |
| LOG_ASSERT2( &rContainer==NULL , "CheckedIterator::initialize()", "Invalid parameter detected!" ) | |
| LOG_ASSERT2( m_eEndState!=E_UNKNOWN , "CheckedIterator::initialize()", "Instance already initialized! Don't do it again." ) | |
| if( m_eEndState == E_UNKNOWN ) | |
| { | |
| // Set new container and update other member. | |
| m_pContainer = &rContainer ; | |
| m_eEndState = E_BEFOREEND ; | |
| m_pPosition = m_pContainer->begin(); | |
| } | |
| } | |
| /*-****************************************************************************************************//** | |
| @short set internal states to E_END | |
| @descr Sometimes we need a "walking" check-iterator which is initialized with the END-state! | |
| We need it to return one default value if no other ones exist ... | |
| @seealso using in class FilterCache! | |
| @param - | |
| @return - | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline void setEnd() | |
| { | |
| m_pContainer = NULL ; | |
| m_eEndState = E_END ; | |
| } | |
| /*-****************************************************************************************************//** | |
| @short set internal states to E_AFTEREND | |
| @descr Sometimes we need a "walking" check-iterator which is initialized with AFTEREND-state! | |
| We need it if we don't have a container but must prevent us against further searching! | |
| @seealso using in class FilterCache! | |
| @param - | |
| @return - | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline void setAfterEnd() | |
| { | |
| m_pContainer = NULL ; | |
| m_eEndState = E_AFTEREND ; | |
| } | |
| /*-****************************************************************************************************//** | |
| @short reset this iterator | |
| @descr It must be called on an already initialized iterator. | |
| Means the member m_pContainer must be valid. Otherwise the reaction | |
| isn't defined. | |
| @param - | |
| @return - | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline void reset() | |
| { | |
| m_eEndState = E_UNKNOWN; | |
| m_pContainer = NULL; | |
| } | |
| /*-****************************************************************************************************//** | |
| @short step to next element in container. | |
| @descr If end of container is reached we change our internal "m_eEndState". | |
| If end reached for first time; we set it to E_END; | |
| If you step to next element again; we set it to E_AFTEREND. | |
| So you have a chance to differ between "exact end" and "after end"! | |
| @seealso method isEnd() | |
| @seealso method isAfterEnd() | |
| @param - | |
| @return A reference to our changed object himself. | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline CheckedIterator& operator++() | |
| { | |
| // Warn programmer if he forget to initialize object! | |
| LOG_ASSERT2( m_pContainer==NULL, "CheckedIterator::operator++()", "Object not initialized!" ) | |
| // Step to next element if any exist or set our end states. | |
| switch( m_eEndState ) | |
| { | |
| case E_BEFOREEND: { | |
| ++m_pPosition; | |
| // If iterator reaching end ... set right state! | |
| if( m_pPosition == m_pContainer->end() ) | |
| { | |
| m_eEndState = E_END; | |
| } | |
| } | |
| break; | |
| case E_END : { | |
| // Set state only ... iterator already points to end of container! | |
| m_eEndState = E_AFTEREND; | |
| } | |
| break; | |
| } | |
| return *this; | |
| } | |
| /*-****************************************************************************************************//** | |
| @short return true if internal iterator was not initialized before | |
| @descr These will be true, if use start a new search by using these iterator mechanism! | |
| @seealso class FilterCache | |
| @param - | |
| @return True if internal state E_UNKNOWN - false otherwise. | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline sal_Bool isUninitialized() | |
| { | |
| return( m_eEndState == E_UNKNOWN ); | |
| } | |
| /*-****************************************************************************************************//** | |
| @short return true if internal iterator reached end of container | |
| @descr These will be true if you step to the end of internal container. | |
| @seealso method isAfterEnd() | |
| @param - | |
| @return True if end reached; false otherwise. | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline sal_Bool isEnd() | |
| { | |
| // Is true if one end state is set! | |
| return ( | |
| ( m_eEndState == E_END ) || | |
| ( m_eEndState == E_AFTEREND ) | |
| ); | |
| } | |
| /*-****************************************************************************************************//** | |
| @short return true if you call operator++ again and end already reached | |
| @descr These indicate, that end already reached but you call operator++ again and again! | |
| @seealso method isEnd() | |
| @param - | |
| @return True if end multiple reached; false otherwise. | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline sal_Bool isAfterEnd() | |
| { | |
| // Is true only, if special end state is set! | |
| return( m_eEndState == E_AFTEREND ); | |
| } | |
| /*-****************************************************************************************************//** | |
| @short support readonly access to container entry | |
| @descr Use it to get the value of current container item. | |
| @seealso - | |
| @param - | |
| @return A reference to value of container entry. | |
| @onerror - | |
| *//*-*****************************************************************************************************/ | |
| inline typename TContainer::const_iterator getEntry() | |
| { | |
| // Warn programmer if he forget to initialize these object ... | |
| LOG_ASSERT2( m_pContainer==NULL, "CheckedIterator::getEntry()", "Object not initialized!" ) | |
| // or try to read a non existing element! | |
| LOG_ASSERT2( m_eEndState!=E_BEFOREEND, "CheckedIterator::getEntry()", "Wrong using of class detected!" ) | |
| return m_pPosition; | |
| } | |
| //------------------------------------------------------------------------------------------------------------- | |
| // private member | |
| //------------------------------------------------------------------------------------------------------------- | |
| private: | |
| // These enum defines our four states for an iterator position in current container. | |
| enum EEndState | |
| { | |
| E_UNKNOWN , | |
| E_BEFOREEND , | |
| E_END , | |
| E_AFTEREND | |
| }; | |
| const TContainer* m_pContainer ; // pointer to current container | |
| EEndState m_eEndState ; // "position state" of iterator! | |
| typename TContainer::const_iterator m_pPosition ; // point to actual element in container | |
| }; | |
| } // namespace framework | |
| #endif // #ifndef __FRAMEWORK_CLASSES_CHECKEDITERATOR_HXX_ |