ucx: comparison docs/src/modules-ucx2.md

-:cc8cbabd27cd
+:1e2be40f0cb5
 // make the array as small as possible
 ucx_array_shrink(result);
 return result;
 }
-/* ... */
+// ...
-sstr_t* array = /* some standard array of strings */
+sstr_t* array = // some standard array of strings
-size_t arrlen = /* the length of the array */
+size_t arrlen = // the length of the array
 UcxArray* result = create_unique(array,arrlen);
-/* Iterate over the array and print the elements */
+// Iterate over the array and print the elements
 sstr_t* unique = result->data;
 for (size_t i = 0 ; i < result->size ; i++) {
 printf("%" PRIsstr "\n", SFMT(unique[i]));
 }
-/* Free the array. */
+// Free the array.
 ucx_array_free(result);
 ```
 ### Preventing out of bounds writes
 The functions `ucx_array_reserve()`, `ucx_array_resize()`, `ucx_array_grow()`,
 Suppose you have a list of items which contain a `time_t` value and your task
 is to find all items within a time window `[t_start, t_end]`.
 With AVL Trees this is easy:
 ```C
-/* ---------------------
+// Somewhere in a header
-* Somewhere in a header
-*/
 typedef struct {
 time_t ts;
-/* other important data */
+// other important data
 } MyObject;
-/* -----------
+// Source code
-* Source code
-*/
 UcxAVLTree* tree = ucx_avl_new(ucx_cmp_longint);
-/* ... populate tree with objects, use '& MyObject.ts' as key ... */
+// ... populate tree with objects, use '& MyObject.ts' as key ...
-/* Now find every item, with 30 <= ts <= 70 */
+// Now find every item, with 30 <= ts <= 70
 time_t ts_start = 30;
 time_t ts_end = 70;
 printf("Values in range:\n");
 for (
 const size_t chunksize = 256;
 UcxBuffer* linebuf =
 ucx_buffer_new(
-NULL,       /* the buffer should manage the memory area for us */
+NULL,       // the buffer should manage the memory area for us
-2*chunksize,  /* initial size should be twice the chunk size */
+2*chunksize,  // initial size should be twice the chunk size
-UCX_BUFFER_AUTOEXTEND); /* the buffer will grow when necessary */
+UCX_BUFFER_AUTOEXTEND); // the buffer will grow when necessary
 size_t lineno = 1;
 do {
-/* read line chunk */
+// read line chunk
 size_t read = ucx_stream_ncopy(
 input, linebuf, fread, ucx_buffer_write, chunksize);
 if (read == 0) break;
-/* handle line endings */
+// handle line endings
 do {
 sstr_t bufstr = ucx_buffer_to_sstr(linebuf);
 sstr_t nl = sstrchr(bufstr, '\n');
 if (nl.length == 0) break;
 size_t linelen = bufstr.length - nl.length;
 sstr_t linestr = sstrsubsl(bufstr, 0, linelen);
 printf("%zu: %" PRIsstr "\n", lineno++, SFMT(linestr));
-/* shift the buffer to the next line */
+// shift the buffer to the next line
 ucx_buffer_shift_left(linebuf, linelen+1);
 } while(1);
 } while(1);
-/* print the 'noeol' line, if any */
+// print the 'noeol' line, if any
 sstr_t lastline = ucx_buffer_to_sstr(linebuf);
 if (lastline.length > 0) {
 printf("%zu: %" PRIsstr, lineno, SFMT(lastline));
 }
 }
 }
 return list;
 }
-/* we will need this function to clean up the list contents later */
+// we will need this function to clean up the list contents later
 void free_sstr(void* ptr) {
 sstr_t* s = ptr;
 free(s->ptr);
 free(s);
 }
-/* ... */
+// ...
-sstr_t* array = /* some array of strings */
+sstr_t* array = // some array of strings
-size_t arrlen = /* the length of the array */
+size_t arrlen = // the length of the array
 UcxList* list = remove_duplicates(array,arrlen);
-/* Iterate over the list and print the elements */
+// Iterate over the list and print the elements
 UCX_FOREACH(elem, list) {
 sstr_t s = *((sstr_t*)elem->data);
 printf("%" PRIsstr "\n", SFMT(s));
 }
