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           The specified input parameter is invalid, or
 104          *                                                                      the specified @c capacity is negative.
 105          * @remarks             If the number of elements added to the queue reaches the current capacity,
 106          *                              the capacity is automatically increased by memory reallocation.
 107          *                              Therefore, if the size of the queue can be estimated,
 108          *                              specifying the initial capacity eliminates the need to perform a number of
 109          *                              resizing operations while adding elements to the queue.
 110          * @see                 Queue()
 111          */
 112         result Construct(int capacity = DEFAULT_CAPACITY);
 113
 114         /**
 115          * Initializes an instance of %Queue with the elements of the given collection. @n
 116          * The capacity of the queue is the same as the number of elements copied.
 117          *
 118          * @since 2.0
 119          *
 120          * @return              An error code
 121          * @param[in]   collection                      The collection to copy elements from
 122          * @exception   E_SUCCESS                       The method is successful.
 123          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 124          *                                                                      the @c collection is modified during the operation of this method.
 125          * @remarks             This method performs a shallow copy. It copies just the pointer; not the element itself.
 126          * @see                 Queue()
 127          */
 128         result Construct(const ICollection& collection);
 129
 130         /**
 131          * Removes the element at the beginning of this queue and returns it.
 132          *
 133          * @since 2.0
 134          *
 135          * @return              The element at the beginning of this queue, @n
 136          *                              else @c null if this queue is empty
 137          * @exception   E_SUCCESS       The method is successful.
 138          * @exception   E_UNDERFLOW     The operation (arithmetic/casting/conversion) has caused an underflow, or
 139          *                                                      this queue is empty.
 140          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 141          * @see                 Enqueue(Object*)
 142          */
 143         virtual Object* Dequeue(void);
 144
 145         /**
 146          * @if OSPDEPREC
 147          * Inserts an object at the end of this queue.
 148          *
 149          * @brief               <i> [Deprecated] </i>
 150          * @deprecated  This method is deprecated because it has a problem of const reference argument.
 151          *                              Instead of using this method, use Enqueue(Object* pObj).
 152          * @since 2.0
 153          *
 154          * @return              An error code
 155          * @param[in]   obj                             The object to add to this queue
 156          * @exception   E_SUCCESS               The method is successful.
 157          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 158          * @remarks             This method performs a shallow copy. It inserts just the pointer; not the element itself.
 159          * @see                 Dequeue()
 160          * @endif
 161          */
 162         result Enqueue(const Object& obj)
 163         {
 164                 return Enqueue(const_cast< Object* >(&obj));
 165         }
 166
 167         /**
 168          * Inserts an object at the end of this queue.
 169          *
 170          * @since 2.0
 171          *
 172          * @return              An error code
 173          * @param[in]   pObj                            The pointer to object to add to this queue
 174          * @exception   E_SUCCESS                       The method is successful.
 175          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 176          * @remarks             This method performs a shallow copy. It inserts just the pointer; not the element itself.
 177          * @see                 Dequeue()
 178          */
 179         virtual result Enqueue(Object* pObj);
 180
 181         /**
 182          * Gets an enumerator of this queue.
 183          *
 184          * @since 2.0
 185          *
 186          * @return              An enumerator (an instance of the IEnumerator derived class) of this queue, @n
 187          *                              else @c null if an exception occurs
 188          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 189          * @see                 IEnumerator
 190          */
 191         virtual IEnumerator* GetEnumeratorN(void) const;
 192
 193         /**
 194          * Gets the element at the front of this queue without removing it.
 195          *
 196          * @since 2.0
 197          *
 198          * @return              The element at the beginning of this queue, @n
 199          *                              else @c null if this queue is empty
 200          * @exception   E_SUCCESS       The method is successful.
 201          * @exception   E_UNDERFLOW     The operation (arithmetic/casting/conversion) has caused an underflow, or
 202          *                                                      this queue is empty.
 203          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 204          */
 205         virtual const Object* Peek(void) const;
 206
 207         /**
 208          * Removes all objects and their pointers in collection, when the @c deallocate parameter is set to @c true.
 209          *
 210          * @since 2.0
 211          *
 212          * @param[in]   deallocate              Set to @c true to deallocate all objects, @n
 213          *                                                              else @c false
 214          * @remarks              This method can be called before deleting the collection.
 215          */
 216         virtual void RemoveAll(bool deallocate = false);
 217
 218         /**
 219          * Gets the number of objects currently stored in this queue.
 220          *
 221          * @since 2.0
 222          *
 223          * @return              The number of objects currently stored in this queue
 224          */
 225         virtual int GetCount(void) const;
 226
 227         /**
 228          * Checks whether this queue contains the specified object.
 229          *
 230          * @since 2.0
 231          *
 232          * @return              @c true if this queue contains the specified object, @n
 233          *                              else @c false
 234          * @param[in]   obj  The object to locate
 235          */
 236         virtual bool Contains(const Object& obj) const;
 237
 238         /**
 239          * @if OSPDEPREC
 240          * Checks whether this queue contains all the elements in the specified collection.
 241          *
 242          * @brief               <i> [Deprecated] </i>
 243          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 244          *                              The return type will be changed into boolean type and this method will return the result.
 245          *                              Instead of using this method, use bool ContainsAll(const ICollection& collection).
 246          * @since 2.0
 247          *
 248          * @return              An error code
 249          * @param[in]   collection      The collection to locate
 250          * @param[out]  out  Set to @c true if this queue contains all the elements in the specified collection, @n
 251          *                                       else @c false
 252          * @exception   E_SUCCESS                       The method is successful.
 253          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 254          *                                                                      the @c collection is modified during the operation of this method.
 255          * @endif
 256          */
 257         result ContainsAll(const ICollection& collection, bool& out) const
 258         {
 259                 out = ContainsAll(collection);
 260                 result r = GetLastResult();
 261                 return r;
 262         }
 263
 264         /**
 265          * Checks whether this queue contains all the elements in the specified collection.
 266          *
 267          * @since 2.0
 268          *
 269          * @return              @c true if this queue contains all the elements in the specified collection, @n
 270          *                              else @c false
 271          * @param[in]   collection                      The collection to locate
 272          * @exception   E_SUCCESS                       The method is successful.
 273          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 274          *                                                                      the @c collection is modified during the operation of this method.
 275          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 276          */
 277         virtual bool ContainsAll(const ICollection& collection) const;
 278
 279         /**
 280          * Compares the specified instance to the current instance for equality.
 281          *
 282          * @since 2.0
 283          *
 284          * @return              @c true if the specified instance equals the current instance, @n
 285          *                              else @c false
 286          * @param[in]   obj The object to compare with the current instance
 287          * @remarks             This method returns @c true if and only if the specified object is also an instance of %Queue class,
 288          *                              both queues have the same size, and all corresponding pairs of elements in the two queues are equal.
 289          *                              In other words, two queues are equal if they contain the same elements in the same order.
 290          */
 291         virtual bool Equals(const Object& obj) const;
 292
 293         /**
 294          * Gets the hash value of the current instance.
 295          *
 296          * @since 2.0
 297          *
 298          * @return      The hash value of the current instance
 299          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
 300          *                      the used hash function must generate a random distribution for all inputs.
 301          */
 302         virtual int GetHashCode(void) const;
 303
 304 private:
 305         //
 306         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 307         //
 308         // @param[in]   queue The specified instance of %Queue to initialize the current instance
 309         //
 310         Queue(const Queue& queue);
 311
 312         //
 313         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 314         //
 315         // @param[in]   queue An instance of %Queue
 316         //
 317         Queue& operator =(const Queue& queue);
 318
 319         int __capacity;
 320         int __head;
 321         int __tail;
 322         Object** __pObjArray;
 323         int __modCount;
 324         static const int DEFAULT_CAPACITY = 10;
 325
 326         friend class _QueueEnumerator;
 327         friend class _QueueImpl;
 328         class _QueueImpl* __pQueueImpl;
 329
 330 }; // Queue
 331
 332 }}} // Tizen::Collection
 333
 334 #endif // _FBASE_COL_QUEUE_H_