Mercurial > hg > dav / file diff

--- a/ucx/ucx/stack.h	Mon Feb 04 14:11:57 2019 +0100
+++ b/ucx/ucx/stack.h	Mon Feb 04 17:17:48 2019 +0100
@@ -91,19 +91,23 @@
  * 
  * @param stack a pointer to the stack
  * @param n amount of memory to allocate
- * @return a pointer to the allocated memory
+ * @return a pointer to the allocated memory or <code>NULL</code> on stack
+ * overflow
  * @see ucx_allocator_malloc()
  */
 void *ucx_stack_malloc(UcxStack *stack, size_t n);
 
 /**
- * Alias for #ucx_stack_malloc().
+ * Allocates memory with #ucx_stack_malloc() and copies the specified data if
+ * the allocation was successful.
+ * 
  * @param stack a pointer to the stack
  * @param n amount of memory to allocate
+ * @param data a pointer to the data to copy
  * @return a pointer to the allocated memory
  * @see ucx_stack_malloc
  */
-#define ucx_stack_push(stack, n) ucx_stack_malloc(stack, n)
+void *ucx_stack_push(UcxStack *stack, size_t n, const void *data);
 
 /**
  * Allocates an array of stack memory
@@ -119,15 +123,18 @@
 void *ucx_stack_calloc(UcxStack *stack, size_t nelem, size_t elsize);
 
 /**
- * Alias for #ucx_stack_calloc().
+ * Allocates memory with #ucx_stack_calloc() and copies the specified data if
+ * the allocation was successful.
  * 
  * @param stack a pointer to the stack
- * @param n amount of elements to allocate
+ * @param nelem amount of elements to allocate
  * @param elsize amount of memory per element
+ * @param data a pointer to the data
  * @return a pointer to the allocated memory
  * @see ucx_stack_calloc
  */
-#define ucx_stack_pusharr(stack,n,elsize) ucx_stack_calloc(stack,n,elssize)
+void *ucx_stack_pusharr(UcxStack *stack,
+        size_t nelem, size_t elsize, const void *data);
 
 /**
  * Reallocates memory on the stack.
@@ -184,12 +191,13 @@
  * Removes the top most element from the stack and copies the content to <code>
  * dest</code>.
  * 
- * In contrast to #ucx_stack_pop() the <code>dest</code> pointer <code>MUST
- * NOT</code> be <code>NULL</code>.
+ * This function copies at most <code>n</code> bytes to the destination, but
+ * the element is always freed as a whole.
+ * If the element was larger than <code>n</code>, the remaining data is lost.
  * 
  * @param stack a pointer to the stack
  * @param dest the location where the contents shall be written to
- * @param n copies at most n elements to <code>dest</code>
+ * @param n copies at most n bytes to <code>dest</code>
  * @see ucx_stack_pop
  */
 void ucx_stack_popn(UcxStack *stack, void *dest, size_t n);