# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1526225646 -7200
# Node ID 0f83916c163934f21deb5c25ea0d4c145c327cf7
# Parent  e7dfcf229625b0d3de36ab0fda03a6e05a08a7f7
documentation for the UcxStack

diff -r e7dfcf229625 -r 0f83916c1639 docs/src/modules.md
--- a/docs/src/modules.md	Sat May 12 14:56:17 2018 +0200
+++ b/docs/src/modules.md	Sun May 13 17:34:06 2018 +0200
@@ -403,12 +403,55 @@
 This concrete implementation of an UCX Allocator allows you to grab some amount
 of memory which is then handled as a stack.
 Please note, that the term *stack* only refers to the behavior of this
-allocator. You may still choose if you want to use stack or heap memory
+allocator. You may still choose to use either stack or heap memory
 for the underlying space.
-
 A typical use case is an algorithm where you need to allocate and free large
 amounts of memory very frequently.
 
+The following code sample shows how to initialize a stack and push and pop
+simple data.
+```C
+    const size_t len = 1024;
+    char space[len];
+    UcxStack stack;
+    ucx_stack_init(&stack, space, len);
+
+    int i = 42;
+    float f = 3.14f;
+    const char* str = "Hello!";
+    size_t strn = 7;
+
+    /* push the integer */
+    ucx_stack_push(&stack, sizeof(int), &i);
+
+    /* push the float and rember the address */
+    float* remember = ucx_stack_push(&stack, sizeof(float), &f);
+
+    /* push the string with zero terminator */
+    ucx_stack_push(&stack, strn, str);
+
+    /* if we forget, how big an element was, we can ask the stack */
+    printf("Length of string: %zu\n", ucx_stack_topsize(&stack)-1);
+
+    /* retrieve the string as sstr_t, without zero terminator! */
+    sstr_t s;
+    s.length = ucx_stack_topsize(&stack)-1;
+    s.ptr = malloc(s.length);
+    ucx_stack_popn(&stack, s.ptr, s.length);
+    printf("%" PRIsstr "\n", SFMT(s));
+
+    /* print the float directly from the stack and free it */
+    printf("Float: %f\n", *remember);
+    ucx_stack_free(&stack, remember);
+
+    /* the last element is the integer */
+    int j;
+    ucx_stack_pop(&stack, &j);
+    printf("Integer: %d\n", j);
+```
+
+
+
 ## String
 
 *Header file:* [string.h](api/string_8h.html)  
diff -r e7dfcf229625 -r 0f83916c1639 src/stack.c
--- a/src/stack.c	Sat May 12 14:56:17 2018 +0200
+++ b/src/stack.c	Sun May 13 17:34:06 2018 +0200
@@ -120,13 +120,15 @@
         return;
     }
     
-    size_t len = ucx_stack_topsize(stack);
-    if (len > n) {
-        len = n;
+    if (dest) {
+        size_t len = ucx_stack_topsize(stack);
+        if (len > n) {
+            len = n;
+        }
+
+        memcpy(dest, stack->top, len);
     }
     
-    memcpy(dest, stack->top, len);
-    
     ucx_stack_free(stack, stack->top);
 }
 
@@ -142,3 +144,22 @@
         return 0;
     }
 }
+
+void *ucx_stack_push(UcxStack *stack, size_t n, const void *data) {
+    void *space = ucx_stack_malloc(stack, n);
+    if (space) {
+        memcpy(space, data, n);
+    }
+    return space;
+}
+
+void *ucx_stack_pusharr(UcxStack *stack,
+        size_t nelem, size_t elsize, const void *data) {
+    
+    // skip the memset by using malloc
+    void *space = ucx_stack_malloc(stack, nelem*elsize);
+    if (space) {
+        memcpy(space, data, nelem*elsize);
+    }
+    return space;
+}
diff -r e7dfcf229625 -r 0f83916c1639 src/ucx/stack.h
--- a/src/ucx/stack.h	Sat May 12 14:56:17 2018 +0200
+++ b/src/ucx/stack.h	Sun May 13 17:34:06 2018 +0200
@@ -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);