inc/FBaseColStack.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                FBaseColStack.h
  19  * @brief               This is the header file for the %Stack class.
  20  *
  21  * This header file contains the declarations of the %Stack class.
  22  *
  23  */
  24 #ifndef _FBASE_COL_STACK_H_
  25 #define _FBASE_COL_STACK_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 /**
  35  * @class       Stack
  36  * @brief       This class represents a simple last-in-first-out collection of objects, that is, a stack.
  37  *
  38  * @since 2.0
  39  *
  40  * The %Stack class represents a simple last-in-first-out collection of objects, that is, a stack.
  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 %Stack 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::StackSample(void)
  54  *      {
  55  *              Stack stack;
  56  *              stack.Construct(3);                     // capacity = 3
  57  *
  58  *              stack.Push(new String(L"First"));
  59  *              stack.Push(new String(L"Second"));
  60  *              stack.Push(new String(L"Third"));
  61  *
  62  *              // Reads the element at the top
  63  *              const Object* pObj = stack.Peek();                              // pObj: "Third", stack.GetCount(): 3
  64  *
  65  *              // Reads and removes the element at the top
  66  *              String* pStr = static_cast< String* > (stack.Pop());    // pStr: "Third", stack.GetCount(): 2
  67  *
  68  *              delete pStr;    // Because the stack does not have the ownership of this pStr after popping
  69  *
  70  *              // Deallocates all objects
  71  *              stack.RemoveAll(true);
  72  *      }
  73  * @endcode
  74  */
  75 class _OSP_EXPORT_ Stack
  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         Stack(void);
  87
  88
  89         /**
  90          * This destructor overrides Tizen::Base::Object::~Object().
  91          *
  92          * @since 2.0
  93          */
  94         virtual ~Stack(void);
  95
  96
  97         /**
  98          * Initializes this instance of %Stack with the specified capacity.
  99          *
 100          * @since 2.0
 101          *
 102          * @return              An error code
 103          * @param[in]   capacity                        The number of elements @n
 104          *                                                                      The default capacity is @c 10.
 105          * @exception   E_SUCCESS                       The method is successful.
 106          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 107          *                                                                      - The specified input parameter is invalid.
 108          *                                                                      - The specified @c capacity is negative.
 109          * @remarks     If the number of elements added to the stack reaches the current capacity,
 110          *                              the capacity is automatically increased by memory reallocation. @n
 111          *                              Therefore, if the size of the stack can be estimated,
 112          *                              specifying the initial capacity eliminates the need to perform a number of
 113          *                              resizing operations while adding elements to the stack.
 114          * @see                 Stack()
 115          */
 116         result Construct(int capacity = DEFAULT_CAPACITY);
 117
 118         /**
 119          * Initializes this instance of %Stack by copying the elements of the specified collection. @n
 120          * The capacity of the stack is the same as the number of elements copied.
 121          *
 122          * @since 2.0
 123          *
 124          * @return              An error code
 125          * @param[in]   collection                      The collection to copy elements from
 126          * @exception   E_SUCCESS                       The method is successful.
 127          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 128          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 129          *                                                                      - The specified @c collection is modified during the operation of this method.
 130          * @remarks     This method performs a shallow copy. It copies just the pointer and not the element itself.
 131          * @see                 Stack()
 132          */
 133         result Construct(const ICollection& collection);
 134
 135         /**
 136          * Gets the enumerator of this stack.
 137          *
 138          * @since 2.0
 139          *
 140          * @return              The enumerator (an instance of the IEnumerator derived class) of this stack, @n
 141          *                              else @c null if an exception occurs
 142          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 143          */
 144         virtual IEnumerator* GetEnumeratorN(void) const;
 145
 146         /**
 147          * Gets the element at the top of this stack without removing it.
 148          *
 149          * @since 2.0
 150          *
 151          * @return              The element at the top of this stack, @n
 152          *                              else @c null if this stack is empty
 153          * @exception   E_SUCCESS       The method is successful.
 154          * @exception   E_UNDERFLOW     Either of the following conditions has occurred:
 155          *                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 156          *                                                      - The stack is empty.
 157          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 158          */
 159         virtual const Object* Peek(void) const;
 160
 161         /**
 162          * Pops the element from the top of this stack.
 163          *
 164          * @since 2.0
 165          *
 166          * @return              The element at the top of this stack, @n
 167          *                              else @c null if this stack is empty
 168          * @exception   E_SUCCESS       The method is successful.
 169          * @exception   E_UNDERFLOW     Either of the following conditions has occurred:
 170          *                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 171          *                                                      - The stack is empty.
 172          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 173          * @see                 Push(Object*)
 174          */
 175         virtual Object* Pop(void);
 176
 177         /**
 178          * @if OSPDEPREC
 179          * Pushes an object to the top of this stack.
 180          *
 181          * @brief               <i> [Deprecated] </i>
 182          * @deprecated  This method is deprecated because it has a problem of constant reference argument.
 183          *                              Instead of using this method, use Push(Object* pObj).
 184          * @since 2.0
 185          *
 186          * @return              An error code
 187          * @param[in]   obj                             The object to add to this stack
 188          * @exception   E_SUCCESS               The method is successful.
 189          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 190          * @remarks             This method performs a shallow copy. It inserts just the pointer and not the element itself.
 191          * @see                 Pop()
 192          * @endif
 193          */
 194         result Push(const Object& obj)
 195         {
 196                 return Push(const_cast< Object* >(&obj));
 197         }
 198
 199         /**
 200          * Pushes an object to the top of this stack.
 201          *
 202          * @since 2.0
 203          *
 204          * @return              An error code
 205          * @param[in]   pObj                    A pointer to the object to add to this stack
 206          * @exception   E_SUCCESS               The method is successful.
 207          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 208          * @remarks             This method performs a shallow copy. It inserts just the pointer and not the element itself.
 209          * @see                 Pop()
 210          */
 211         virtual result Push(Object* pObj);
 212
 213         /**
 214          * Removes all the objects and their pointers from the collection, when the @c deallocate parameter is set to @c true. @n
 215          * This method can be called before deleting the objects in a collection.
 216          *
 217          * @since 2.0
 218          *
 219          * @param[in]   deallocate              Set to @c true to deallocate all objects, @n
 220          *                                                              else @c false
 221          */
 222         virtual void RemoveAll(bool deallocate = false);
 223
 224         /**
 225          * Gets the number of objects currently stored in this stack.
 226          *
 227          * @since 2.0
 228          *
 229          * @return              The number of objects currently stored in this stack
 230          */
 231         virtual int GetCount(void) const;
 232
 233         /**
 234          * Checks whether this stack contains the specified object.
 235          *
 236          * @since 2.0
 237          *
 238          * @return              @c true if this stack contains the specified object, @n
 239          *                              else @c false
 240          * @param[in]   obj  The object to locate
 241          */
 242         virtual bool Contains(const Object& obj) const;
 243
 244         /**
 245          * @if OSPDEPREC
 246          * Checks whether this stack contains all of the elements in the specified collection.
 247          *
 248          * @brief               <i> [Deprecated] </i>
 249          * @deprecated  This method is deprecated because it transfers the result of the comparison in an out-parameter form.
 250          *                              The return type is changed to boolean and this method returns the result.
 251          *                              Instead of using this method, use bool Contains(const ICollection& collection).
 252          * @since 2.0
 253          *
 254          * @return              An error code
 255          * @param[in]   collection                      The collection to locate
 256          * @param[out]  out                                     Set to @c true if this stack contains all the elements in the specified collection, @n
 257          *                                                                      else @c false
 258          * @exception   E_SUCCESS                       The method is successful.
 259          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 260          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 261          *                                                                      - The specified @c collection is modified during the operation of this method.
 262          * @endif
 263          */
 264         result ContainsAll(const ICollection& collection, bool& out) const
 265         {
 266                 out = ContainsAll(collection);
 267                 result r = GetLastResult();
 268                 return r;
 269         }
 270
 271         /**
 272          * Checks whether this stack contains all the elements in the specified collection.
 273          *
 274          * @since 2.0
 275          *
 276          * @return              @c true if this stack contains all the elements in the specified collection, @n
 277          *                              else @c false
 278          * @param[in]   collection                      The collection to locate
 279          * @exception   E_SUCCESS                       The method is successful.
 280          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 281          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 282          *                                                                      - The specified @c collection is modified during the operation of this method.
 283          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 284          */
 285         virtual bool ContainsAll(const ICollection& collection) const;
 286
 287         /**
 288          * Checks whether the specified instance equals the current instance.
 289          *
 290          * @since 2.0
 291          *
 292          * @return              @c true if the specified instance equals the current instance, @n
 293          *                              else @c false
 294          * @param[in]   obj             The object to compare with the current instance
 295          * @remarks     This method returns @c true only if the specified object is also an instance of the %Stack class,
 296          *                              both stacks have the same size, and all the corresponding pairs of the elements in the two stacks are equal. @n
 297          *                              In other words, two stacks are equal if they contain the same elements in the same order.
 298          */
 299         virtual bool Equals(const Object& obj) const;
 300
 301         /**
 302          * Gets the hash value of the current instance.
 303          *
 304          * @since 2.0
 305          *
 306          * @return      The hash value of the current instance
 307          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. @n
 308          *                      For better performance, the used hash function must generate a random distribution for all the inputs.
 309          */
 310         virtual int GetHashCode(void) const;
 311
 312 private:
 313         /**
 314          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 315          *
 316          * @param[in]   stack The other instance of Stack
 317          */
 318         Stack(const Stack& stack);
 319
 320         /**
 321          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 322          *
 323          * @since 2.0
 324          *
 325          * @param[in]   stack An instance of %Stack
 326          */
 327         Stack& operator =(const Stack& stack);
 328
 329         int __capacity;
 330         int __index;
 331         Object** __pObjArray;
 332         int __modCount;
 333         static const int DEFAULT_CAPACITY = 10;
 334
 335         friend class _StackEnumerator;
 336         class _StackImpl* __pStackImpl;
 337         friend class _StackImpl;
 338
 339 }; // Stack
 340
 341 }}} // Tizen::Base::Collection
 342
 343 #endif // _FBASE_COL_STACK_H_