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
  32 namespace Tizen { namespace Base { namespace Collection
  33 {
  34 /**
  35  * @class       Queue
  36  * @brief       This class represents a first-in-first-out collection of objects, that is, a queue.
  37  *
  38  * @since 2.0
  39  *
  40  * The %Queue class represents a first-in-first-out collection of objects, that is, a queue.
  41  *
  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>.
  43  *
  44  * The following example demonstrates how to use the %Queue class.
  45  *
  46  * @code
  47  *      #include <FBase.h>
  48  *
  49  *      using namespace Tizen::Base;
  50  *      using namespace Tizen::Base::Collection;
  51  *
  52  *      void
  53  *      MyClass::QueueSample(void)
  54  *      {
  55  *              Queue queue;
  56  *              queue.Construct(3);                                     // capacity = 3
  57  *
  58  *              queue.Enqueue(new String(L"First"));
  59  *              queue.Enqueue(new String(L"Second"));
  60  *              queue.Enqueue(new String(L"Third"));
  61  *
  62  *              // Reads the element at the beginning
  63  *              const Object* pObj = queue.Peek();              // pObj: "First", queue.GetCount(): 3
  64  *
  65  *              // Reads and removes the element at the beginning
  66  *              String* pStr = static_cast< String* > (queue.Dequeue());        // pStr: "First", queue.GetCount(): 2
  67  *
  68  *              delete pStr;     // Because the queue does not have the Ownership of this pStr after dequeueing
  69  *
  70  *              // Deallocates all objects
  71  *              queue.RemoveAll(true);
  72  *      }
  73  * @endcode
  74  */
  75 class _OSP_EXPORT_ Queue
  76         : public virtual ICollection
  77         , public Object
  78 {
  79 public:
  80         /**
  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.
  83          *
  84          * @since 2.0
  85          */
  86         Queue(void);
  87
  88         /**
  89          * This destructor overrides Tizen::Base::Object::~Object().
  90          *
  91          * @since 2.0
  92          */
  93         virtual ~Queue(void);
  94
  95         /**
  96          * Initializes an instance of %Queue with the specified capacity.
  97          *
  98          * @since 2.0
  99          *
 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.
 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     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.
 127          * @see                 Queue()
 128          */
 129         result Construct(const ICollection& collection);
 130
 131         /**
 132          * Removes the element at the beginning of this queue and returns it.
 133          *
 134          * @since 2.0
 135          *
 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.
 142          * @see                         Enqueue(Object*)
 143          */
 144         virtual Object* Dequeue(void);
 145
 146         /**
 147          * @if OSPDEPREC
 148          * Inserts an object at the end of this queue.
 149          *
 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).
 153          * @since 2.0
 154          *
 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.
 160          * @see                         Dequeue()
 161          * @endif
 162          */
 163         result Enqueue(const Object& obj)
 164         {
 165                 return Enqueue(const_cast< Object* >(&obj));
 166         }
 167
 168         /**
 169          * Inserts an object at the end of this queue.
 170          *
 171          * @since 2.0
 172          *
 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.
 178          * @see                         Dequeue()
 179          */
 180         virtual result Enqueue(Object* pObj);
 181
 182         /**
 183          * Gets an enumerator of this queue.
 184          *
 185          * @since 2.0
 186          *
 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.
 190          * @see                         IEnumerator
 191          */
 192         virtual IEnumerator* GetEnumeratorN(void) const;
 193
 194         /**
 195          * Gets the element at the front of this queue without removing it.
 196          *
 197          * @since 2.0
 198          *
 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.
 205          */
 206         virtual const Object* Peek(void) const;
 207
 208         /**
 209          * Removes all objects and their pointers in collection, when the @c deallocate parameter is set to @c true.
 210          *
 211          * @since 2.0
 212          *
 213          * @param[in]   deallocate              Set to @c true to deallocate all objects, @n
 214          *                                                              else @c false
 215          * @remarks              This method can be called before deleting the collection.
 216          */
 217         virtual void RemoveAll(bool deallocate = false);
 218
 219         /**
 220          * Gets the number of objects currently stored in this queue.
 221          *
 222          * @since 2.0
 223          *
 224          * @return              The number of objects currently stored in this queue
 225          */
 226         virtual int GetCount(void) const;
 227
 228         /**
 229          * Checks whether this queue contains the specified object.
 230          *
 231          * @since 2.0
 232          *
 233          * @return              @c true if this queue contains the specified object, @n
 234          *                              else @c false
 235          * @param[in]   obj  The object to locate
 236          */
 237         virtual bool Contains(const Object& obj) const;
 238
 239         /**
 240          * @if OSPDEPREC
 241          * Checks whether this queue contains all the elements in the specified collection.
 242          *
 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).
 247          * @since 2.0
 248          *
 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
 252          *                                       else @c false
 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.
 256          * @endif
 257          */
 258         result ContainsAll(const ICollection& collection, bool& out) const
 259         {
 260                 out = ContainsAll(collection);
 261                 result r = GetLastResult();
 262                 return r;
 263         }
 264
 265         /**
 266          * Checks whether this queue contains all the elements in the specified collection.
 267          *
 268          * @since 2.0
 269          *
 270          * @return              @c true if this queue contains all the elements in the specified collection, @n
 271          *                                      else @c false
 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.
 277          */
 278         virtual bool ContainsAll(const ICollection& collection) const;
 279
 280         /**
 281          * Compares the specified instance to the current instance for equality.
 282          *
 283          * @since 2.0
 284          *
 285          * @return              @c true if the specified instance equals the current instance, @n
 286          *                              else @c false
 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.
 291          */
 292         virtual bool Equals(const Object& obj) const;
 293
 294         /**
 295          * Gets the hash value of the current instance.
 296          *
 297          * @since 2.0
 298          *
 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.
 302          */
 303         virtual int GetHashCode(void) const;
 304
 305 private:
 306         //
 307         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 308         //
 309         // @param[in]   queue The specified instance of %Queue to initialize the current instance
 310         //
 311         Queue(const Queue& queue);
 312
 313         //
 314         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 315         //
 316         // @param[in]   queue An instance of %Queue
 317         //
 318         Queue& operator =(const Queue& queue);
 319
 320         int __capacity;
 321         int __head;
 322         int __tail;
 323         Object** __pObjArray;
 324         int __modCount;
 325         static const int DEFAULT_CAPACITY = 10;
 326
 327         friend class _QueueEnumerator;
 328         friend class _QueueImpl;
 329         class _QueueImpl* __pQueueImpl;
 330
 331 }; // Queue
 332
 333 }}} // Tizen::Collection
 334
 335 #endif // _FBASE_COL_QUEUE_H_