For the string-desc module, I need to make use of the 'ialloc' module.
Which is hard if its functions are not documented. I mean, as a user
of imalloc(), I'm not supposed to look into the module description
in order to understand that this function returns non-NULL for a
zero-sized allocation. Things like that should be stated as comments.
Done as follows:
2023-03-27 Bruno Haible <br...@clisp.org>
ialloc: Add comments.
* lib/ialloc.h (imalloc, irealloc, icalloc, ireallocarray): Add
comments.
diff --git a/lib/ialloc.h b/lib/ialloc.h
index 1d43faf388..275237ccb1 100644
--- a/lib/ialloc.h
+++ b/lib/ialloc.h
@@ -43,6 +43,9 @@ _gl_alloc_nomem (void)
return NULL;
}
+/* imalloc (size) is like malloc (size).
+ It returns a non-NULL pointer to size bytes of memory.
+ Upon failure, it returns NULL with errno set. */
IALLOC_INLINE
_GL_ATTRIBUTE_MALLOC /*_GL_ATTRIBUTE_DEALLOC_FREE*/
void *
@@ -51,6 +54,9 @@ imalloc (idx_t s)
return s <= SIZE_MAX ? malloc (s) : _gl_alloc_nomem ();
}
+/* irealloc (ptr, size) is like realloc (ptr, size).
+ It returns a non-NULL pointer to size bytes of memory.
+ Upon failure, it returns NULL with errno set. */
IALLOC_INLINE
/*_GL_ATTRIBUTE_DEALLOC_FREE*/
void *
@@ -61,6 +67,9 @@ irealloc (void *p, idx_t s)
return s <= SIZE_MAX ? realloc (p, s | !s) : _gl_alloc_nomem ();
}
+/* icalloc (num, size) is like calloc (num, size).
+ It returns a non-NULL pointer to num * size bytes of memory.
+ Upon failure, it returns NULL with errno set. */
IALLOC_INLINE
_GL_ATTRIBUTE_MALLOC /*_GL_ATTRIBUTE_DEALLOC_FREE*/
void *
@@ -81,6 +90,9 @@ icalloc (idx_t n, idx_t s)
return calloc (n, s);
}
+/* ireallocarray (ptr, num, size) is like reallocarray (ptr, num, size).
+ It returns a non-NULL pointer to num * size bytes of memory.
+ Upon failure, it returns NULL with errno set. */
IALLOC_INLINE void *
ireallocarray (void *p, idx_t n, idx_t s)
{