-/* Use our free function to free the duplicated strings. */
+// Use our free function to free the duplicated strings.
 ucx_list_free_content(list, free_sstr);
 ucx_list_free(list);
 ```
 ## Logging
 }
 } else if(option) {
 ucx_map_cstr_put(options, option, arg);
 option = NULL;
 } else {
-/* ... handle argument that is not an option ... */
+// ... handle argument that is not an option ...
 }
 }
 if(option) {
 fprintf(stderr,
 "Missing argument for option -%c\n", optchar);
 FILE *f = fopen("test.csv", "r");
 if (!f) {
 perror("Cannot open file");
 return 1;
 }
-/* close the file automatically at pool destruction*/
+// close the file automatically at pool destruction
 ucx_mempool_reg_destr(pool, f, (ucx_destructor) fclose);
-/* create a buffer and register it at the memory pool for destruction */
+// create a buffer and register it at the memory pool for destruction
 UcxBuffer* content = ucx_buffer_new(NULL, 256, UCX_BUFFER_AUTOEXTEND);
 ucx_mempool_reg_destr(pool, content, (ucx_destructor) ucx_buffer_free);
-/* read the file and split it by lines first */
+// read the file and split it by lines first
 ucx_stream_copy(f, content, fread, ucx_buffer_write);
 sstr_t contentstr = ucx_buffer_to_sstr(content);
 ssize_t lc = 0;
 sstr_t* lines = sstrsplit_a(pool->allocator, contentstr, S("\n"), &lc);
-/* skip the header and parse the remaining data */
+// skip the header and parse the remaining data
 UcxList* datalist = NULL;
 for (size_t i = 1 ; i < lc ; i++) {
 if (lines[i].length == 0) continue;
 ssize_t fc = 3;
 sstr_t* fields = sstrsplit_a(pool->allocator, lines[i], S(";"), &fc);
 data->column_b = fields[1];
 data->column_c = fields[2];
 datalist = ucx_list_append_a(pool->allocator, datalist, data);
 }
-/* control output */
+// control output
 UCX_FOREACH(elem, datalist) {
 CSVData* data = elem->data;
 printf("Column A: %" PRIsstr " | "
 "Column B: %" PRIsstr " | "
 "Column C: %" PRIsstr "\n",
 SFMT(data->column_a), SFMT(data->column_b), SFMT(data->column_c)
 );
 }
-/* cleanup everything, no manual free() needed */
+// cleanup everything, no manual free() needed
 ucx_mempool_destroy(pool);
 return 0;
 }
 ```
 memory is not supposed to be freed with a simple call to `free()`.
 In this case, you can overwrite the default destructor as follows:
 ```C
 MyObject* obj = ucx_mempool_malloc(pool, sizeof(MyObject));
-/* some special initialization with own resource management */
+// some special initialization with own resource management
 my_object_init(obj);
-/* register destructor function */
+// register destructor function
 ucx_mempool_set_destr(obj, (ucx_destructor) my_object_destroy);
 ```
 Be aware, that your destructor function should not free any memory, that is
 also managed by the pool.
 Otherwise you might be risking a double-free.
 The key/value pairs are stored within an UCX Map.
 ### Example: Loading properties from a file
 ```C
-/* Open the file as usual */
+// Open the file as usual
 FILE* file = fopen("myprops.properties", "r");
 if (!file) {
 // error handling
 return 1;
 }
-/* Load the properties from the file */
+// Load the properties from the file
 UcxMap* myprops = ucx_map_new(16);
 if (ucx_properties_load(myprops, file)) {
-/* ... error handling ... */
+// ... error handling ...
 fclose(file);
 ucx_map_free(myprops);
 return 1;
 }
-/* Print out the key/value pairs */
+// Print out the key/value pairs
 char* propval;
 UcxMapIterator propiter = ucx_map_iterator(myprops);
 UCX_MAP_FOREACH(key, propval, propiter) {
 printf("%s = %s\n", (char*)key.data, propval);
 }
-/* Don't forget to free the values before freeing the map */
+// Don't forget to free the values before freeing the map
 ucx_map_free_content(myprops, NULL);
 ucx_map_free(myprops);
 fclose(file);
 ```
 int i = 42;
 float f = 3.14f;
 const char* str = "Hello!";
 size_t strn = 7;
-/* push the integer */
+// push the integer
 ucx_stack_push(&stack, sizeof(int), &i);
-/* push the float and rember the address */
+// push the float and rember the address
 float* remember = ucx_stack_push(&stack, sizeof(float), &f);
-/* push the string with zero terminator */
+// 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 */
+// 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! */
+// 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 */
+// 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 */
+// the last element is the integer
 int j;
 ucx_stack_pop(&stack, &j);
 printf("Integer: %d\n", j);
 ```
 ### Initialization
 There are several ways to create an `sstr_t`:
 ```C
