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 The specified input parameter is invalid, or
107 * the specified @c capacity is negative.
108 * @remarks If the number of elements added to the stack reaches the current capacity,
109 * the capacity is automatically increased by memory reallocation. @n
110 * Therefore, if the size of the stack can be estimated,
111 * specifying the initial capacity eliminates the need to perform a number of
112 * resizing operations while adding elements to the stack.
115 result Construct(int capacity = DEFAULT_CAPACITY);
118 * Initializes this instance of %Stack by copying the elements of the specified collection. @n
119 * The capacity of the stack is the same as the number of elements copied.
123 * @return An error code
124 * @param[in] collection The collection to copy elements from
125 * @exception E_SUCCESS The method is successful.
126 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
127 * the @c collection is modified during the operation of this method.
128 * @remarks This method performs a shallow copy. It copies just the pointer; not the element itself.
131 result Construct(const ICollection& collection);
134 * Gets an enumerator of this stack.
138 * @return An enumerator (an instance of the IEnumerator derived class) of this stack, @n
139 * else @c null if an exception occurs
140 * @remarks The specific error code can be accessed using the GetLastResult() method.
143 virtual IEnumerator* GetEnumeratorN(void) const;
146 * Gets the element at the top of this stack without removing it.
150 * @return The element at the top of this stack, @n
151 * else @c null if this stack is empty
152 * @exception E_SUCCESS The method is successful.
153 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
154 * this stack is empty.
155 * @remarks The specific error code can be accessed using the GetLastResult() method.
157 virtual const Object* Peek(void) const;
160 * Pops the element from the top of this stack.
164 * @return The element at the top of this stack, @n
165 * else @c null if this stack is empty
166 * @exception E_SUCCESS The method is successful.
167 * @exception E_UNDERFLOW The operation (arithmetic/casting/conversion) has caused an underflow, or
168 * this stack is empty.
169 * @remarks The specific error code can be accessed using the GetLastResult() method.
172 virtual Object* Pop(void);
176 * Pushes an object to the top of this stack.
178 * @brief <i> [Deprecated] </i>
179 * @deprecated This method is deprecated because it has a problem of const reference argument.
180 * Instead of using this method, use Push(Object* pObj).
183 * @return An error code
184 * @param[in] obj The object to add to this stack
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_OUT_OF_MEMORY The memory is insufficient.
187 * @remarks This method performs a shallow copy. It inserts just the pointer; not the element itself.
191 result Push(const Object& obj)
193 return Push(const_cast< Object* >(&obj));
197 * Pushes an object to the top of this stack.
201 * @return An error code
202 * @param[in] pObj The pointer to object to add to this stack
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_INVALID_ARG The specified input parameter is invalid.
205 * @remarks This method performs a shallow copy. It inserts just the pointer; not the element itself.
208 virtual result Push(Object* pObj);
211 * Removes all objects and their pointers in collection, when the @c deallocate parameter is set to @c true. @n
212 * This method can be called before deleting the objects in a collection.
216 * @param[in] deallocate Set to @c true to deallocate all objects, @n
219 virtual void RemoveAll(bool deallocate = false);
222 * Gets the number of objects currently stored in this stack.
226 * @return The number of objects currently stored in this stack
228 virtual int GetCount(void) const;
231 * Checks whether this stack contains the specified object.
235 * @return @c true if this stack contains the specified object, @n
237 * @param[in] obj The object to locate
239 virtual bool Contains(const Object& obj) const;
243 * Checks whether this stack contains all of the elements in the specified collection.
245 * @brief <i> [Deprecated] </i>
246 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
247 * The return type will be changed into boolean type and this method will return the result.
248 * Instead of using this method, use bool Contains(const ICollection& collection).
251 * @return An error code
252 * @param[in] collection The collection to locate
253 * @param[out] out Set to @c true if this stack contains all the elements in the specified collection, @n
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
257 * the @c collection is modified during the operation of this method.
260 result ContainsAll(const ICollection& collection, bool& out) const
262 out = ContainsAll(collection);
263 result r = GetLastResult();
268 * Checks whether this stack contains all of the elements in the specified collection.
272 * @return @c true if this stack contains all the elements in the specified collection, @n
274 * @param[in] collection The collection to locate
275 * @exception E_SUCCESS The method is successful.
276 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
277 * the @c collection is modified during the operation of this method.
278 * @remarks The specific error code can be accessed using the GetLastResult() method.
280 virtual bool ContainsAll(const ICollection& collection) const;
283 * Checks whether the specified instance equals the current instance.
287 * @return @c true if the specified instance equals the current instance, @n
289 * @param[in] obj The object to compare with the current instance
290 * @remarks This method returns @c true only if the specified object is also an instance of %Stack class,
291 * both stacks have the same size, and all corresponding pairs of elements in the two stacks are equal.
292 * In other words, two stacks are equal if they contain the same elements in the same order.
294 virtual bool Equals(const Object& obj) const;
297 * Gets the hash value of the current instance.
301 * @return The hash value of the current instance
302 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
303 * the used hash function must generate a random distribution for all inputs.
305 virtual int GetHashCode(void) const;
309 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
311 * @param[in] stack The other instance of Stack
313 Stack(const Stack& stack);
316 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
320 * @param[in] stack An instance of %Stack
322 Stack& operator =(const Stack& stack);
326 Object** __pObjArray;
328 static const int DEFAULT_CAPACITY = 10;
330 friend class _StackEnumerator;
331 class _StackImpl* __pStackImpl;
332 friend class _StackImpl;
336 }}} // Tizen::Base::Collection
338 #endif // _FBASE_COL_STACK_H_