ICU 56 update step 1

source/common/uhash.h

 /*
 ******************************************************************************
-*   Copyright (C) 1997-2011, International Business Machines
+*   Copyright (C) 1997-2015, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 ******************************************************************************
 *   Date        Name        Description
 *   03/22/00    aliu        Adapted from original C++ ICU Hashtable.
 *   07/06/01    aliu        Modified to support int32_t keys on
 *                           platforms with sizeof(void*) < 32.
 ******************************************************************************
 */
 
 #ifndef UHASH_H
 #define UHASH_H
 
 #include "unicode/utypes.h"
 #include "cmemory.h"
 #include "uelement.h"
+#include "unicode/localpointer.h"
 
 /**
  * UHashtable stores key-value pairs and does moderately fast lookup
  * based on keys.  It provides a good tradeoff between access time and
  * storage space.  As elements are added to it, it grows to accomodate
  * them.  By default, the table never shrinks, even if all elements
  * are removed from it.
  *
  * Keys and values are stored as void* pointers.  These void* pointers
  * may be actual pointers to strings, objects, or any other structure
@@ skipping 21 matching lines @@
  * value is passed to uhash_put(), this has the effect of doing a
  * uhash_remove() on that key.  This keeps uhash_get(), uhash_count(),
  * and uhash_nextElement() consistent with one another.
  *
  * To see everything in a hashtable, use uhash_nextElement() to
  * iterate through its contents.  Each call to this function returns a
  * UHashElement pointer.  A hash element contains a key, value, and
  * hashcode.  During iteration an element may be deleted by calling
  * uhash_removeElement(); iteration may safely continue thereafter.
  * The uhash_remove() function may also be safely called in
- * mid-iteration.  However, if uhash_put() is called during iteration
- * then the iteration will be out of sync.  Under no circumstances
- * should the UHashElement returned by uhash_nextElement be modified
- * directly.
+ * mid-iteration.  If uhash_put() is called during iteration,
+ * the iteration is still guaranteed to terminate reasonably, but
+ * there is no guarantee that every element will be returned or that
+ * some won't be returned more than once.
+ *
+ * Under no circumstances should the UHashElement returned by
+ * uhash_nextElement be modified directly.
  *
  * By default, the hashtable grows when necessary, but never shrinks,
  * even if all items are removed.  For most applications this is
  * optimal.  However, in a highly dynamic usage where memory is at a
  * premium, the table can be set to both grow and shrink by calling
  * uhash_setResizePolicy() with the policy U_GROW_AND_SHRINK.  In a
  * situation where memory is critical and the client wants a table
  * that does not grow at all, the constant U_FIXED can be used.
  */
 
@@ skipping 404 matching lines @@
  * compare, then the hash key may be desired in order to obtain the
  * canonical case corresponding to a search key.
  * @param hash The target UHashtable.
  * @param key A key stored in a hashtable
  * @return a hash element, or NULL if the key is not found.
  */
 U_CAPI const UHashElement* U_EXPORT2 
 uhash_find(const UHashtable *hash, const void* key);
 
 /**
+ * \def UHASH_FIRST
+ * Constant for use with uhash_nextElement
+ * @see uhash_nextElement
+ */
+#define UHASH_FIRST (-1)
+
+/**
  * Iterate through the elements of a UHashtable.  The caller must not
  * modify the returned object.  However, uhash_removeElement() may be
  * called during iteration to remove an element from the table.
  * Iteration may safely be resumed afterwards.  If uhash_put() is
  * called during iteration the iteration will then be out of sync and
  * should be restarted.
  * @param hash The target UHashtable.
- * @param pos This should be set to -1 initially, and left untouched
+ * @param pos This should be set to UHASH_FIRST initially, and left untouched
  * thereafter.
  * @return a hash element, or NULL if no further key-value pairs
  * exist in the table.
  */
 U_CAPI const UHashElement* U_EXPORT2 
 uhash_nextElement(const UHashtable *hash,
                   int32_t *pos);
 
 /**
  * Remove an element, returned by uhash_nextElement(), from the table.
@@ skipping 150 matching lines @@
 
 /**
  * Checks if the given hash tables are equal or not.
  * @param hash1
  * @param hash2
  * @return true if the hashtables are equal and false if not.
  */
 U_CAPI UBool U_EXPORT2 
 uhash_equals(const UHashtable* hash1, const UHashtable* hash2);
 
+
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalUResourceBundlePointer
+ * "Smart pointer" class, closes a UResourceBundle via ures_close().
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @stable ICU 4.4
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUHashtablePointer, UHashtable, uhash_close);
+
+U_NAMESPACE_END
+
 #endif
+
+#endif