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