inc/FBaseColQueue.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   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
   7 //
   8 // http://www.apache.org/licenses/LICENSE-2.0
   9 //
  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.
  15 //
  16
  17 /**
  18  * @file                FBaseColQueue.h
  19  * @brief               This is the header file for the %Queue class.
  20  *
  21  * This header file contains the declarations of the %Queue class.
  22  *
  23  */
  24 #ifndef _FBASE_COL_QUEUE_H_
  25 #define _FBASE_COL_QUEUE_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseTypes.h>
  29 #include <FBaseColICollection.h>
  30
  31 namespace Tizen { namespace Base { namespace Collection
  32 {
  33 /**
  34  * @class       Queue
  35  * @brief       This class represents a first-in-first-out collection of objects, that is, a queue.
  36  *
  37  * @since 2.0
  38  *
  39  * The %Queue class represents a first-in-first-out collection of objects, that is, a queue.
  40  *
  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>.
  42  *
  43  * The following example demonstrates how to use the %Queue class.
  44  *
  45  * @code
  46  *      #include <FBase.h>
  47  *
  48  *      using namespace Tizen::Base;
  49  *      using namespace Tizen::Base::Collection;
  50  *
  51  *      void
  52  *      MyClass::QueueSample(void)
  53  *      {
  54  *              Queue queue;
  55  *              queue.Construct(3);                                     // capacity = 3
  56  *
  57  *              queue.Enqueue(new String(L"First"));
  58  *              queue.Enqueue(new String(L"Second"));
  59  *              queue.Enqueue(new String(L"Third"));
  60  *
  61  *              // Reads the element at the beginning
  62  *              const Object* pObj = queue.Peek();              // pObj: "First", queue.GetCount(): 3
  63  *
  64  *              // Reads and removes the element at the beginning
  65  *              String* pStr = static_cast< String* > (queue.Dequeue());        // pStr: "First", queue.GetCount(): 2
  66  *
  67  *              delete pStr;     // Because the queue does not have the Ownership of this pStr after dequeueing
  68  *
  69  *              // Deallocates all objects
  70  *              queue.RemoveAll(true);
  71  *      }
  72  * @endcode
  73  */
  74 class _OSP_EXPORT_ Queue
  75         : public virtual ICollection
  76         , public Object
  77 {
  78 public:
  79         /**
  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.
  82          *
  83          * @since 2.0
  84          */
  85         Queue(void);
  86
  87         /**
  88          * This destructor overrides Tizen::Base::Object::~Object().
  89          *
  90          * @since 2.0
  91          */
  92         virtual ~Queue(void);
  93
  94         /**
  95          * Initializes an instance of %Queue with the specified capacity.
  96          *
  97          * @since 2.0
  98          *
  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.
 111          * @see                 Queue()
 112          */
 113         result Construct(int capacity = DEFAULT_CAPACITY);
 114
 115         /**
 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.
 118          *
 119          * @since 2.0
 120          *
 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.
 128          * @see                 Queue()
 129          */
 130         result Construct(const ICollection& collection);
 131
 132         /**
 133          * Removes the element at the beginning of this queue and returns it.
 134          *
 135          * @since 2.0
 136          *
 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*)
 145          */
 146         virtual Object* Dequeue(void);
 147
 148         /**
 149          * @if OSPDEPREC
 150          * Inserts an object at the end of this queue.
 151          *
 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).
 155          * @since 2.0
 156          *
 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.
 162          * @see                 Dequeue()
 163          * @endif
 164          */
 165         result Enqueue(const Object& obj)
 166         {
 167                 return Enqueue(const_cast< Object* >(&obj));
 168         }
 169
 170         /**
 171          * Inserts an object at the end of this queue.
 172          *
 173          * @since 2.0
 174          *
 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.
 180          * @see                 Dequeue()
 181          */
 182         virtual result Enqueue(Object* pObj);
 183
 184         /**
 185          * Gets the enumerator of this queue.
 186          *
 187          * @since 2.0
 188          *
 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.
 192          */
 193         virtual IEnumerator* GetEnumeratorN(void) const;
 194
 195         /**
 196          * Gets the element at the beginning of this queue without removing it.
 197          *
 198          * @since 2.0
 199          *
 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.
 207          */
 208         virtual const Object* Peek(void) const;
 209
 210         /**
 211          * Removes all the objects and their pointers from the collection, when the @c deallocate parameter is set to @c true.
 212          *
 213          * @since 2.0
 214          *
 215          * @param[in]   deallocate              Set to @c true to deallocate all objects, @n
 216          *                                                              else @c false
 217          * @remarks              This method can be called before deleting the collection.
 218          */
 219         virtual void RemoveAll(bool deallocate = false);
 220
 221         /**
 222          * Gets the number of objects currently stored in this queue.
 223          *
 224          * @since 2.0
 225          *
 226          * @return              The number of objects currently stored in this queue
 227          */
 228         virtual int GetCount(void) const;
 229
 230         /**
 231          * Checks whether this queue contains the specified object.
 232          *
 233          * @since 2.0
 234          *
 235          * @return              @c true if this queue contains the specified object, @n
 236          *                              else @c false
 237          * @param[in]   obj  The object to locate
 238          */
 239         virtual bool Contains(const Object& obj) const;
 240
 241         /**
 242          * @if OSPDEPREC
 243          * Checks whether this queue contains all the elements in the specified collection.
 244          *
 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).
 249          * @since 2.0
 250          *
 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
 254          *                                                                      else @c false
 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.
 259          * @endif
 260          */
 261         result ContainsAll(const ICollection& collection, bool& out) const
 262         {
 263                 out = ContainsAll(collection);
 264                 result r = GetLastResult();
 265                 return r;
 266         }
 267
 268         /**
 269          * Checks whether this queue contains all the elements in the specified collection.
 270          *
 271          * @since 2.0
 272          *
 273          * @return              @c true if this queue contains all the elements in the specified collection, @n
 274          *                              else @c false
 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.
 281          */
 282         virtual bool ContainsAll(const ICollection& collection) const;
 283
 284         /**
 285          * Compares the specified instance to the current instance for equality.
 286          *
 287          * @since 2.0
 288          *
 289          * @return              @c true if the specified instance equals the current instance, @n
 290          *                              else @c false
 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.
 295          */
 296         virtual bool Equals(const Object& obj) const;
 297
 298         /**
 299          * Gets the hash value of the current instance.
 300          *
 301          * @since 2.0
 302          *
 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.
 306          */
 307         virtual int GetHashCode(void) const;
 308
 309 private:
 310         //
 311         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 312         //
 313         // @param[in]   queue The specified instance of %Queue to initialize the current instance
 314         //
 315         Queue(const Queue& queue);
 316
 317         //
 318         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 319         //
 320         // @param[in]   queue An instance of %Queue
 321         //
 322         Queue& operator =(const Queue& queue);
 323
 324         int __capacity;
 325         int __head;
 326         int __tail;
 327         Object** __pObjArray;
 328         int __modCount;
 329         static const int DEFAULT_CAPACITY = 10;
 330
 331         friend class _QueueEnumerator;
 332         friend class _QueueImpl;
 333         class _QueueImpl* __pQueueImpl;
 334
 335 }; // Queue
 336
 337 }}} // Tizen::Collection
 338
 339 #endif // _FBASE_COL_QUEUE_H_