| /************************************************************** |
| * |
| * 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 neccessary 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 automaticly! |
| 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. Otherwhise 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 initailize 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 internalk 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 curent 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_ |
