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 FBaseColQueueT.h
19 * @brief This is the header file for the %QueueT class.
21 * This header file contains the declarations of the %QueueT class.
24 #ifndef _FBASE_COL_QUEUE_T_H_
25 #define _FBASE_COL_QUEUE_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 __QueueEnumeratorT;
39 * @brief This represents a template-based queue (a first-in-first-out collection of objects).
43 * The %QueueT class represents a template-based queue (a first-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 %QueueT class.
52 * using namespace Tizen::Base;
53 * using namespace Tizen::Base::Collection;
56 * MyClass::QueueTSample(void)
58 * QueueT< String > queue;
61 * String str1(L"First");
62 * String str2(L"Second");
63 * String str3(L"Third");
65 * queue.Enqueue(str1);
66 * queue.Enqueue(str2);
67 * queue.Enqueue(str3);
69 * // Reads the element at the beginning
71 * queue.Peek(temp); // temp: "First", queue.GetCount(): 3
73 * // Reads and removes the element at the beginning
74 * queue.Dequeue(temp); // temp: "First", queue.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.
100 * This destructor overrides Tizen::Base::Object::~Object().
104 virtual ~QueueT(void)
111 * Initializes this instance of %QueueT with the specified capacity.
115 * @return An error code
116 * @param[in] capacity The number of elements in the queue @n
117 * The default capacity is @c 10.
118 * @exception E_SUCCESS The method is successful.
119 * @exception E_OUT_OF_MEMORY The memory is insufficient.
120 * @exception E_INVALID_ARG The specified input parameter is invalid, or
121 * the specified @c capacity is negative.
123 result Construct(int capacity = DEFAULT_CAPACITY)
125 TryReturn(capacity >= 0, E_INVALID_ARG, "[%s] The capacity(%d) MUST be greater than or equal to 0.", GetErrorMessage(E_INVALID_ARG), capacity);
129 __pObjArray = new Type[capacity];
130 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
132 __capacity = capacity;
138 * Initializes this instance of %QueueT that contains the elements of the specified @c collection. @n
139 * The capacity of the queue is the same as the number of elements copied.
143 * @return An error code
144 * @param[in] collection The collection to copy the elements from
145 * @exception E_SUCCESS The method is successful.
146 * @exception E_OUT_OF_MEMORY The memory is insufficient.
147 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
148 * the @c collection is modified during the operation of this method.
151 result Construct(const ICollectionT< Type >& collection)
153 result r = E_SUCCESS;
155 IEnumeratorT< Type >* pEnum = null;
156 if (collection.GetCount() > 0)
158 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
159 pEnum = pCol->GetEnumeratorN();
160 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
165 r = pEnum->MoveNext();
167 if (E_OUT_OF_RANGE == r)
172 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
174 r = pEnum->GetCurrent(temp);
175 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
178 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
199 * Reads and removes the element at the beginning of this queue.
203 * @return An error code
204 * @param[out] obj The element at the beginning of this queue
205 * @exception E_SUCCESS The method is successful.
206 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
207 * this queue is empty.
210 virtual result Dequeue(Type& obj)
212 if (__head <= __tail)
216 int index = (__tail) % __capacity;
217 obj = __pObjArray[index];
225 * Inserts an object at the end of this queue.
229 * @return An error code
230 * @param[in] obj The object to add to this queue
231 * @exception E_SUCCESS The method is successful.
232 * @exception E_OUT_OF_MEMORY The memory is insufficient.
235 virtual result Enqueue(const Type& obj)
237 if (null == __pObjArray)
239 __pObjArray = new Type[DEFAULT_CAPACITY];
240 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
241 __capacity = DEFAULT_CAPACITY;
243 else if ((__head - __tail) >= __capacity)
245 Type* pArrayTemp = new Type[__capacity + DEFAULT_CAPACITY];
246 TryReturn(pArrayTemp != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
248 for (int i = 0, j = __tail; i < __capacity; i++, j++)
250 pArrayTemp[i] = __pObjArray[j % __capacity];
253 delete[] __pObjArray;
254 __pObjArray = pArrayTemp;
257 __capacity += DEFAULT_CAPACITY;
261 __pObjArray[__head % __capacity] = obj;
268 * Removes all the elements in this queue.
272 virtual void RemoveAll(void)
274 if (__pObjArray != null)
276 delete[] __pObjArray;
288 * Gets an enumerator of this queue.
292 * @return An enumerator (an instance of the IEnumeratorT derived class) of this queue, @n
293 * else @c null if an exception occurs
294 * @exception E_SUCCESS The method is successful.
295 * @exception E_OUT_OF_MEMORY The memory is insufficient.
296 * @remarks The specific error code can be accessed using the GetLastResult() method.
297 * @see Tizen::Base::Collection::IEnumeratorT
299 virtual IEnumeratorT< Type >* GetEnumeratorN(void) const
303 result r = E_SUCCESS;
305 __QueueEnumeratorT< Type >* pEnum = new __QueueEnumeratorT< Type >(*this, __modCount);
306 TryCatch(pEnum != null, r = E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
316 * Reads the element at the beginning of this queue without removing it.
320 * @return An error code
321 * @param[out] obj The element at the beginning of this queue
322 * @exception E_SUCCESS The method is successful.
323 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
324 * this queue is empty.
326 virtual result Peek(Type& obj) const
328 if (__head <= __tail)
333 obj = __pObjArray[__tail % __capacity];
339 * Gets the number of objects currently stored in this queue.
343 * @return The number of objects currently stored in this queue
345 virtual int GetCount(void) const
347 return __head - __tail;
351 * Checks whether this queue contains the specified object.
355 * @return @c true if this queue contains the specified object, @n
357 * @param[in] obj The object to locate
359 virtual bool Contains(const Type& obj) const
362 for (int i = 0; i < GetCount(); i++)
364 if (__pObjArray[(__tail + i) % __capacity] == obj)
375 * Checks whether this queue contains all of the elements in the specified collection.
379 * @return An error code
380 * @param[in] collection The collection to locate
381 * @param[out] out Set to @c true if this queue contains all of the elements in the specified collection, @n
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
385 * the specified @c collection is modified during the operation of this method.
386 * @exception E_OUT_OF_MEMORY The memory is insufficient.
388 virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const
390 result r = E_SUCCESS;
392 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
393 IEnumeratorT< Type >* pEnum = pCol->GetEnumeratorN();
394 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
399 r = pEnum->MoveNext();
401 if (E_OUT_OF_RANGE == r)
407 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
409 r = pEnum->GetCurrent(temp);
410 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
412 if (false == Contains(temp))
434 * Compares the specified instance to the current instance for equality.
438 * @return @c true if the specified instance equals the current instance, @n
440 * @param[in] obj The object to compare with the current instance
441 * @remarks This method returns @c true if and only if the specified object is also an instance of %QueueT class,
442 * both queues have the same size, and all corresponding pairs of elements in the two queues are equal.
443 * In other words, two queues are equal if they contain the same elements in the same order.
445 virtual bool Equals(const Object& obj) const
449 const QueueT< Type >* other = dynamic_cast< const QueueT< Type >* >(&obj);
454 else if (other == this)
458 else if (GetCount() != other->GetCount())
464 for (int i = 0; i < GetCount(); i++)
466 if (!(__pObjArray[(__tail + i) % __capacity] == other->__pObjArray[(other->__tail + i) % other->__capacity]))
478 * Gets the hash value of the current instance.
482 * @return The hash value of the current instance
483 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
484 * the used hash function must generate a random distribution for all inputs.
486 virtual int GetHashCode(void) const
489 int count = GetCount();
490 for (int i = 0; i < count; i++)
492 if (&(__pObjArray[(__tail + i) % __capacity]) != null)
494 hash += reinterpret_cast< int >(&(__pObjArray[(__tail + i) % __capacity]));
502 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
504 * @param[in] queue The specified instance of %QueueT to initialize the current instance
506 QueueT(const QueueT< Type >& queue);
509 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
511 * @param[in] queue An instance of %QueueT
513 QueueT< Type >& operator =(const QueueT< Type >& queue);
520 static const int DEFAULT_CAPACITY = 10;
522 friend class __QueueEnumeratorT< Type >;
527 // @class __QueueEnumeratorT
528 // @brief This class is an implementation of IEnumeratorT for %QueueT.
531 template< class Type >
532 class __QueueEnumeratorT
533 : public IEnumeratorT< Type >
538 * Initializes this instance of __QueueEnumeratorT with the specified parameters.
542 * @param[in] queue A queue to enumerate
543 * @param[in] modeCount The modification count to detect the change in the queue
545 __QueueEnumeratorT(const QueueT< Type >& queue, int modeCount)
547 , __modCount(modeCount)
553 * This is the destructor for this class.
557 virtual ~__QueueEnumeratorT(void)
562 * Gets the current object in the queue.
566 * @return An error code
567 * @param[out] obj The current object
568 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
569 * - The current state of the instance prohibits the execution of the specified operation. @n
570 * - This enumerator is currently positioned before the first element or
571 * past the last element. @n
572 * - The queue is modified after this enumerator is created.
573 * @exception E_SUCCESS The method is successful.
575 result GetCurrent(Type& obj) const
577 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
578 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
579 TryReturn((__position >= __queue.__tail) && (__position < __queue.__head), E_INVALID_OPERATION,
580 "[%s] Current position is before the first element or past the last element.", GetErrorMessage(E_INVALID_OPERATION));
582 obj = __queue.__pObjArray[__position % __queue.__capacity];
588 * Moves this enumerator to the next element of the queue. @n
589 * When this enumerator is first created or after the call to Reset(),
590 * the first call to MoveNext() positions this enumerator to the first element in the queue.
594 * @return An error code
595 * @exception E_SUCCESS The method is successful.
596 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
597 * the queue is modified after this enumerator is created.
598 * @exception E_OUT_OF_RANGE The enumerator has passed the end of the queue.
601 result MoveNext(void)
603 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
604 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
606 if ((__position + 1) >= __queue.__head)
608 return E_OUT_OF_RANGE;
612 if (__position == -1)
614 __position = __queue.__tail;
626 * Positions this enumerator before the first element in the queue.
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 queue is modified after this enumerator is created.
637 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
638 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
646 const QueueT< Type >& __queue;
650 }; // __QueueEnumeratorT
652 }}} // Tizen::Base::Collection
654 #endif //_FBASE_COL_QUEUE_T_H_