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 FBaseColQueue.h
19 * @brief This is the header file for the %Queue class.
21 * This header file contains the declarations of the %Queue class.
24 #ifndef _FBASE_COL_QUEUE_H_
25 #define _FBASE_COL_QUEUE_H_
27 #include <FBaseObject.h>
28 #include <FBaseTypes.h>
29 #include <FBaseColICollection.h>
31 namespace Tizen { namespace Base { namespace Collection
35 * @brief This class represents a first-in-first-out collection of objects, that is, a queue.
39 * The %Queue class represents a first-in-first-out collection of objects, that is, a queue.
41 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/queue_stack.htm">Stack and Queue</a>.
43 * The following example demonstrates how to use the %Queue class.
48 * using namespace Tizen::Base;
49 * using namespace Tizen::Base::Collection;
52 * MyClass::QueueSample(void)
55 * queue.Construct(3); // capacity = 3
57 * queue.Enqueue(new String(L"First"));
58 * queue.Enqueue(new String(L"Second"));
59 * queue.Enqueue(new String(L"Third"));
61 * // Reads the element at the beginning
62 * const Object* pObj = queue.Peek(); // pObj: "First", queue.GetCount(): 3
64 * // Reads and removes the element at the beginning
65 * String* pStr = static_cast< String* > (queue.Dequeue()); // pStr: "First", queue.GetCount(): 2
67 * delete pStr; // Because the queue does not have the Ownership of this pStr after dequeueing
69 * // Deallocates all objects
70 * queue.RemoveAll(true);
74 class _OSP_EXPORT_ Queue
75 : public virtual ICollection
80 * The object is not fully constructed after this constructor is called. For full construction, @n
81 * the Construct() method must be called right after calling this constructor.
88 * This destructor overrides Tizen::Base::Object::~Object().
95 * Initializes an instance of %Queue with the specified capacity.
99 * @return An error code
100 * @param[in] capacity The number of elements in the queue @n
101 * The default capacity is @c 10.
102 * @exception E_SUCCESS The method is successful.
103 * @exception E_INVALID_ARG Either of the following conditions has occurred:
104 * - The specified input parameter is invalid.
105 * - The specified @c capacity is negative.
106 * @remarks If the number of elements added to the queue reaches the current capacity,
107 * the capacity is automatically increased by memory reallocation. @n
108 * Therefore, if the size of the queue can be estimated,
109 * specifying the initial capacity eliminates the need to perform a number of
110 * resizing operations while adding elements to the queue.
113 result Construct(int capacity = DEFAULT_CAPACITY);
116 * Initializes an instance of %Queue with the elements of the given collection. @n
117 * The capacity of the queue is the same as the number of elements copied.
121 * @return An error code
122 * @param[in] collection The collection to copy elements from
123 * @exception E_SUCCESS The method is successful.
124 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
125 * - The current state of the instance prohibits the execution of the specified operation.
126 * - The @c collection is modified during the operation of this method.
127 * @remarks This method performs a shallow copy. It copies just the pointer and not the element itself.
130 result Construct(const ICollection& collection);
133 * Removes the element at the beginning of this queue and returns it.
137 * @return The element at the beginning of this queue, @n
138 * else @c null if this queue is empty
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_UNDERFLOW Either of the following conditions has occurred:
141 * - The operation (arithmetic/casting/conversion) has caused an underflow.
142 * - The queue is empty.
143 * @remarks The specific error code can be accessed using the GetLastResult() method.
144 * @see Enqueue(Object*)
146 virtual Object* Dequeue(void);
150 * Inserts an object at the end of this queue.
152 * @brief <i> [Deprecated] </i>
153 * @deprecated This method is deprecated because it has a problem of constant reference argument.
154 * Instead of using this method, use Enqueue(Object* pObj).
157 * @return An error code
158 * @param[in] obj The object to add to this queue
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_OUT_OF_MEMORY The memory is insufficient.
161 * @remarks This method performs a shallow copy. It inserts just the pointer and not the element itself.
165 result Enqueue(const Object& obj)
167 return Enqueue(const_cast< Object* >(&obj));
171 * Inserts an object at the end of this queue.
175 * @return An error code
176 * @param[in] pObj A pointer to the object to add to this queue
177 * @exception E_SUCCESS The method is successful.
178 * @exception E_INVALID_ARG The specified input parameter is invalid.
179 * @remarks This method performs a shallow copy. It inserts just the pointer and not the element itself.
182 virtual result Enqueue(Object* pObj);
185 * Gets the enumerator of this queue.
189 * @return The enumerator (an instance of the IEnumerator derived class) of this queue, @n
190 * else @c null if an exception occurs
191 * @remarks The specific error code can be accessed using the GetLastResult() method.
193 virtual IEnumerator* GetEnumeratorN(void) const;
196 * Gets the element at the beginning of this queue without removing it.
200 * @return The element at the beginning of this queue, @n
201 * else @c null if this queue is empty
202 * @exception E_SUCCESS The method is successful.
203 * @exception E_UNDERFLOW Either of the following conditions has occurred:
204 * - The operation (arithmetic/casting/conversion) has caused an underflow.
205 * - The queue is empty.
206 * @remarks The specific error code can be accessed using the GetLastResult() method.
208 virtual const Object* Peek(void) const;
211 * Removes all the objects and their pointers from the collection, when the @c deallocate parameter is set to @c true.
215 * @param[in] deallocate Set to @c true to deallocate all objects, @n
217 * @remarks This method can be called before deleting the collection.
219 virtual void RemoveAll(bool deallocate = false);
222 * Gets the number of objects currently stored in this queue.
226 * @return The number of objects currently stored in this queue
228 virtual int GetCount(void) const;
231 * Checks whether this queue contains the specified object.
235 * @return @c true if this queue contains the specified object, @n
237 * @param[in] obj The object to locate
239 virtual bool Contains(const Object& obj) const;
243 * Checks whether this queue contains all the elements in the specified collection.
245 * @brief <i> [Deprecated] </i>
246 * @deprecated This method is deprecated because it transfers the result of the comparison in an out-parameter form.
247 * The return type is changed to boolean and this method returns the result.
248 * Instead of using this method, use bool ContainsAll(const ICollection& collection).
251 * @return An error code
252 * @param[in] collection The collection to locate
253 * @param[out] out Set to @c true if this queue contains all the elements in the specified collection, @n
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
257 * - The current state of the instance prohibits the execution of the specified operation.
258 * - The @c collection is modified during the operation of this method.
261 result ContainsAll(const ICollection& collection, bool& out) const
263 out = ContainsAll(collection);
264 result r = GetLastResult();
269 * Checks whether this queue contains all the elements in the specified collection.
273 * @return @c true if this queue contains all the elements in the specified collection, @n
275 * @param[in] collection The collection to locate
276 * @exception E_SUCCESS The method is successful.
277 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
278 * - The current state of the instance prohibits the execution of the specified operation.
279 * - The @c collection is modified during the operation of this method.
280 * @remarks The specific error code can be accessed using the GetLastResult() method.
282 virtual bool ContainsAll(const ICollection& collection) const;
285 * Compares the specified instance to the current instance for equality.
289 * @return @c true if the specified instance equals the current instance, @n
291 * @param[in] obj The object to compare with the current instance
292 * @remarks This method returns @c true if and only if the specified object is also an instance of the %Queue class,
293 * both queues have the same size, and all the corresponding pairs of elements in the two queues are equal. @n
294 * In other words, two queues are equal if they contain the same elements in the same order.
296 virtual bool Equals(const Object& obj) const;
299 * Gets the hash value of the current instance.
303 * @return The hash value of the current instance
304 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. @n
305 * For better performance, the used hash function must generate a random distribution for all the inputs.
307 virtual int GetHashCode(void) const;
311 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
313 // @param[in] queue The specified instance of %Queue to initialize the current instance
315 Queue(const Queue& queue);
318 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
320 // @param[in] queue An instance of %Queue
322 Queue& operator =(const Queue& queue);
327 Object** __pObjArray;
329 static const int DEFAULT_CAPACITY = 10;
331 friend class _QueueEnumerator;
332 friend class _QueueImpl;
333 class _QueueImpl* __pQueueImpl;
337 }}} // Tizen::Collection
339 #endif // _FBASE_COL_QUEUE_H_