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>
32 namespace Tizen { namespace Base { namespace Collection
35 template< class Type > class __StackEnumeratorT;
39 * @brief This class represents a template-based stack (a last-in-first-out collection of objects).
43 * The %StackT class represents a template-based stack (a last-in-first-out collection of objects).
45 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/queue_stack.htm">Stack and Queue</a>.
47 * The following example demonstrates how to use the %StackT class.
52 * using namespace Tizen::Base;
53 * using namespace Tizen::Base::Collection;
56 * MyClass::StackTSample(void)
58 * StackT< String > stack;
61 * String str1(L"First");
62 * String str2(L"Second");
63 * String str3(L"Third");
69 * // Reads the element at the top
71 * stack.Peek(temp); // temp: "Third", stack.GetCount(): 3
73 * // Reads and removes the element at the top
74 * stack.Pop(temp); // temp: "Third", stack.GetCount(): 2
78 template< class Type >
80 : public virtual ICollectionT< Type >
85 * The object is not fully constructed after this constructor is called. For full construction, @n
86 * the Construct() method must be called right after calling this constructor.
99 * This destructor overrides Tizen::Base::Object::~Object().
103 virtual ~StackT(void)
110 * Initializes this instance of %StackT with the specified @c capacity.
114 * @return An error code
115 * @param[in] capacity The number of elements @n
116 * The default capacity is @c 10.
117 * @exception E_SUCCESS The method is successful.
118 * @exception E_INVALID_ARG The specified input parameter is invalid, or
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 The current state of the instance prohibits the execution of the specified operation, or
145 * the specified @c collection is modified during the operation of this method.
148 result Construct(const ICollectionT< Type >& collection)
150 result r = E_SUCCESS;
152 IEnumeratorT< Type >* pEnum = null;
153 if (collection.GetCount() > 0)
155 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
156 pEnum = pCol->GetEnumeratorN();
157 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
163 r = pEnum->MoveNext();
164 // enumerator is reached to the end of collection
165 if (E_OUT_OF_RANGE == r)
170 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
172 r = pEnum->GetCurrent(temp);
173 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
176 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
197 * Gets an enumerator of this stack.
201 * @return An enumerator (an instance of the IEnumeratorT derived class) of this stack, @n
202 * else @c null if an exception occurs
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_OUT_OF_MEMORY The memory is insufficient.
205 * @remarks The specific error code can be accessed using the GetLastResult() method.
206 * @see Tizen::Base::Collection::IEnumeratorT
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 The operation (arithmetic/casting/conversion) has caused an underflow, or
233 * this stack is empty.
235 virtual result Peek(Type& obj) const
242 obj = __pObjArray[__index];
248 * Pops the element from the beginning of this stack.
252 * @return An error code
253 * @param[out] obj The element at the beginning of this stack
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
256 * this stack is empty.
259 virtual result Pop(Type& obj)
268 obj = __pObjArray[__index];
276 * Pushes an object at the top of this stack.
280 * @return An error code
281 * @param[in] obj The object to add to this stack
282 * @exception E_SUCCESS The method is successful.
283 * @exception E_OUT_OF_MEMORY The memory is insufficient.
286 virtual result Push(const Type& obj)
289 if (null == __pObjArray)
291 __pObjArray = new Type[DEFAULT_CAPACITY];
292 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
294 __capacity = DEFAULT_CAPACITY;
296 else if ((__index + 1) >= __capacity)
298 Type* pArrayTemp = new Type[__capacity + DEFAULT_CAPACITY];
299 TryReturn(pArrayTemp != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
301 for (int i = 0; i <= __index; i++)
303 pArrayTemp[i] = __pObjArray[i];
306 delete[] __pObjArray;
308 __pObjArray = pArrayTemp;
309 __capacity += DEFAULT_CAPACITY;
315 __pObjArray[++__index] = obj;
321 * Removes all elements in this stack.
325 virtual void RemoveAll(void)
327 if (__pObjArray != null)
329 delete[] __pObjArray;
340 * Gets the number of objects currently stored in this stack.
344 * @return The number of objects currently stored in this stack
346 virtual int GetCount(void) const
352 * Checks whether this stack contains the specified object.
356 * @return @c true if this stack contains the specified object, @n
358 * @param[in] obj The object to locate
360 virtual bool Contains(const Type& obj) const
366 for (int i = 0; i <= __index; i++)
368 if (__pObjArray[i] == obj)
380 * Checks whether this stack contains all of the elements in the specified @c collection.
384 * @return An error code
385 * @param[in] collection The collection to locate
386 * @param[out] out Set to @c true if this stack contains all of the elements in the specified @c collection, @n
388 * @exception E_SUCCESS The method is successful.
389 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
390 * the specified @c collection is modified during the operation of this method.
392 virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const
394 result r = E_SUCCESS;
396 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
397 IEnumeratorT< Type >* pEnum = pCol->GetEnumeratorN();
398 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
404 r = pEnum->MoveNext();
405 // enumerator has reached the end of collection
406 if (E_OUT_OF_RANGE == r)
412 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
414 r = pEnum->GetCurrent(temp);
415 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
417 if (false == Contains(temp))
439 * Checks whether the specified instance equals the current instance.
443 * @return @c true if the specified instance equals the current instance, @n
445 * @param[in] obj The object to compare with the current instance
446 * @remarks This method returns @c true only if the specified object is also an instance of the Stack class,
447 * both stacks have the same size, and all the corresponding pairs of elements in the two stacks are equal.
448 * In other words, two stacks are equal if they contain the same elements in the same order.
450 virtual bool Equals(const Object& obj) const
454 const StackT< Type >* other = dynamic_cast< const StackT< Type >* >(&obj);
455 if (null == other) // obj is not a StackT<Type> instance
459 else if (other == this)
463 else if (__index != other->__index)
469 for (int i = 0; i <= __index; i++)
471 if (!(__pObjArray[i] == other->__pObjArray[i]))
484 * Gets the hash value of the current instance.
488 * @return The hash value of the current instance
489 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
490 * the used hash function must generate a random distribution for all inputs.
492 virtual int GetHashCode(void) const
495 for (int i = 0; i <= __index; i++)
497 if (&__pObjArray[i] != null)
499 hash += reinterpret_cast< int >(&__pObjArray[i]);
508 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
510 * @param[in] stack The other instance of StackT
512 StackT(const StackT< Type >& stack);
515 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
517 * @param[in] stack An instance of %StackT
519 StackT< Type >& operator =(const StackT< Type >& stack);
525 static const int DEFAULT_CAPACITY = 10;
527 friend class __StackEnumeratorT< Type >;
532 // @class __StackEnumeratorT
533 // @brief This class is an implementation of IEnumeratorT for %StackT.
536 template< class Type >
537 class __StackEnumeratorT
538 : public IEnumeratorT< Type >
543 * This is the constructor for this class.
547 * @param[in] stack A stack to enumerate
548 * @param[in] modCount The modification count to detect the change in the stack
550 __StackEnumeratorT(const StackT< Type >& stack, int modCount)
552 , __modCount(modCount)
558 * This is the destructor for this class.
562 virtual ~__StackEnumeratorT(void)
567 * Gets the current object in the stack.
571 * @return An error code
572 * @param[out] obj The current object
573 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
574 * - The current state of the instance prohibits the execution of the specified operation. @n
575 * - This enumerator is currently positioned before the first element or
576 * past the last element. @n
577 * - The stack is modified after this enumerator is created.
578 * @exception E_SUCCESS The method is successful.
580 result GetCurrent(Type& obj) const
582 TryReturn(__modCount == __stack.__modCount, E_INVALID_OPERATION,
583 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
584 TryReturn(((__position >= 0) && (__position <= __stack.__index)), E_INVALID_OPERATION,
585 "[%s] Current position is before the first element or past the last element.", GetErrorMessage(E_INVALID_OPERATION));
587 obj = __stack.__pObjArray[__position];
593 * Moves this enumerator to the next element of the stack. @n
594 * When this enumerator is first created or after a call to Reset(),
595 * the first call to %MoveNext() positions this enumerator to the first element in the stack.
599 * @return An error code
600 * @exception E_SUCCESS The method is successful.
601 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
602 * the stack is modified after this enumerator is created.
603 * @exception E_OUT_OF_RANGE The enumerator has passed the end of the stack.
606 result MoveNext(void)
608 TryReturn((__modCount == __stack.__modCount), E_INVALID_OPERATION,
609 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
611 result r = E_SUCCESS;
612 if (__position >= __stack.__index)
614 // Do not log the E_OUT_OF_RANGE, because it is normal or trivial in most cases.
626 * Positions this enumerator before the first element in the stack.
630 * @return An error code
631 * @exception E_SUCCESS The method is successful.
632 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
633 * the stack is modified after this enumerator is created.
637 TryReturn((__modCount == __stack.__modCount), E_INVALID_OPERATION,
638 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
646 const StackT< Type >& __stack;
650 }; // __StackEnumeratorT
652 }}} // Tizen::Base::Collection
654 #endif //_FBASE_COL_STACK_T_H_