-/* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
+// (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated
 sstr_t a = sstr(cstr);
-/* (2) cstr does not need to be zero-terminated, if length is specified */
+// (2) cstr does not need to be zero-terminated, if length is specified
 sstr_t b = sstrn(cstr, len);
-/* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
+// (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
-This version is especially useful for function arguments */
+//     This version is especially useful for function arguments
 sstr_t c = S("hello");
-/* (4) SC() macro works like S(), but makes the string immutable using scstr_t.
+// (4) SC() macro works like S(), but makes the string immutable using scstr_t.
-(available since UCX 2.0) */
+//     (available since UCX 2.0)
 scstr_t d = SC("hello");
-/* (5) ST() macro creates sstr_t struct literal using sizeof() */
+// (5) ST() macro creates sstr_t struct literal using sizeof()
 sstr_t e = ST("hello");
 ```
 You should not use the `S()`, `SC()`, or `ST()` macro with string of unknown
 origin, since the `sizeof()` call might not coincide with the string length in
 ```C
 sstr_t test = ST("here::are::some::strings");
 sstr_t delim = ST("::");
-ssize_t count = 0; /* no limit */
+ssize_t count = 0; // no limit
 UcxMempool* pool = ucx_mempool_new_default();
 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
 for (ssize_t i = 0 ; i < count ; i++) {
-/* don't forget to specify the length via the %*s format specifier */
+// don't forget to specify the length via the %*s format specifier
 printf("%*s\n", result[i].length, result[i].ptr);
 }
 ucx_mempool_destroy(pool);
 ```
 define test subroutines.
 You should declare test cases and subroutines in a header file per test unit
 and implement them as you would implement normal functions.
 ```C
-/* myunit.h */
+// myunit.h
 UCX_TEST(function_name);
-UCX_TEST_SUBROUTINE(subroutine_name, paramlist); /* optional */
+UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
-/* myunit.c */
+// myunit.c
 UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
-/* ... reusable tests with UCX_TEST_ASSERT() ... */
+// ... reusable tests with UCX_TEST_ASSERT() ...
 }
 UCX_TEST(function_name) {
-/* ... resource allocation and other test preparation ... */
+// ... resource allocation and other test preparation ...
-/* mandatory marker for the start of the tests */
+// mandatory marker for the start of the tests
 UCX_TEST_BEGIN
-/*  ... verifications with UCX_TEST_ASSERT() ...
+//  ... verifications with UCX_TEST_ASSERT() ...
-* (and/or calls with UCX_TEST_CALL_SUBROUTINE())
+// (and/or calls with UCX_TEST_CALL_SUBROUTINE())
-*/
+// mandatory marker for the end of the tests
-/* mandatory marker for the end of the tests */
 UCX_TEST_END
-/* ... resource cleanup ...
+// ... resource cleanup ...
-* (all code after UCX_TEST_END is always executed)
+// (all code after UCX_TEST_END is always executed)
-*/
 }
 ```
 If you want to use the `UCX_TEST_ASSERT()` macro in a function, you are
 *required* to use a `UCX_TEST_SUBROUTINE`.
 Otherwise the testing framework does not know where to jump, when the assertion
 After implementing the tests, you can easily build a test suite and execute it:
 ```C
 UcxTestSuite* suite = ucx_test_suite_new();
 ucx_test_register(suite, testMyTestCase01);
 ucx_test_register(suite, testMyTestCase02);
-/* ... */
+// ...
-ucx_test_run(suite, stdout); /* stdout, or any other FILE stream */
+ucx_test_run(suite, stdout); // stdout, or any other FILE stream
 ```
 ## Utilities
 *Header file:* [utils.h](api-2.1/utils_8h.html)
 if (argc != 3) {
 fprintf(stderr, "Use %s <src> <dest>", argv[0]);
 return 1;
 }
-FILE *srcf = fopen(argv[1], "r");   /* insert error handling on your own */
+FILE *srcf = fopen(argv[1], "r");   // insert error handling on your own
 FILE *destf = fopen(argv[2], "w");
 size_t n =  ucx_stream_copy(srcf, destf, fread, fwrite);
 printf("%zu bytes copied.\n", n);
 for (unsigned int i = 2 ; i < 100 ; i++) {
 ucx_bprintf(strbuffer, "Integer %d is %s\n",
 i, prime(i) ? "prime" : "not prime");
 }
-/* print the result to stdout */
+// print the result to stdout
 printf("%s", (char*)strbuffer->space);
 ucx_buffer_free(strbuffer);
 ```

Mercurial > hg > ucx / file comparison

comparison: docs/src/modules-ucx2.md

docs/src/modules-ucx2.md