inc/FBaseColQueue.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseColQueue.h
  20  * @brief               This is the header file for the %Queue class.
  21  *
  22  * This header file contains the declarations of the %Queue class.
  23  *
  24  */
  25 #ifndef _FBASE_COL_QUEUE_H_
  26 #define _FBASE_COL_QUEUE_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseColICollection.h>
  31
  32
  33 namespace Tizen { namespace Base { namespace Collection
  34 {
  35 /**
  36  * @class       Queue
  37  * @brief       This class represents a first-in-first-out collection of objects, that is, a queue.
  38  *
  39  * @since 2.0
  40  *
  41  * The %Queue class represents a first-in-first-out collection of objects, that is, a queue.
  42  *
  43  * 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  *
  45  * The following example demonstrates how to use the %Queue class.
  46  *
  47  * @code
  48  *      #include <FBase.h>
  49  *
  50  *      using namespace Tizen::Base;
  51  *      using namespace Tizen::Base::Collection;
  52  *
  53  *      void
  54  *      MyClass::QueueSample(void)
  55  *      {
  56  *              Queue queue;
  57  *              queue.Construct(3);                                     // capacity = 3
  58  *
  59  *              queue.Enqueue(new String(L"First"));
  60  *              queue.Enqueue(new String(L"Second"));
  61  *              queue.Enqueue(new String(L"Third"));
  62  *
  63  *              // Reads the element at the beginning
  64  *              const Object* pObj = queue.Peek();              // pObj: "First", queue.GetCount(): 3
  65  *
  66  *              // Reads and removes the element at the beginning
  67  *              String* pStr = static_cast<String*> (queue.Dequeue());  // pStr: "First", queue.GetCount(): 2
  68  *
  69  *              delete pStr;     // Because the queue does not have the Ownership of this pStr after dequeueing
  70  *
  71  *              // Deallocates all objects
  72  *              queue.RemoveAll(true);
  73  *      }
  74  * @endcode
  75  */
  76 class _OSP_EXPORT_ Queue
  77         : public virtual ICollection
  78         , public Object
  79 {
  80 public:
  81         /**
  82          * The object is not fully constructed after this constructor is called. For full construction, @n
  83          * the Construct() method must be called right after calling this constructor.
  84          *
  85          * @since 2.0
  86          */
  87         Queue(void);
  88
  89         /**
  90          * This destructor overrides Tizen::Base::Object::~Object().
  91          *
  92          * @since 2.0
  93          */
  94         virtual ~Queue(void);
  95
  96         /**
  97          * Initializes an instance of %Queue with the specified capacity.
  98          *
  99          * @since 2.0
 100          *
 101          * @return              An error code
 102          * @param[in]   capacity                        The number of elements in the queue @n
 103          *                                                                      The default capacity is @c 10.
 104          * @exception   E_SUCCESS                       The method is successful.
 105          * @exception   E_INVALID_ARG   The specified input parameter is invalid, or
 106          *                                                                the specified @c capacity is negative.
 107          * @remarks             If the number of elements added to the queue reaches the current capacity,
 108          *                              the capacity is automatically increased by memory reallocation.
 109          *                              Therefore, if the size of the queue can be estimated,
 110          *                              specifying the initial capacity eliminates the need to perform a number of
 111          *                              resizing operations while adding elements to the queue.
 112          * @see                 Queue()
 113          */
 114         result Construct(int capacity = DEFAULT_CAPACITY);
 115
 116         /**
 117          * Initializes an instance of %Queue with the elements of the given collection. @n
 118          * The capacity of the queue is the same as the number of elements copied.
 119          *
 120          * @since 2.0
 121          *
 122          * @return              An error code
 123          * @param[in]   collection The collection to copy elements from
 124          * @exception   E_SUCCESS                       The method is successful.
 125          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 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; 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     The operation (arithmetic/casting/conversion) has caused an underflow, or
 141          *                                                      this queue is empty.
 142          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 143          * @see                         Enqueue()
 144          */
 145         virtual Object* Dequeue(void);
 146
 147         /**
 148          * @if OSPDEPREC
 149          * Inserts an object at the end of this queue.
 150          *
 151          * @brief               <i> [Deprecated] </i>
 152          * @deprecated  This method is deprecated because it has a problem of const reference argument.
 153          *                              Instead of using this method, use Enqueue(Object* pObj).
 154          * @since 2.0
 155          *
 156          * @return              An error code
 157          * @param[in]   obj     The object to add to this queue
 158          * @exception   E_SUCCESS               The method is successful.
 159          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 160          * @remarks             This method performs a shallow copy. It inserts just the pointer; not the element itself.
 161          * @see                         Dequeue()
 162          * @endif
 163          */
 164         result Enqueue(const Object& obj)
 165         {
 166                 return Enqueue(const_cast< Object* >(&obj));
 167         }
 168
 169         /**
 170          * Inserts an object at the end of this queue.
 171          *
 172          * @since 2.0
 173          *
 174          * @return              An error code
 175          * @param[in]   pObj            The pointer to object to add to this queue
 176          * @exception   E_SUCCESS               The method is successful.
 177          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 178          * @remarks             This method performs a shallow copy. It inserts just the pointer; not the element itself.
 179          * @see                         Dequeue()
 180          */
 181         virtual result Enqueue(Object* pObj);
 182
 183         /**
 184          * Gets an enumerator of this queue.
 185          *
 186          * @since 2.0
 187          *
 188          * @return              An enumerator (an instance of the IEnumerator derived class) of this queue, @n
 189          *                              else @c null if an exception occurs
 190          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 191          * @see                         IEnumerator
 192          */
 193         virtual IEnumerator* GetEnumeratorN(void) const;
 194
 195         /**
 196          * Gets the element at the front 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     The operation (arithmetic/casting/conversion) has caused an underflow, or
 204          *                                                      this queue is empty.
 205          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 206          */
 207         virtual const Object* Peek(void) const;
 208
 209         /**
 210          * Removes all objects and their pointers in collection, when the @c deallocate parameter is set to @c true.
 211          *
 212          * @since 2.0
 213          *
 214          * @param[in]   deallocate              Set to @c true to deallocate all objects, @n
 215          *                                                              else @c false
 216          * @remarks              This method can be called before deleting the collection.
 217          */
 218         virtual void RemoveAll(bool deallocate = false);
 219
 220         /**
 221          * Gets the number of objects currently stored in this queue.
 222          *
 223          * @since 2.0
 224          *
 225          * @return              The number of objects currently stored in this queue
 226          */
 227         virtual int GetCount(void) const;
 228
 229         /**
 230          * Checks whether this queue contains the specified object.
 231          *
 232          * @since 2.0
 233          *
 234          * @return              @c true if this queue contains the specified object, @n
 235          *                              else @c false
 236          * @param[in]   obj  The object to locate
 237          */
 238         virtual bool Contains(const Object& obj) const;
 239
 240         /**
 241          * @if OSPDEPREC
 242          * Checks whether this queue contains all the elements in the specified collection.
 243          *
 244          * @brief               <i> [Deprecated] </i>
 245          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 246          *                              The return type will be changed into boolean type and this method will return the result.
 247          *                              Instead of using this method, use bool ContainsAll(const ICollection& collection).
 248          * @since 2.0
 249          *
 250          * @return              An error code
 251          * @param[in]   collection      The collection to locate
 252          * @param[out]  out  Set to @c true if this queue contains all the elements in the specified collection, @n
 253          *                                       else @c false
 254          * @exception   E_SUCCESS                       The method is successful.
 255          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 256          *                                                                      the @c collection is modified during the operation of this method.
 257          * @endif
 258          */
 259         result ContainsAll(const ICollection& collection, bool& out) const
 260         {
 261                 out = ContainsAll(collection);
 262                 result r = GetLastResult();
 263                 return r;
 264         }
 265
 266         /**
 267          * Checks whether this queue contains all the elements in the specified collection.
 268          *
 269          * @since 2.0
 270          *
 271          * @return              @c true if this queue contains all the elements in the specified collection, @n
 272          *                                      else @c false
 273          * @param[in]   collection      The collection to locate
 274          * @exception   E_SUCCESS                       The method is successful.
 275          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 276          *                                                                      the @c collection is modified during the operation of this method.
 277          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 278          */
 279         virtual bool ContainsAll(const ICollection& collection) const;
 280
 281         /**
 282          * Compares the specified instance to the current instance for equality.
 283          *
 284          * @since 2.0
 285          *
 286          * @return              @c true if the specified instance equals the current instance, @n
 287          *                              else @c false
 288          * @param[in]   obj The object to compare with the current instance
 289          * @remarks             This method returns @c true if and only if the specified object is also an instance of %Queue class,
 290          *                              both queues have the same size, and all corresponding pairs of elements in the two queues are equal.
 291          *                              In other words, two queues are equal if they contain the same elements in the same order.
 292          */
 293         virtual bool Equals(const Object& obj) const;
 294
 295         /**
 296          * Gets the hash value of the current instance.
 297          *
 298          * @since 2.0
 299          *
 300          * @return      The hash value of the current instance
 301          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
 302          *                      the used hash function must generate a random distribution for all inputs.
 303          */
 304         virtual int GetHashCode(void) const;
 305
 306 private:
 307         //
 308         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 309         //
 310         // @param[in]   queue The specified instance of %Queue to initialize the current instance
 311         //
 312         Queue(const Queue& queue);
 313
 314         //
 315         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 316         //
 317         // @param[in]   queue An instance of %Queue
 318         //
 319         Queue& operator =(const Queue& queue);
 320
 321         int __capacity;
 322         int __head;
 323         int __tail;
 324         Object** __pObjArray;
 325         int __modCount;
 326         static const int DEFAULT_CAPACITY = 10;
 327
 328         friend class _QueueEnumerator;
 329         friend class _QueueImpl;
 330         class _QueueImpl* __pQueueImpl;
 331
 332 }; // Queue
 333
 334 }}} // Tizen::Collection
 335
 336 #endif // _FBASE_COL_QUEUE_H_