2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FBaseColStackT.h
19 * @brief This is the header file for the %StackT class.
21 * This header file contains the declarations of the %StackT class.
24 #ifndef _FBASE_COL_STACK_T_H_
25 #define _FBASE_COL_STACK_T_H_
27 #include <FBaseObject.h>
28 #include <FBaseResult.h>
29 #include <FBaseColICollectionT.h>
31 namespace Tizen { namespace Base { namespace Collection
34 template< class Type > class __StackEnumeratorT;
38 * @brief This class represents a template-based stack (a last-in-first-out collection of objects).
42 * The %StackT class represents a template-based stack (a last-in-first-out collection of objects).
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/queue_stack.htm">Stack and Queue</a>.
46 * The following example demonstrates how to use the %StackT class.
51 * using namespace Tizen::Base;
52 * using namespace Tizen::Base::Collection;
55 * MyClass::StackTSample(void)
57 * StackT< String > stack;
60 * String str1(L"First");
61 * String str2(L"Second");
62 * String str3(L"Third");
68 * // Reads the element at the top
70 * stack.Peek(temp); // temp: "Third", stack.GetCount(): 3
72 * // Reads and removes the element at the top
73 * stack.Pop(temp); // temp: "Third", stack.GetCount(): 2
77 template< class Type >
79 : public virtual ICollectionT< Type >
84 * The object is not fully constructed after this constructor is called. For full construction, @n
85 * the Construct() method must be called right after calling this constructor.
98 * This destructor overrides Tizen::Base::Object::~Object().
102 virtual ~StackT(void)
109 * Initializes this instance of %StackT with the specified @c capacity.
113 * @return An error code
114 * @param[in] capacity The number of elements @n
115 * The default capacity is @c 10.
116 * @exception E_SUCCESS The method is successful.
117 * @exception E_INVALID_ARG Either of the following conditions has occurred:
118 * - The specified input parameter is invalid.
119 * - The specified @c capacity is negative.
121 result Construct(int capacity = DEFAULT_CAPACITY)
123 TryReturn(capacity >= 0, E_INVALID_ARG, "[%s] The capacity(%d) MUST be greater than or equal to 0.", GetErrorMessage(E_INVALID_ARG), capacity);
127 __pObjArray = new Type[capacity];
128 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
130 __capacity = capacity;
136 * Initializes this instance of %StackT that contains the elements of the specified @c collection. @n
137 * The capacity of the stack is the same as the number of elements copied.
141 * @return An error code
142 * @param[in] collection The collection to copy elements from
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
145 * - The current state of the instance prohibits the execution of the specified operation.
146 * - The specified @c collection is modified during the operation of this method.
149 result Construct(const ICollectionT< Type >& collection)
151 result r = E_SUCCESS;
153 IEnumeratorT< Type >* pEnum = null;
154 if (collection.GetCount() > 0)
156 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
157 pEnum = pCol->GetEnumeratorN();
158 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
164 r = pEnum->MoveNext();
165 // enumerator is reached to the end of collection
166 if (E_OUT_OF_RANGE == r)
171 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
173 r = pEnum->GetCurrent(temp);
174 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
177 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
198 * Gets the enumerator of this stack.
202 * @return The enumerator (an instance of the IEnumeratorT derived class) of this stack, @n
203 * else @c null if an exception occurs
204 * @exception E_SUCCESS The method is successful.
205 * @exception E_OUT_OF_MEMORY The memory is insufficient.
206 * @remarks The specific error code can be accessed using the GetLastResult() method.
208 virtual IEnumeratorT< Type >* GetEnumeratorN(void) const
212 result r = E_SUCCESS;
214 __StackEnumeratorT< Type >* pEnum = new __StackEnumeratorT< Type >(*this, __modCount);
215 TryCatch(pEnum != null, r = E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
225 * Reads the element at the beginning of this stack without removing it.
229 * @return An error code
230 * @param[out] obj The element at the beginning of this stack
231 * @exception E_SUCCESS The method is successful.
232 * @exception E_UNDERFLOW Either of the following conditions has occurred:
233 * - The operation (arithmetic/casting/conversion) has caused an underflow.
234 * - The stack is empty.
236 virtual result Peek(Type& obj) const
243 obj = __pObjArray[__index];
249 * Pops the element from the beginning of this stack.
253 * @return An error code
254 * @param[out] obj The element at the beginning of this stack
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_UNDERFLOW Either of the following conditions has occurred:
257 * - The operation (arithmetic/casting/conversion) has caused an underflow.
258 * - The stack is empty.
261 virtual result Pop(Type& obj)
270 obj = __pObjArray[__index];
278 * Pushes an object to the top of this stack.
282 * @return An error code
283 * @param[in] obj The object to add to this stack
284 * @exception E_SUCCESS The method is successful.
285 * @exception E_OUT_OF_MEMORY The memory is insufficient.
288 virtual result Push(const Type& obj)
291 if (null == __pObjArray)
293 __pObjArray = new Type[DEFAULT_CAPACITY];
294 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
296 __capacity = DEFAULT_CAPACITY;
298 else if ((__index + 1) >= __capacity)
300 Type* pArrayTemp = new Type[__capacity + DEFAULT_CAPACITY];
301 TryReturn(pArrayTemp != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
303 for (int i = 0; i <= __index; i++)
305 pArrayTemp[i] = __pObjArray[i];
308 delete[] __pObjArray;
310 __pObjArray = pArrayTemp;
311 __capacity += DEFAULT_CAPACITY;
317 __pObjArray[++__index] = obj;
323 * Removes all the elements from this stack.
327 virtual void RemoveAll(void)
329 if (__pObjArray != null)
331 delete[] __pObjArray;
342 * Gets the number of objects currently stored in this stack.
346 * @return The number of objects currently stored in this stack
348 virtual int GetCount(void) const
354 * Checks whether this stack contains the specified object.
358 * @return @c true if this stack contains the specified object, @n
360 * @param[in] obj The object to locate
362 virtual bool Contains(const Type& obj) const
368 for (int i = 0; i <= __index; i++)
370 if (__pObjArray[i] == obj)
382 * Checks whether this stack contains all the elements in the specified @c collection.
386 * @return An error code
387 * @param[in] collection The collection to locate
388 * @param[out] out The boolean value that indicates if this stack contains all the elements in the specified @c collection
389 * @exception E_SUCCESS The method is successful.
390 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
391 * - The current state of the instance prohibits the execution of the specified operation.
392 * - The specified @c collection is modified during the operation of this method.
394 virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const
396 result r = E_SUCCESS;
398 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
399 IEnumeratorT< Type >* pEnum = pCol->GetEnumeratorN();
400 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
406 r = pEnum->MoveNext();
407 // enumerator has reached the end of collection
408 if (E_OUT_OF_RANGE == r)
414 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
416 r = pEnum->GetCurrent(temp);
417 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
419 if (false == Contains(temp))
441 * Checks whether the specified instance equals the current instance.
445 * @return @c true if the specified instance equals the current instance, @n
447 * @param[in] obj The object to compare with the current instance
448 * @remarks This method returns @c true only if the specified object is also an instance of the Stack class,
449 * both the stacks have the same size, and all the corresponding pairs of elements in the two stacks are equal. @n
450 * In other words, two stacks are equal if they contain the same elements in the same order.
452 virtual bool Equals(const Object& obj) const
456 const StackT< Type >* other = dynamic_cast< const StackT< Type >* >(&obj);
457 if (null == other) // obj is not a StackT<Type> instance
461 else if (other == this)
465 else if (__index != other->__index)
471 for (int i = 0; i <= __index; i++)
473 if (!(__pObjArray[i] == other->__pObjArray[i]))
486 * Gets the hash value of the current instance.
490 * @return The hash value of the current instance
491 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value.@n
492 * For better performance, the used hash function must generate a random distribution for all the inputs.
494 virtual int GetHashCode(void) const
497 for (int i = 0; i <= __index; i++)
499 if (&__pObjArray[i] != null)
501 hash += reinterpret_cast< int >(&__pObjArray[i]);
510 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
512 * @param[in] stack The other instance of StackT
514 StackT(const StackT< Type >& stack);
517 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
519 * @param[in] stack An instance of %StackT
521 StackT< Type >& operator =(const StackT< Type >& stack);
527 static const int DEFAULT_CAPACITY = 10;
529 friend class __StackEnumeratorT< Type >;
534 // @class __StackEnumeratorT
535 // @brief This class is an implementation of IEnumeratorT for %StackT.
538 template< class Type >
539 class __StackEnumeratorT
540 : public IEnumeratorT< Type >
545 * This is the constructor for this class.
549 * @param[in] stack A stack to enumerate
550 * @param[in] modCount The modification count to detect the change in the stack
552 __StackEnumeratorT(const StackT< Type >& stack, int modCount)
554 , __modCount(modCount)
560 * This is the destructor for this class.
564 virtual ~__StackEnumeratorT(void)
569 * Gets the current object in the stack.
573 * @return An error code
574 * @param[out] obj The current object
575 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
576 * - The current state of the instance prohibits the execution of the specified operation.
577 * - This enumerator is currently positioned before the first element or
578 * past the last element.
579 * - The stack is modified after this enumerator is created.
580 * @exception E_SUCCESS The method is successful.
582 result GetCurrent(Type& obj) const
584 TryReturn(__modCount == __stack.__modCount, E_INVALID_OPERATION,
585 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
586 TryReturn(((__position >= 0) && (__position <= __stack.__index)), E_INVALID_OPERATION,
587 "[%s] Current position is before the first element or past the last element.", GetErrorMessage(E_INVALID_OPERATION));
589 obj = __stack.__pObjArray[__position];
595 * Moves this enumerator to the next element of the stack. @n
596 * When this enumerator is first created or after a call to Reset(),
597 * the first call to %MoveNext() positions this enumerator to the first element in the stack.
601 * @return An error code
602 * @exception E_SUCCESS The method is successful.
603 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
604 * the stack is modified after this enumerator is created.
605 * @exception E_OUT_OF_RANGE The enumerator has passed the end of the stack.
608 result MoveNext(void)
610 TryReturn((__modCount == __stack.__modCount), E_INVALID_OPERATION,
611 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
613 result r = E_SUCCESS;
614 if (__position >= __stack.__index)
616 // Do not log the E_OUT_OF_RANGE, because it is normal or trivial in most cases.
628 * Positions this enumerator before the first element in the stack.
632 * @return An error code
633 * @exception E_SUCCESS The method is successful.
634 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
635 * the stack is modified after this enumerator is created.
639 TryReturn((__modCount == __stack.__modCount), E_INVALID_OPERATION,
640 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
648 const StackT< Type >& __stack;
652 }; // __StackEnumeratorT
654 }}} // Tizen::Base::Collection
656 #endif //_FBASE_COL_STACK_T_H_