--- psiconv/trunk/lib/psiconv/list.h	2000/12/13 00:42:04	61
+++ psiconv/trunk/lib/psiconv/list.h	2000/12/13 16:17:54	62
@@ -36,7 +36,10 @@
 
 /* Before using a list, call list_new. It takes the size of a single element
    as its argument. Always compute it with a sizeof() expression, just to be
-   safe. The returned list is empty. */
+   safe. The returned list is empty. 
+   If there is not enough memory available, NULL is returned. You should 
+   always test for this explicitely, because the other functions do not
+   like a psiconv_list argument that is equal to NULL */
 extern psiconv_list psiconv_list_new(int element_size);
 
 /* This frees the list. If elements contain pointers that need to be freed
@@ -56,13 +59,17 @@
 
 /* Get an element from the list, and return a pointer to it. Note: you can
    directly modify this element, but be careful not to write beyond the
-   element memory space. */
+   element memory space. 
+   If indx is out of range, NULL is returned. */
 extern void * psiconv_list_get(const psiconv_list l, unsigned int indx);
 
 /* Add an element at the end of the list. The element is copied from the
    supplied element. Of course, this does not help if the element contains
-   pointers. */
-extern void psiconv_list_add(psiconv_list l, void *el);
+   pointers. 
+   As the lists extends itself, it may be necessary to allocate new
+   memory. If this fails, a negative error-code is returned. If everything,
+   succeeds, 0 is returned. */
+extern int psiconv_list_add(psiconv_list l, void *el);
 
 /* Do some action for each element. Note: you can directly modify the
    elements supplied to action, and they will be changed in the list,
@@ -70,19 +77,17 @@
 extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el));
 
 /* Clone the list, that is, copy it. If elements contain pointers, you
-   should call the next routine. */
+   should call the next routine. If not enough memory is available,
+   NULL is returned. */
 extern psiconv_list psiconv_list_clone(const psiconv_list l);
 
-/* Clone the list. For each element, clone_el is called. The elements which
-   are given to clone_el must be modified in place, as needed. */
-extern psiconv_list psiconv_list_clone_el(const psiconv_list l,
-                                          void clone_el(void *el));
-
 /* Read upto size_t elements from file f, and put them at the end of list l.
    Returned is the actual number of elements added. This assumes the file
-   layout and the memory layout of elements is the same. */
+   layout and the memory layout of elements is the same. Note that if
+   not enough memory could be allocated, 0 is simply returned. */
 extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f);
 
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */