Tidy up m_wordfm.
First, as the allocator function does not fail, there is no need
to assert its return value.
Second, remove commented out (since r8765) function VG_(isEmptyFM).
Third, remove VG_(getNodeSizeFM) from the API. The details of the
implementation do not need to be exposed.
Fourth, for consistency require that the copy functions for keys and
values in VG_(dopyFM) (which are essentially like allocators) return
non-NULL values for non-NULL arguments if they return.
Fifth, document NULL-ness of return values for VG_(newFM), VG_(dopyFM),
and VG_(newBag). Remove pointless asserts at call sites.
Six, change avl_dopy to assert that the node the function is
supposed to copy is not NULL. It is called that way anyhow. With
that change the function never returns NULL which allows us to
simplify the call sites. Checking the return value is no longer needed.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@14535 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/include/pub_tool_wordfm.h b/include/pub_tool_wordfm.h
index f0fdb58..bd7e221 100644
--- a/include/pub_tool_wordfm.h
+++ b/include/pub_tool_wordfm.h
@@ -77,7 +77,8 @@
VG_(initIterAtFM), VG_(nextIterFM), VG_(doneIterFM) to iterate over
sections of the map, or the whole thing. If kCmp is NULL then the
ordering used is unsigned word ordering (UWord) on the key
- values. */
+ values.
+ The function never returns NULL. */
WordFM* VG_(newFM) ( void* (*alloc_nofail)( const HChar* cc, SizeT ),
const HChar* cc,
void (*dealloc)(void*),
@@ -129,11 +130,6 @@
// since it involves walking the whole tree.
UWord VG_(sizeFM) ( WordFM* fm );
-// Is fm empty? This at least is an O(1) operation.
-// Code is present in m_wordfm.c but commented out due to no
-// current usage. Un-comment (and TEST IT) if required.
-//Bool VG_(isEmptyFM)( WordFM* fm );
-
// set up FM for iteration
void VG_(initIterFM) ( WordFM* fm );
@@ -148,21 +144,18 @@
Bool VG_(nextIterFM) ( WordFM* fm,
/*OUT*/UWord* pKey, /*OUT*/UWord* pVal );
-// clear the I'm iterating flag
+// Finish an FM iteration
void VG_(doneIterFM) ( WordFM* fm );
// Deep copy a FM. If dopyK is NULL, keys are copied verbatim.
// If non-null, dopyK is applied to each key to generate the
-// version in the new copy. In that case, if the argument to dopyK
-// is non-NULL but the result is NULL, it is assumed that dopyK
-// could not allocate memory, in which case the copy is abandoned
-// and NULL is returned. Ditto with dopyV for values.
+// version in the new copy. dopyK may be called with a NULL argument
+// in which case it should return NULL. For all other argument values
+// dopyK must not return NULL. Ditto with dopyV for values.
+// VG_(dopyFM) never returns NULL.
WordFM* VG_(dopyFM) ( WordFM* fm,
UWord(*dopyK)(UWord), UWord(*dopyV)(UWord) );
-// admin: what's the 'common' allocation size (for tree nodes?)
-SizeT VG_(getNodeSizeFM)( void );
-
//------------------------------------------------------------------//
//--- end WordFM ---//
//--- Public interface ---//
@@ -175,7 +168,7 @@
typedef struct _WordBag WordBag; /* opaque */
-/* Allocate and initialise a WordBag */
+/* Allocate and initialise a WordBag. Never returns NULL. */
WordBag* VG_(newBag) ( void* (*alloc_nofail)( const HChar* cc, SizeT ),
const HChar* cc,
void (*dealloc)(void*) );