Wed, 17 Jul 2013 11:47:02 +0200
added doxyfile and documentation for ucx.h
universe@103 | 1 | /* |
universe@103 | 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
olaf@5 | 3 | * |
universe@103 | 4 | * Copyright 2013 Olaf Wintermann. All rights reserved. |
universe@103 | 5 | * |
universe@103 | 6 | * Redistribution and use in source and binary forms, with or without |
universe@103 | 7 | * modification, are permitted provided that the following conditions are met: |
universe@103 | 8 | * |
universe@103 | 9 | * 1. Redistributions of source code must retain the above copyright |
universe@103 | 10 | * notice, this list of conditions and the following disclaimer. |
universe@103 | 11 | * |
universe@103 | 12 | * 2. Redistributions in binary form must reproduce the above copyright |
universe@103 | 13 | * notice, this list of conditions and the following disclaimer in the |
universe@103 | 14 | * documentation and/or other materials provided with the distribution. |
universe@103 | 15 | * |
universe@103 | 16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
universe@103 | 17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
universe@103 | 18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
universe@103 | 19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
universe@103 | 20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
universe@103 | 21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
universe@103 | 22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
universe@103 | 23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
universe@103 | 24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
universe@103 | 25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
universe@103 | 26 | * POSSIBILITY OF SUCH DAMAGE. |
olaf@5 | 27 | */ |
universe@114 | 28 | /** |
universe@114 | 29 | * Main UCX Header providing most common definitions. |
universe@114 | 30 | * |
universe@114 | 31 | * @file ucx.h |
universe@114 | 32 | * @author Olaf Wintermann |
universe@114 | 33 | */ |
olaf@5 | 34 | |
olaf@5 | 35 | #ifndef UCX_H |
olaf@5 | 36 | #define UCX_H |
olaf@5 | 37 | |
olaf@5 | 38 | #include <stdlib.h> |
olaf@5 | 39 | |
olaf@5 | 40 | #ifdef __cplusplus |
universe@65 | 41 | #ifndef _Bool |
universe@65 | 42 | #define _Bool bool |
universe@69 | 43 | #define restrict |
universe@65 | 44 | #endif |
olaf@5 | 45 | extern "C" { |
olaf@5 | 46 | #endif |
olaf@5 | 47 | |
universe@114 | 48 | /** |
universe@114 | 49 | * Generic loop statement for lists. |
universe@114 | 50 | * |
universe@114 | 51 | * The first argument is the type of the list and its elements (e.g. UcxList). |
universe@114 | 52 | * The structure invariant of the list must be as follows: |
universe@114 | 53 | * <ul> |
universe@114 | 54 | * <li>a first (non-<code>NULL</code>) element</li> |
universe@114 | 55 | * <li>for each element a reference to the <code>next</code> element (the |
universe@114 | 56 | * variable name of the pointer MUST be <code>next</code>)</li> |
universe@114 | 57 | * <li>the last element of the list MUST have the <code>next</code> pointer |
universe@114 | 58 | * set to <code>NULL</code></li> |
universe@114 | 59 | * </ul> |
universe@114 | 60 | * |
universe@114 | 61 | * The second argument is a pointer to the list. In most cases this will be the |
universe@114 | 62 | * pointer to the first element of the list, but it may also be an arbitrary |
universe@114 | 63 | * element of the list. The iteration will then start with that element. |
universe@114 | 64 | * |
universe@114 | 65 | * The third argument is the name of the iteration variable. The scope of |
universe@114 | 66 | * this variable is limited to the <code>UCX_FOREACH</code> statement. |
universe@114 | 67 | * |
universe@114 | 68 | * @param type The type of <b>both</b> the list and the element |
universe@114 | 69 | * @param list The first element of the list |
universe@114 | 70 | * @param elem The variable name of the element |
universe@114 | 71 | */ |
universe@26 | 72 | #define UCX_FOREACH(type,list,elem) \ |
universe@26 | 73 | for (type elem = list ; elem != NULL ; elem = elem->next) |
universe@69 | 74 | |
universe@114 | 75 | /** |
universe@114 | 76 | * Function pointer to a compare function. |
universe@114 | 77 | * |
universe@114 | 78 | * The compare function shall take three arguments: the two values that shall be |
universe@114 | 79 | * compared and optional additional data. |
universe@114 | 80 | * The function shall then return -1 if the first argument is less than the |
universe@114 | 81 | * second argument, 1 if the first argument is greater than the second argument |
universe@114 | 82 | * and 0 if both arguments are equal. If the third argument is |
universe@114 | 83 | * <code>NULL</code>, it shall be ignored. |
universe@114 | 84 | */ |
universe@18 | 85 | typedef int(*cmp_func)(void*,void*,void*); |
universe@18 | 86 | |
universe@114 | 87 | /** |
universe@114 | 88 | * Function pointer to a copy function. |
universe@114 | 89 | * |
universe@114 | 90 | * The copy function shall create a copy of the first argument and may use |
universe@114 | 91 | * additional data provided by the second argument. If the second argument is |
universe@114 | 92 | * <code>NULL</code>, it shall be ignored. |
universe@114 | 93 | |
universe@114 | 94 | * <b>Attention:</b> if pointers returned by functions of this type may be |
universe@114 | 95 | * passed to <code>free()</code> depends on the implementation of the |
universe@114 | 96 | * respective <code>copy_func</code>. |
universe@114 | 97 | */ |
universe@18 | 98 | typedef void*(*copy_func)(void*,void*); |
universe@18 | 99 | |
universe@114 | 100 | /** |
universe@114 | 101 | * Function pointer to a write function. |
universe@114 | 102 | * |
universe@114 | 103 | * The signature of the write function shall be compatible to the signature |
universe@114 | 104 | * of standard <code>fwrite</code>, though it may use arbitrary data types for |
universe@114 | 105 | * source and destination. |
universe@114 | 106 | * |
universe@114 | 107 | * The arguments shall contain (in ascending order): a pointer to the source, |
universe@114 | 108 | * the length of one element, the element count, a pointer to the destination. |
universe@114 | 109 | */ |
olaf@76 | 110 | typedef size_t(*write_func)(const void*, size_t, size_t, void*); |
olaf@76 | 111 | |
universe@114 | 112 | /** |
universe@114 | 113 | * Function pointer to a read function. |
universe@114 | 114 | * |
universe@114 | 115 | * The signature of the read function shall be compatible to the signature |
universe@114 | 116 | * of standard <code>fread</code>, though it may use arbitrary data types for |
universe@114 | 117 | * source and destination. |
universe@114 | 118 | * |
universe@114 | 119 | * The arguments shall contain (in ascending order): a pointer to the |
universe@114 | 120 | * destination, the length of one element, the element count, a pointer to the |
universe@114 | 121 | * source. |
universe@114 | 122 | */ |
olaf@76 | 123 | typedef size_t(*read_func)(void*, size_t, size_t, void*); |
olaf@76 | 124 | |
olaf@5 | 125 | #ifdef __cplusplus |
olaf@5 | 126 | } |
olaf@5 | 127 | #endif |
olaf@5 | 128 | |
olaf@5 | 129 | #endif /* UCX_H */ |
olaf@5 | 130 |