/**************************************************************
 * 
 * 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. 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_