Merge "[3.0][cherry-pick]Changes in Skip() and GetNextTokenWithoutPAttern() method...
[platform/framework/native/appfw.git] / inc / FBaseColHashMap.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                FBaseColHashMap.h
19  * @brief               This is the header file for the %HashMap class.
20  *
21  * This header file contains the declarations of the %HashMap class.
22  */
23 #ifndef _FBASE_COL_HASH_MAP_H_
24 #define _FBASE_COL_HASH_MAP_H_
25
26 #include <FBaseColIComparer.h>
27 #include <FBaseColIHashCodeProvider.h>
28 #include <FBaseColIMap.h>
29
30 namespace Tizen { namespace Base { namespace Collection
31 {
32
33 class _HashMapEntry;
34
35 /**
36  * @class HashMap
37  * @brief This class represents a collection of associated keys and values that are organized based on the hash code of the key.
38  *
39  * @since 2.0
40  *
41  * The %HashMap class contains unique keys and each key maps to one single value.
42  * The key and value cannot be a @c null reference.
43  *
44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
45  *
46  * The following example demonstrates how to use the %HashMap class to create and initialize a %HashMap instance and to use its methods.
47  *
48  * @code
49  *
50  *      #include <FBase.h>
51  *
52  *      using namespace Tizen::Base;
53  *      using namespace Tizen::Base::Collection;
54  *
55  *
56  *      void
57  *      MyClass::HashMapSample(void)
58  *      {
59  *              HashMap map(SingleObjectDeleter);
60  *
61  *              // Constructs a %HashMap instance with default capacity, load factor, hash code provider, and comparer
62  *              map.Construct();
63  *
64  *              map.Add(new String(L"Zero"), new Integer(0));           // map.GetCount() : 1, map : (Zero -> 0)
65  *              map.Add(new String(L"One"), new Integer(1));            // map.GetCount() : 2, map : (Zero -> 0), (one -> 1)
66  *              map.Add(new String(L"Two"), new Integer(2));            // map.GetCount() : 3, map : (Zero -> 0), (one -> 1), (Two -> 2)
67  *
68  *              // Gets a value with the specified key
69  *              Integer*        pValue = static_cast< Integer* > (map.GetValue(String(L"Zero")));               // pValue : 0
70  *
71  *              // Removes the value with the specified key
72  *              map.Remove(String(L"Zero"));                                                                                    // map.GetCount() : 2, map : (one -> 1), (Two -> 2)
73  *
74  *              // Uses an enumerator to access elements in the list
75  *              IMapEnumerator* pMapEnum = map.GetMapEnumeratorN();
76  *              String* pKey = null;
77  *              while (pMapEnum->MoveNext() == E_SUCCESS)
78  *              {
79  *                      pKey = static_cast< String* > (pMapEnum->GetKey());
80  *                      pValue = static_cast< Integer* > (pMapEnum->GetValue());
81  *              }
82  *
83  *              delete pMapEnum;
84  *
85  *              // Deallocates all objects
86  *              // Because the destructor calls RemoveAll() internally, you do not need to call RemoveAll() to destroy all elements at the end.
87  *              // map.RemoveAll();
88  *      }
89  * @endcode
90  */
91 class _OSP_EXPORT_ HashMap
92         : public IMap
93         , public Object
94 {
95 public:
96         using IMap::Add;
97         using IMap::Remove;
98         using IMap::RemoveAll;
99         using IMap::SetValue;
100         using IMap::ContainsKey;
101         /**
102          * The object is not fully constructed after this constructor is called. For full construction, @n
103          * the Construct() method must be called right after calling this constructor.
104          *
105          * @since 2.0
106          *
107          * @param[in]   deleter The function pointer to type of the element deleter
108          * @remarks     To create an owing collection, set the element deleter value as @c SingleObjectDeleter. This gives the collection the ownership of elements and the collection will destroy elements. @n
109          *                      On the other hand, to create a non-owning collection, you do not need to set the element deleter value, as @c NoOpDeleter is the default element deleter.
110          *                      It means that you do not transfer the ownership of elements to the collection.
111          * @see         NoOpDeleter()
112          * @see         SingleObjectDeleter()
113          * @see         ArrayDeleter()
114          */
115         explicit HashMap(DeleterFunctionType deleter = NoOpDeleter);
116
117         /**
118          * This destructor overrides Tizen::Base::Object::~Object().
119          *
120          * @since 2.0
121          */
122         virtual ~HashMap(void);
123
124         /**
125          * Initializes an instance of an empty %HashMap class with the initial capacity and load factor.
126          *
127          * @since 2.0
128          *
129          * @return              An error code
130          * @param[in]   capacity                The initial capacity
131          * @param[in]   loadFactor              The maximum ratio of elements to buckets
132          * @exception   E_SUCCESS               The method is successful.
133          * @exception   E_INVALID_ARG   A specified input parameter is invalid, @n
134          *                                                              the @c capacity or the @c loadFactor is negative.
135          * @remarks             The GetHashCode() method of key objects is used for hashing and
136          *                              the Equals() method of key objects is used for comparing keys.
137          * @see                 HashMap()
138          */
139         result Construct(int capacity = 16, float loadFactor = 0.75);
140
141         /**
142          * Initializes an instance of a %HashMap class by copying the elements of the specified @c map.
143          *
144          * @since 2.0
145          *
146          * @return              An error code
147          * @param[in]   map                             The map to copy
148          * @param[in]   loadFactor              The maximum ratio of elements to buckets
149          * @exception   E_SUCCESS               The method is successful.
150          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
151          *                                                              the @c loadFactor is negative.
152          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
153          *                                                                      the @c map is modified during the operation of this method.
154          * @remarks             This method performs a shallow copy. It copies only the pointer; not the element itself.
155          * @see                 HashMap()
156          */
157         result Construct(const IMap& map, float loadFactor = 0.75);
158
159         /**
160          * Initializes an instance of an empty %HashMap class with the specified initial capacity, load factor, hash code provider, and comparer.
161          *
162          * @since 2.0
163          *
164          * @return              An error code
165          * @param[in]   capacity                The initial capacity @n
166          *                                                              If it is @c 0, the default capacity(16) is used.
167          * @param[in]   loadFactor              The maximum ratio of elements to buckets @n
168          *                                                              If it is @c 0, the default load factor(0.75) is used.
169          * @param[in]   provider                An instance of the IHashCodeProvider derived class that supplies the hash codes for all the keys in this map
170          * @param[in]   comparer                An instance of the IComparer derived class to use when comparing the keys
171          *
172          * @exception   E_SUCCESS               The method is successful.
173          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
174          *                                                                the @c capacity or the @c loadFactor is negative.
175          * @remarks             The instances of hash code provider and comparer will not be deallocated later from this map.
176          * @see                 HashMap()
177          */
178         result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
179
180         /**
181          * Initializes an instance of a %HashMap class by copying the elements of the specified map with the specified load factor, hash code provider, and comparer.
182          *
183          * @since 2.0
184          *
185          * @return              An error code
186          * @param[in]   map                     The map to copy
187          * @param[in]   loadFactor      The maximum ratio of elements to buckets @n
188          *                                                      If it is @c 0, the default load factor(0.75) is used.
189          * @param[in]   provider        An instance of the IHashCodeProvider derived class that supplies the hash codes for all keys in this map
190          * @param[in]   comparer        An instance of the IComparer derived class to use when comparing keys
191          * @exception   E_SUCCESS                       The method is successful.
192          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
193          *                                                                      the @c loadFactor is negative.
194          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
195          *                                                                      the @c map is modified during the operation of this method.
196          * @remarks             This method performs a shallow copy. It copies only the pointer; not the element itself.
197          * @remarks             The instances of hash code provider and comparer will not be deallocated later from this map.
198          * @see                 HashMap()
199          */
200         result Construct(const IMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
201
202         /**
203          * Adds the specified key-value pair to a map.
204          *
205          * @since 2.0
206          *
207          * @return              An error code
208          * @param[in]   pKey    The pointer to key of the value to add
209          * @param[in]   pValue  The pointer to value to add
210          * @exception   E_SUCCESS                       The method is successful.
211          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
212          *                                                                      the comparer has failed to compare the keys.
213          * @exception   E_OBJ_ALREADY_EXIST     The specified @c pKey already exists.
214          * @remarks             This method performs a shallow copy. It adds only the pointer; not the element itself.
215          * @see                 Remove()
216          */
217         virtual result Add(Object* pKey, Object* pValue);
218
219         /**
220          * Gets an enumerator (an instance of the IMapEnumerator derived class) of this map.
221          *
222          * @since 2.0
223          *
224          * @return              An instance of the IMapEnumerator derived class, if successful @n
225          *                              else @c null if an exception occurs
226          * @remarks             The specific error code can be accessed using the GetLastResult() method.
227          * @see                 Tizen::Base::Collection::IEnumerator
228          * @see                 Tizen::Base::Collection::IMapEnumerator
229          */
230         virtual IEnumerator* GetEnumeratorN(void) const;
231
232         /**
233          * Gets the elements of the map in an instance of the IMapEnumerator derived class.
234          *
235          * @since 2.0
236          *
237          * @return              An instance of the IMapEnumerator derived class, @n
238          *                              else @c null if an exception occurs
239          * @remarks             The specific error code can be accessed using the GetLastResult() method.
240          * @see                 Tizen::Base::Collection::IEnumerator
241          * @see                 Tizen::Base::Collection::IMapEnumerator
242          */
243         virtual IMapEnumerator* GetMapEnumeratorN(void) const;
244
245         /**
246          * Gets the value associated with the specified @c key.
247          *
248          * @since 2.0
249          *
250          * @return              The value associated with the key, @n
251          *                              else @c null if an exception occurs
252          * @param[in]   key             The key to locate
253          * @exception   E_SUCCESS                       The method is successful.
254          * @exception   E_INVALID_ARG           The specified input parameter is invalid, or
255          *                                                                      the comparer has failed to compare the keys.
256          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
257          * @remarks             The specific error code can be accessed using the GetLastResult() method.
258          * @see                 SetValue()
259          */
260         virtual const Object* GetValue(const Object& key) const;
261
262         /**
263          * Gets the value associated with the specified @c key.
264          *
265          * @since 2.0
266          *
267          * @return              The value associated with the key, @n
268          *                              else @c null if an exception occurs
269          * @param[in]   key             The key to locate
270          * @exception   E_SUCCESS                       The method is successful.
271          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
272          *                                                                      the comparer has failed to compare the keys.
273          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
274          * @remarks             The specific error code can be accessed using the GetLastResult() method.
275          * @see                 SetValue()
276          */
277         virtual Object* GetValue(const Object& key);
278
279         /**
280          * Gets a list of all the keys in a map.
281          *
282          * @since 2.0
283          *
284          * @return              A pointer to an IList object containing all the keys in the map, @n
285          *                              else @c null if an exception occurs
286          * @remarks             The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
287          *              The IList stores just the pointers to the elements in the map, not the elements themselves.
288          *                              The specific error code can be accessed using the GetLastResult() method.
289          * @see                 GetValuesN()
290          */
291         virtual IList* GetKeysN(void) const;
292
293         /**
294          * Gets all the values in the map.
295          *
296          * @since 2.0
297          *
298          * @return              A pointer to an IList object containing all the values in the map, @n
299          *                              else @c null if an exception occurs
300          * @remarks             The IList stores just the pointers to the elements in the map, not the elements themselves.
301          * @remarks             The specific error code can be accessed using the GetLastResult() method.
302          * @see                 GetKeysN()
303          */
304         virtual IList* GetValuesN(void) const;
305
306         /**
307          * Removes the values associated with the specified @c key.
308          *
309          * @since 2.0
310          *
311          * @return              An error code
312          * @param[in]   key The key to remove
313          * @exception   E_SUCCESS                       The method is successful.
314          * @exception   E_INVALID_ARG           The specified input parameter is invalid, or
315          *                                                                      the comparer has failed to compare keys.
316          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
317          * @see                 Add()
318          */
319         virtual result Remove(const Object& key);
320
321         /**
322          * Removes all the object pointers in the collection. @n
323          * The %RemoveAll() method can be called before deleting a collection.
324          *
325          * @since 2.0
326          */
327         virtual void RemoveAll(void);
328
329         /**
330          * Sets the value associated with the specified @c key by allocating it a new value.
331          *
332          * @since 2.0
333          *
334          * @return              An error code
335          * @param[in]   key     The key whose value is to replace
336          * @param[in]   pValue  The pointer to new value to replace
337          * @exception   E_SUCCESS                       The method is successful.
338          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
339          *                                                                      the comparer has failed to compare keys.
340          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
341          * @remarks             To add a new key-value pair, use the Add() method.
342          * @see                 Add()
343          * @see                 GetValue()
344          */
345         virtual result SetValue(const Object& key, Object* pValue);
346
347         /**
348          * Gets the number of pairs currently stored in the map.
349          *
350          * @since 2.0
351          *
352          * @return              The pairs stored in the map
353          */
354         virtual int GetCount(void) const;
355
356         /**
357          * Checks whether the map contains the specified @c key.
358          *
359          * @since 2.0
360          *
361          * @return              @c true if the map contains the specified @c key, @n
362          *                              else @c false
363          * @param[in]   key     The key to locate
364          * @exception   E_SUCCESS               The method is successful.
365          * @exception   E_INVALID_ARG   The specified input parameter is invalid, or
366          *                                                              the comparer has failed to compare the keys.
367          * @remarks             The specific error code can be accessed using the GetLastResult() method.
368          * @see                 ContainsValue()
369          */
370         virtual bool ContainsKey(const Object& key) const;
371
372         /**
373          * Checks whether the map contains the specified @c value.
374          *
375          * @since 2.0
376          *
377          * @return              @c true if the map contains the specified @c value, @n
378          *                              else @c false
379          * @param[in]   value   The value to locate
380          *
381          * @see                 ContainsKey()
382          */
383         virtual bool ContainsValue(const Object& value) const;
384
385         /**
386          * Compares two instances of the %HashMap class.
387          *
388          * @since 2.0
389          *
390          * @return              @c true if the two instances match, @n
391          *                              else @c false
392          * @param[in]   obj The object to compare with the current instance
393          * @remarks             This method returns @c true if and only if the two instances contain the same number of elements and all the elements contained in each other.
394          */
395         virtual bool Equals(const Object& obj) const;
396
397         /**
398          * Gets the hash value of the current instance.
399          *
400          * @since 2.0
401          *
402          * @return      The hash value of the current instance
403          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
404          *                      the used hash function must generate a random distribution for all inputs.
405          */
406         virtual int GetHashCode(void) const;
407
408         /**
409          * Gets the element deleter of the collection.
410          *
411          * @since 2.0
412          *
413          * @return              A function pointer to the existing element deleter
414          */
415         virtual DeleterFunctionType GetDeleter(void) const;
416
417 private:
418         /**
419          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
420          *
421          * @param[in]   map             The instance of the %HashMap class to copy from
422          */
423         HashMap(const HashMap& map);
424
425         /**
426          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
427          *
428          * @param[in]   map             An instance of %HashMap
429          */
430         HashMap& operator =(const HashMap& map);
431
432         /**
433          * Copies all the pairs from the specified @c map to this map.
434          *
435          * @return              An error code
436          * @param[in]   map The map to copy
437          * @exception   E_SUCCESS                       The method is successful.
438          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
439          *                                                                      The @c map is modified during the operation of this method.
440          */
441         result AddAll(const IMap& map);
442
443         /**
444          * Gets the hash value for the specified object.
445          *
446          * @return              The hash value for the specified object
447          * @param[in]   obj
448          */
449         int Hash(const Object& obj) const;
450
451         /**
452          * Rehashes the content of a map to a new array with a greater capacity.
453          *
454          * @return              An error code
455          * @param[in[   newCapacity     The new capacity @n
456          *                                                      It must be a power of two and must be greater than the current capacity.
457          * @exception   E_SUCCESS                       The method is successful.
458          * @remarks     This method is called automatically when the number of keys in a map reaches its threshold.
459          */
460         result Resize(int newCapacity);
461
462         /**
463          *  Clears all key-value pairs in a map.
464          */
465         void Reset(void);
466
467         /**
468          * Sets the element deleter of the collection.
469          *
470          * @since 2.0
471          *
472          * @param[in]   deleter A function pointer to the element deleter to set
473          */
474         virtual void SetDeleter(DeleterFunctionType deleter);
475
476         _HashMapEntry** __pTable;
477         int __count;
478         int __capacity;
479         float __loadFactor;
480         int __threshold;
481         IHashCodeProvider* __pProvider;
482         IComparer* __pComparer;
483         bool __needToRemoveProviderComparer;
484         int __modCount;
485         DeleterFunctionType __deleter;
486         static const int DEFAULT_CAPACITY = 16;
487         static const float DEFAULT_LOAD_FACTOR;
488
489         friend class _HashMapEnumerator;
490         friend class _HashMapImpl;
491         class _HashMapImpl* __pHashMapImpl;
492
493 }; // HashMap
494
495 }}} // Tizen::Base::Collection
496
497 #endif //_FBASE_COL_HASH_MAP_H_