1.1 --- a/docs/src/modules.md Sat May 12 14:56:17 2018 +0200
1.2 +++ b/docs/src/modules.md Sun May 13 17:34:06 2018 +0200
1.3 @@ -403,12 +403,55 @@
1.4 This concrete implementation of an UCX Allocator allows you to grab some amount
1.5 of memory which is then handled as a stack.
1.6 Please note, that the term *stack* only refers to the behavior of this
1.7 -allocator. You may still choose if you want to use stack or heap memory
1.8 +allocator. You may still choose to use either stack or heap memory
1.9 for the underlying space.
1.10 -
1.11 A typical use case is an algorithm where you need to allocate and free large
1.12 amounts of memory very frequently.
1.13
1.14 +The following code sample shows how to initialize a stack and push and pop
1.15 +simple data.
1.16 +```C
1.17 + const size_t len = 1024;
1.18 + char space[len];
1.19 + UcxStack stack;
1.20 + ucx_stack_init(&stack, space, len);
1.21 +
1.22 + int i = 42;
1.23 + float f = 3.14f;
1.24 + const char* str = "Hello!";
1.25 + size_t strn = 7;
1.26 +
1.27 + /* push the integer */
1.28 + ucx_stack_push(&stack, sizeof(int), &i);
1.29 +
1.30 + /* push the float and rember the address */
1.31 + float* remember = ucx_stack_push(&stack, sizeof(float), &f);
1.32 +
1.33 + /* push the string with zero terminator */
1.34 + ucx_stack_push(&stack, strn, str);
1.35 +
1.36 + /* if we forget, how big an element was, we can ask the stack */
1.37 + printf("Length of string: %zu\n", ucx_stack_topsize(&stack)-1);
1.38 +
1.39 + /* retrieve the string as sstr_t, without zero terminator! */
1.40 + sstr_t s;
1.41 + s.length = ucx_stack_topsize(&stack)-1;
1.42 + s.ptr = malloc(s.length);
1.43 + ucx_stack_popn(&stack, s.ptr, s.length);
1.44 + printf("%" PRIsstr "\n", SFMT(s));
1.45 +
1.46 + /* print the float directly from the stack and free it */
1.47 + printf("Float: %f\n", *remember);
1.48 + ucx_stack_free(&stack, remember);
1.49 +
1.50 + /* the last element is the integer */
1.51 + int j;
1.52 + ucx_stack_pop(&stack, &j);
1.53 + printf("Integer: %d\n", j);
1.54 +```
1.55 +
1.56 +
1.57 +
1.58 ## String
1.59
1.60 *Header file:* [string.h](api/string_8h.html)
