2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseColStack.h
19 * @brief This is the header file for the %Stack class.
21 * This header file contains the declarations of the %Stack class.
24 #ifndef _FBASE_COL_STACK_H_
25 #define _FBASE_COL_STACK_H_
27 #include <FBaseObject.h>
28 #include <FBaseTypes.h>
29 #include <FBaseColICollection.h>
31 namespace Tizen { namespace Base { namespace Collection
36 * @brief This class represents a simple last-in-first-out collection of objects, that is, a stack.
40 * The %Stack class represents a simple last-in-first-out collection of objects, that is, a stack.
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>.
44 * The following example demonstrates how to use the %Stack class.
49 * using namespace Tizen::Base;
50 * using namespace Tizen::Base::Collection;
53 * MyClass::StackSample(void)
56 * stack.Construct(3); // capacity = 3
58 * stack.Push(new String(L"First"));
59 * stack.Push(new String(L"Second"));
60 * stack.Push(new String(L"Third"));
62 * // Reads the element at the top
63 * const Object* pObj = stack.Peek(); // pObj: "Third", stack.GetCount(): 3
65 * // Reads and removes the element at the top
66 * String* pStr = static_cast< String* > (stack.Pop()); // pStr: "Third", stack.GetCount(): 2
68 * delete pStr; // Because the stack does not have the ownership of this pStr after popping
70 * // Deallocates all objects
71 * stack.RemoveAll(true);
75 class _OSP_EXPORT_ Stack
76 : public virtual ICollection
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.
90 * This destructor overrides Tizen::Base::Object::~Object().
98 * Initializes this instance of %Stack with the specified capacity.
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.
116 result Construct(int capacity = DEFAULT_CAPACITY);
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.
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.
133 result Construct(const ICollection& collection);
136 * Gets the enumerator of this stack.
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.
144 virtual IEnumerator* GetEnumeratorN(void) const;
147 * Gets the element at the top of this stack without removing it.
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.
159 virtual const Object* Peek(void) const;
162 * Pops the element from the top of this stack.
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.
175 virtual Object* Pop(void);
179 * Pushes an object to the top of this stack.
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).
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.
194 result Push(const Object& obj)
196 return Push(const_cast< Object* >(&obj));
200 * Pushes an object to the top of this stack.
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.
211 virtual result Push(Object* pObj);
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.
219 * @param[in] deallocate Set to @c true to deallocate all objects, @n
222 virtual void RemoveAll(bool deallocate = false);
225 * Gets the number of objects currently stored in this stack.
229 * @return The number of objects currently stored in this stack
231 virtual int GetCount(void) const;
234 * Checks whether this stack contains the specified object.
238 * @return @c true if this stack contains the specified object, @n
240 * @param[in] obj The object to locate
242 virtual bool Contains(const Object& obj) const;
246 * Checks whether this stack contains all of the elements in the specified collection.
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).
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
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.
264 result ContainsAll(const ICollection& collection, bool& out) const
266 out = ContainsAll(collection);
267 result r = GetLastResult();
272 * Checks whether this stack contains all the elements in the specified collection.
276 * @return @c true if this stack contains all the elements in the specified collection, @n
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.
285 virtual bool ContainsAll(const ICollection& collection) const;
288 * Checks whether the specified instance equals the current instance.
292 * @return @c true if the specified instance equals the current instance, @n
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.
299 virtual bool Equals(const Object& obj) const;
302 * Gets the hash value of the current instance.
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.
310 virtual int GetHashCode(void) const;
314 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
316 * @param[in] stack The other instance of Stack
318 Stack(const Stack& stack);
321 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
325 * @param[in] stack An instance of %Stack
327 Stack& operator =(const Stack& stack);
331 Object** __pObjArray;
333 static const int DEFAULT_CAPACITY = 10;
335 friend class _StackEnumerator;
336 class _StackImpl* __pStackImpl;
337 friend class _StackImpl;
341 }}} // Tizen::Base::Collection
343 #endif // _FBASE_COL_STACK_H_