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