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>
31 namespace Tizen { namespace Base { namespace Collection
34 template< class Type > class __QueueEnumeratorT;
38 * @brief This class represents a template-based queue (a first-in-first-out collection of objects).
42 * The %QueueT class represents a template-based queue (a first-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 %QueueT class.
51 * using namespace Tizen::Base;
52 * using namespace Tizen::Base::Collection;
55 * MyClass::QueueTSample(void)
57 * QueueT< String > queue;
60 * String str1(L"First");
61 * String str2(L"Second");
62 * String str3(L"Third");
64 * queue.Enqueue(str1);
65 * queue.Enqueue(str2);
66 * queue.Enqueue(str3);
68 * // Reads the element at the beginning
70 * queue.Peek(temp); // temp: "First", queue.GetCount(): 3
72 * // Reads and removes the element at the beginning
73 * queue.Dequeue(temp); // temp: "First", queue.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.
99 * This destructor overrides Tizen::Base::Object::~Object().
103 virtual ~QueueT(void)
110 * Initializes this instance of %QueueT with the specified capacity.
114 * @return An error code
115 * @param[in] capacity The number of elements in the queue @n
116 * The default capacity is @c 10.
117 * @exception E_SUCCESS The method is successful.
118 * @exception E_OUT_OF_MEMORY The memory is insufficient.
119 * @exception E_INVALID_ARG Either of the following conditions has occurred:
120 * - The specified input parameter is invalid.
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 Either of the following conditions has occurred:
148 * - The current state of the instance prohibits the execution of the specified operation.
149 * - The specified @c collection is modified during the operation of this method.
152 result Construct(const ICollectionT< Type >& collection)
154 result r = E_SUCCESS;
156 IEnumeratorT< Type >* pEnum = null;
157 if (collection.GetCount() > 0)
159 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
160 pEnum = pCol->GetEnumeratorN();
161 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
166 r = pEnum->MoveNext();
168 if (E_OUT_OF_RANGE == r)
173 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
175 r = pEnum->GetCurrent(temp);
176 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
179 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
200 * Reads and removes the element at the beginning of this queue.
204 * @return An error code
205 * @param[out] obj The element at the beginning of this queue
206 * @exception E_SUCCESS The method is successful.
207 * @exception E_UNDERFLOW Either of the following conditions has occurred:
208 * - The operation (arithmetic/casting/conversion) has caused an underflow.
209 * - The queue is empty.
212 virtual result Dequeue(Type& obj)
214 if (__head <= __tail)
218 int index = (__tail) % __capacity;
219 obj = __pObjArray[index];
227 * Inserts an object at the end of this queue.
231 * @return An error code
232 * @param[in] obj The object to add to this queue
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_OUT_OF_MEMORY The memory is insufficient.
237 virtual result Enqueue(const Type& obj)
239 if (null == __pObjArray)
241 __pObjArray = new Type[DEFAULT_CAPACITY];
242 TryReturn(__pObjArray != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
243 __capacity = DEFAULT_CAPACITY;
245 else if ((__head - __tail) >= __capacity)
247 Type* pArrayTemp = new Type[__capacity + DEFAULT_CAPACITY];
248 TryReturn(pArrayTemp != null, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
250 for (int i = 0, j = __tail; i < __capacity; i++, j++)
252 pArrayTemp[i] = __pObjArray[j % __capacity];
255 delete[] __pObjArray;
256 __pObjArray = pArrayTemp;
259 __capacity += DEFAULT_CAPACITY;
263 __pObjArray[__head % __capacity] = obj;
270 * Removes all the elements from this queue.
274 virtual void RemoveAll(void)
276 if (__pObjArray != null)
278 delete[] __pObjArray;
290 * Gets the enumerator of this queue.
294 * @return The enumerator (an instance of the IEnumeratorT derived class) of this queue, @n
295 * else @c null if an exception occurs
296 * @exception E_SUCCESS The method is successful.
297 * @exception E_OUT_OF_MEMORY The memory is insufficient.
298 * @remarks The specific error code can be accessed using the GetLastResult() method.
300 virtual IEnumeratorT< Type >* GetEnumeratorN(void) const
304 result r = E_SUCCESS;
306 __QueueEnumeratorT< Type >* pEnum = new __QueueEnumeratorT< Type >(*this, __modCount);
307 TryCatch(pEnum != null, r = E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
317 * Reads the element at the beginning of this queue without removing it.
321 * @return An error code
322 * @param[out] obj The element at the beginning of this queue
323 * @exception E_SUCCESS The method is successful.
324 * @exception E_UNDERFLOW Either of the following conditions has occurred:
325 * - The operation (arithmetic/casting/conversion) has caused an underflow.
326 * - The queue is empty.
328 virtual result Peek(Type& obj) const
330 if (__head <= __tail)
335 obj = __pObjArray[__tail % __capacity];
341 * Gets the number of objects currently stored in this queue.
345 * @return The number of objects currently stored in this queue
347 virtual int GetCount(void) const
349 return __head - __tail;
353 * Checks whether this queue contains the specified object.
357 * @return @c true if this queue contains the specified object, @n
359 * @param[in] obj The object to locate
361 virtual bool Contains(const Type& obj) const
364 for (int i = 0; i < GetCount(); i++)
366 if (__pObjArray[(__tail + i) % __capacity] == obj)
377 * Checks whether this queue contains all of the elements in the specified collection.
381 * @return An error code
382 * @param[in] collection The collection to locate
383 * @param[out] out Set to @c true if this queue contains all of the elements in the specified collection, @n
385 * @exception E_SUCCESS The method is successful.
386 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
387 * - The current state of the instance prohibits the execution of the specified operation.
388 * - The specified @c collection is modified during the operation of this method.
389 * @exception E_OUT_OF_MEMORY The memory is insufficient.
391 virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const
393 result r = E_SUCCESS;
395 ICollectionT< Type >* pCol = const_cast< ICollectionT< Type >* >(&collection);
396 IEnumeratorT< Type >* pEnum = pCol->GetEnumeratorN();
397 TryCatch(pEnum != null, r = GetLastResult(), "[%s] Propagating.", GetErrorMessage(GetLastResult()));
402 r = pEnum->MoveNext();
404 if (E_OUT_OF_RANGE == r)
410 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
412 r = pEnum->GetCurrent(temp);
413 TryCatch(r == E_SUCCESS, , "[%s] Propagating.", GetErrorMessage(r));
415 if (false == Contains(temp))
437 * Compares the specified instance to the current instance for equality.
441 * @return @c true if the specified instance equals the current instance, @n
443 * @param[in] obj The object to compare with the current instance
444 * @remarks This method returns @c true if and only if the specified object is also an instance of the %QueueT class,
445 * both queues have the same size, and all the corresponding pairs of elements in the two queues are equal. @n
446 * In other words, two queues are equal if they contain the same elements in the same order.
448 virtual bool Equals(const Object& obj) const
452 const QueueT< Type >* other = dynamic_cast< const QueueT< Type >* >(&obj);
457 else if (other == this)
461 else if (GetCount() != other->GetCount())
467 for (int i = 0; i < GetCount(); i++)
469 if (!(__pObjArray[(__tail + i) % __capacity] == other->__pObjArray[(other->__tail + i) % other->__capacity]))
481 * Gets the hash value of the current instance.
485 * @return The hash value of the current instance
486 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. @n
487 * For better performance, the used hash function must generate a random distribution for all the inputs.
489 virtual int GetHashCode(void) const
492 int count = GetCount();
493 for (int i = 0; i < count; i++)
495 if (&(__pObjArray[(__tail + i) % __capacity]) != null)
497 hash += reinterpret_cast< int >(&(__pObjArray[(__tail + i) % __capacity]));
505 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
507 * @param[in] queue The specified instance of %QueueT to initialize the current instance
509 QueueT(const QueueT< Type >& queue);
512 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
514 * @param[in] queue An instance of %QueueT
516 QueueT< Type >& operator =(const QueueT< Type >& queue);
523 static const int DEFAULT_CAPACITY = 10;
525 friend class __QueueEnumeratorT< Type >;
530 // @class __QueueEnumeratorT
531 // @brief This class is an implementation of IEnumeratorT for %QueueT.
534 template< class Type >
535 class __QueueEnumeratorT
536 : public IEnumeratorT< Type >
541 * Initializes this instance of __QueueEnumeratorT with the specified parameters.
545 * @param[in] queue The queue to enumerate
546 * @param[in] modeCount The modification count to detect the change in the queue
548 __QueueEnumeratorT(const QueueT< Type >& queue, int modeCount)
550 , __modCount(modeCount)
556 * This is the destructor for this class.
560 virtual ~__QueueEnumeratorT(void)
565 * Gets the current object in the queue.
569 * @return An error code
570 * @param[out] obj The current object
571 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
572 * - The current state of the instance prohibits the execution of the specified operation. @n
573 * - This enumerator is currently positioned before the first element or
574 * past the last element.
575 * - The queue is modified after this enumerator is created.
576 * @exception E_SUCCESS The method is successful.
578 result GetCurrent(Type& obj) const
580 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
581 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
582 TryReturn((__position >= __queue.__tail) && (__position < __queue.__head), E_INVALID_OPERATION,
583 "[%s] Current position is before the first element or past the last element.", GetErrorMessage(E_INVALID_OPERATION));
585 obj = __queue.__pObjArray[__position % __queue.__capacity];
591 * Moves this enumerator to the next element of the queue. @n
592 * When this enumerator is first created or after the call to Reset(),
593 * the first call to MoveNext() positions this enumerator to the first element in the queue.
597 * @return An error code
598 * @exception E_SUCCESS The method is successful.
599 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
600 * - The current state of the instance prohibits the execution of the specified operation.
601 * - The queue is modified after this enumerator is created.
602 * @exception E_OUT_OF_RANGE The enumerator has passed the end of the queue.
605 result MoveNext(void)
607 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
608 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
610 if ((__position + 1) >= __queue.__head)
612 return E_OUT_OF_RANGE;
616 if (__position == -1)
618 __position = __queue.__tail;
630 * Positions this enumerator before the first element in the queue.
634 * @return An error code
635 * @exception E_SUCCESS The method is successful.
636 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
637 * - The current state of the instance prohibits the execution of the specified operation.
638 * - The queue is modified after this enumerator is created.
642 TryReturn((__modCount == __queue.__modCount), E_INVALID_OPERATION,
643 "[%s] The source collection is modified after the creation of this enumerator.", GetErrorMessage(E_INVALID_OPERATION));
651 const QueueT< Type >& __queue;
655 }; // __QueueEnumeratorT
657 }}} // Tizen::Base::Collection
659 #endif //_FBASE_COL_QUEUE_T_H_