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>
32 namespace Tizen { namespace Base { namespace Collection
36 * @brief This class represents a first-in-first-out collection of objects, that is, a queue.
40 * The %Queue class represents a first-in-first-out collection of objects, that is, a queue.
42 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/queue_stack.htm">Stack and Queue</a>.
44 * The following example demonstrates how to use the %Queue class.
49 * using namespace Tizen::Base;
50 * using namespace Tizen::Base::Collection;
53 * MyClass::QueueSample(void)
56 * queue.Construct(3); // capacity = 3
58 * queue.Enqueue(new String(L"First"));
59 * queue.Enqueue(new String(L"Second"));
60 * queue.Enqueue(new String(L"Third"));
62 * // Reads the element at the beginning
63 * const Object* pObj = queue.Peek(); // pObj: "First", queue.GetCount(): 3
65 * // Reads and removes the element at the beginning
66 * String* pStr = static_cast< String* > (queue.Dequeue()); // pStr: "First", queue.GetCount(): 2
68 * delete pStr; // Because the queue does not have the Ownership of this pStr after dequeueing
70 * // Deallocates all objects
71 * queue.RemoveAll(true);
75 class _OSP_EXPORT_ Queue
76 : public virtual ICollection
81 * The object is not fully constructed after this constructor is called. For full construction, @n
82 * the Construct() method must be called right after calling this constructor.
89 * This destructor overrides Tizen::Base::Object::~Object().
96 * Initializes an instance of %Queue with the specified capacity.
100 * @return An error code
101 * @param[in] capacity The number of elements in the queue @n
102 * The default capacity is @c 10.
103 * @exception E_SUCCESS The method is successful.
104 * @exception E_INVALID_ARG The specified input parameter is invalid, or
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.
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 The current state of the instance prohibits the execution of the specified operation, or
125 * the @c collection is modified during the operation of this method.
126 * @remarks This method performs a shallow copy. It copies just the pointer; not the element itself.
129 result Construct(const ICollection& collection);
132 * Removes the element at the beginning of this queue and returns it.
136 * @return The element at the beginning of this queue, @n
137 * else @c null if this queue is empty
138 * @exception E_SUCCESS The method is successful.
139 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
140 * this queue is empty.
141 * @remarks The specific error code can be accessed using the GetLastResult() method.
144 virtual Object* Dequeue(void);
148 * Inserts an object at the end of this queue.
150 * @brief <i> [Deprecated] </i>
151 * @deprecated This method is deprecated because it has a problem of const reference argument.
152 * Instead of using this method, use Enqueue(Object* pObj).
155 * @return An error code
156 * @param[in] obj The object to add to this queue
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_OUT_OF_MEMORY The memory is insufficient.
159 * @remarks This method performs a shallow copy. It inserts just the pointer; not the element itself.
163 result Enqueue(const Object& obj)
165 return Enqueue(const_cast< Object* >(&obj));
169 * Inserts an object at the end of this queue.
173 * @return An error code
174 * @param[in] pObj The pointer to object to add to this queue
175 * @exception E_SUCCESS The method is successful.
176 * @exception E_INVALID_ARG The specified input parameter is invalid.
177 * @remarks This method performs a shallow copy. It inserts just the pointer; not the element itself.
180 virtual result Enqueue(Object* pObj);
183 * Gets an enumerator of this queue.
187 * @return An enumerator (an instance of the IEnumerator derived class) of this queue, @n
188 * else @c null if an exception occurs
189 * @remarks The specific error code can be accessed using the GetLastResult() method.
192 virtual IEnumerator* GetEnumeratorN(void) const;
195 * Gets the element at the front of this queue without removing it.
199 * @return The element at the beginning of this queue, @n
200 * else @c null if this queue is empty
201 * @exception E_SUCCESS The method is successful.
202 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
203 * this queue is empty.
204 * @remarks The specific error code can be accessed using the GetLastResult() method.
206 virtual const Object* Peek(void) const;
209 * Removes all objects and their pointers in collection, when the @c deallocate parameter is set to @c true.
213 * @param[in] deallocate Set to @c true to deallocate all objects, @n
215 * @remarks This method can be called before deleting the collection.
217 virtual void RemoveAll(bool deallocate = false);
220 * Gets the number of objects currently stored in this queue.
224 * @return The number of objects currently stored in this queue
226 virtual int GetCount(void) const;
229 * Checks whether this queue contains the specified object.
233 * @return @c true if this queue contains the specified object, @n
235 * @param[in] obj The object to locate
237 virtual bool Contains(const Object& obj) const;
241 * Checks whether this queue contains all the elements in the specified collection.
243 * @brief <i> [Deprecated] </i>
244 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
245 * The return type will be changed into boolean type and this method will return the result.
246 * Instead of using this method, use bool ContainsAll(const ICollection& collection).
249 * @return An error code
250 * @param[in] collection The collection to locate
251 * @param[out] out Set to @c true if this queue contains all the elements in the specified collection, @n
253 * @exception E_SUCCESS The method is successful.
254 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
255 * the @c collection is modified during the operation of this method.
258 result ContainsAll(const ICollection& collection, bool& out) const
260 out = ContainsAll(collection);
261 result r = GetLastResult();
266 * Checks whether this queue contains all the elements in the specified collection.
270 * @return @c true if this queue contains all the elements in the specified collection, @n
272 * @param[in] collection The collection to locate
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
275 * the @c collection is modified during the operation of this method.
276 * @remarks The specific error code can be accessed using the GetLastResult() method.
278 virtual bool ContainsAll(const ICollection& collection) const;
281 * Compares the specified instance to the current instance for equality.
285 * @return @c true if the specified instance equals the current instance, @n
287 * @param[in] obj The object to compare with the current instance
288 * @remarks This method returns @c true if and only if the specified object is also an instance of %Queue class,
289 * both queues have the same size, and all corresponding pairs of elements in the two queues are equal.
290 * In other words, two queues are equal if they contain the same elements in the same order.
292 virtual bool Equals(const Object& obj) const;
295 * Gets the hash value of the current instance.
299 * @return The hash value of the current instance
300 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
301 * the used hash function must generate a random distribution for all inputs.
303 virtual int GetHashCode(void) const;
307 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
309 // @param[in] queue The specified instance of %Queue to initialize the current instance
311 Queue(const Queue& queue);
314 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
316 // @param[in] queue An instance of %Queue
318 Queue& operator =(const Queue& queue);
323 Object** __pObjArray;
325 static const int DEFAULT_CAPACITY = 10;
327 friend class _QueueEnumerator;
328 friend class _QueueImpl;
329 class _QueueImpl* __pQueueImpl;
333 }}} // Tizen::Collection
335 #endif // _FBASE_COL_QUEUE_H_