Mercurial > hg > ucx / changeset

     1.1 --- a/src/cx/buffer.h	Mon Dec 27 17:02:32 2021 +0100
     1.2 +++ b/src/cx/buffer.h	Mon Dec 27 17:16:32 2021 +0100
     1.3 @@ -90,9 +90,9 @@
     1.4      size_t size;
     1.5      /**
     1.6       * Flag register for buffer features.
     1.7 -     * \see #CX_BUFFER_DEFAULT
     1.8 -     * \see #CX_BUFFER_FREE_CONTENTS
     1.9 -     * \see #CX_BUFFER_AUTO_EXTEND
    1.10 +     * @see #CX_BUFFER_DEFAULT
    1.11 +     * @see #CX_BUFFER_FREE_CONTENTS
    1.12 +     * @see #CX_BUFFER_AUTO_EXTEND
    1.13       */
    1.14      int flags;
    1.15  } cx_buffer_s;
    1.16 @@ -109,11 +109,11 @@
    1.17   * Then this function will allocate the space and enforce
    1.18   * the #CX_BUFFER_FREE_CONTENTS flag.
    1.19   *
    1.20 - * \param space pointer to the memory area, or <code>NULL</code> to allocate
    1.21 + * @param space pointer to the memory area, or <code>NULL</code> to allocate
    1.22   * new memory
    1.23 - * \param capacity the capacity of the buffer
    1.24 - * \param flags buffer features (see cx_buffer_s.flags)
    1.25 - * \return the new buffer
    1.26 + * @param capacity the capacity of the buffer
    1.27 + * @param flags buffer features (see cx_buffer_s.flags)
    1.28 + * @return the new buffer
    1.29   */
    1.30  CxBuffer cxBufferCreate(
    1.31          void *space,
    1.32 @@ -127,7 +127,7 @@
    1.33   * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer
    1.34   * are also freed.
    1.35   *
    1.36 - * \param buffer the buffer to destroy
    1.37 + * @param buffer the buffer to destroy
    1.38   */
    1.39  void cxBufferDestroy(CxBuffer buffer);
    1.40  
    1.41 @@ -136,11 +136,11 @@
    1.42   *
    1.43   * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer.
    1.44   *
    1.45 - * \param src the source buffer
    1.46 - * \param start the start position of extraction
    1.47 - * \param length the count of bytes to extract (must not be zero)
    1.48 - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
    1.49 - * \return a new buffer containing the extraction
    1.50 + * @param src the source buffer
    1.51 + * @param start the start position of extraction
    1.52 + * @param length the count of bytes to extract (must not be zero)
    1.53 + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
    1.54 + * @return a new buffer containing the extraction
    1.55   */
    1.56  CxBuffer cxBufferExtract(
    1.57          CxBuffer src,
    1.58 @@ -152,9 +152,9 @@
    1.59  /**
    1.60   * A shorthand macro for copying an entire buffer.
    1.61   *
    1.62 - * \param src the source buffer
    1.63 - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
    1.64 - * \return a new buffer with the copied content
    1.65 + * @param src the source buffer
    1.66 + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
    1.67 + * @return a new buffer with the copied content
    1.68   */
    1.69  #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags)
    1.70  
    1.71 @@ -181,16 +181,16 @@
    1.72   * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and
    1.73   * cxBufferShiftRight() functions using a \c size_t as parameter type.
    1.74   *
    1.75 - * \par Security Note
    1.76 - * The shifting operation does \em not erase the previously occupied memory cells.
    1.77 - * You can easily do that manually, e.g. by calling
    1.78 + * \attention
    1.79 + * Security Note: The shifting operation does \em not erase the previously occupied memory cells.
    1.80 + * But you can easily do that manually, e.g. by calling
    1.81   * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or
    1.82   * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code>
    1.83   * for a left shift.
    1.84   *
    1.85 - * \param buffer the buffer
    1.86 - * \param shift the shift offset (negative means left shift)
    1.87 - * \return 0 on success, non-zero if a required auto-extension fails
    1.88 + * @param buffer the buffer
    1.89 + * @param shift the shift offset (negative means left shift)
    1.90 + * @return 0 on success, non-zero if a required auto-extension fails
    1.91   */
    1.92  int cxBufferShift(
    1.93          CxBuffer buffer,
    1.94 @@ -201,10 +201,10 @@
    1.95   * Shifts the buffer to the right.
    1.96   * See cxBufferShift() for details.
    1.97   *
    1.98 - * \param buffer the buffer
    1.99 - * \param shift the shift offset
   1.100 - * \return 0 on success, non-zero if a required auto-extension fails
   1.101 - * \see cxBufferShift()
   1.102 + * @param buffer the buffer
   1.103 + * @param shift the shift offset
   1.104 + * @return 0 on success, non-zero if a required auto-extension fails
   1.105 + * @see cxBufferShift()
   1.106   */
   1.107  int cxBufferShiftRight(
   1.108          CxBuffer buffer,
   1.109 @@ -218,10 +218,10 @@
   1.110   * \note Since a left shift cannot fail due to memory allocation problems, this
   1.111   * function always returns zero.
   1.112   *
   1.113 - * \param buffer the buffer
   1.114 - * \param shift the positive shift offset
   1.115 - * \return always zero
   1.116 - * \see cxBufferShift()
   1.117 + * @param buffer the buffer
   1.118 + * @param shift the positive shift offset
   1.119 + * @return always zero
   1.120 + * @see cxBufferShift()
   1.121   */
   1.122  int cxBufferShiftLeft(
   1.123          CxBuffer buffer,
   1.124 @@ -242,10 +242,10 @@
   1.125   * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position
   1.126   * unchanged (\c SEEK_CUR).
   1.127   *
   1.128 - * \param buffer the buffer
   1.129 - * \param offset position offset relative to \p whence
   1.130 - * \param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
   1.131 - * \return 0 on success, non-zero if the position is invalid
   1.132 + * @param buffer the buffer
   1.133 + * @param offset position offset relative to \p whence
   1.134 + * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
   1.135 + * @return 0 on success, non-zero if the position is invalid
   1.136   *
   1.137   */
   1.138  int cxBufferSeek(
   1.139 @@ -259,7 +259,7 @@
   1.140   *
   1.141   * The data is deleted by zeroing it with a call to memset().
   1.142   *
   1.143 - * \param buffer the buffer to be cleared
   1.144 + * @param buffer the buffer to be cleared
   1.145   */
   1.146  #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \
   1.147          (buffer)->size = 0; (buffer)->pos = 0;
   1.148 @@ -267,8 +267,8 @@
   1.149  /**
   1.150   * Tests, if the buffer position has exceeded the buffer capacity.
   1.151   *
   1.152 - * \param buffer the buffer to test
   1.153 - * \return non-zero, if the current buffer position has exceeded the last
   1.154 + * @param buffer the buffer to test
   1.155 + * @return non-zero, if the current buffer position has exceeded the last
   1.156   * available byte of the buffer.
   1.157   */
   1.158  int cxBufferEof(CxBuffer buffer);
   1.159 @@ -279,9 +279,9 @@
   1.160   *
   1.161   * If the current capacity is not sufficient, the buffer will be extended.
   1.162   *
   1.163 - * \param buffer the buffer
   1.164 - * \param capacity the minimum required capacity for this buffer
   1.165 - * \return 0 on success or a non-zero value on failure
   1.166 + * @param buffer the buffer
   1.167 + * @param capacity the minimum required capacity for this buffer
   1.168 + * @return 0 on success or a non-zero value on failure
   1.169   */
   1.170  int cxBufferMinimumCapacity(
   1.171          CxBuffer buffer,
   1.172 @@ -295,11 +295,11 @@
   1.173   *
   1.174   * \note The signature is compatible with the fwrite() family of functions.
   1.175   *
   1.176 - * \param ptr a pointer to the memory area containing the bytes to be written
   1.177 - * \param size the length of one element
   1.178 - * \param nitems the element count
   1.179 - * \param buffer the CxBuffer to write to
   1.180 - * \return the total count of bytes written
   1.181 + * @param ptr a pointer to the memory area containing the bytes to be written
   1.182 + * @param size the length of one element
   1.183 + * @param nitems the element count
   1.184 + * @param buffer the CxBuffer to write to
   1.185 + * @return the total count of bytes written
   1.186   */
   1.187  size_t cxBufferWrite(
   1.188          const void *ptr,
   1.189 @@ -315,11 +315,11 @@
   1.190   *
   1.191   * \note The signature is compatible with the fread() family of functions.
   1.192   *
   1.193 - * \param ptr a pointer to the memory area where to store the read data
   1.194 - * \param size the length of one element
   1.195 - * \param nitems the element count
   1.196 - * \param buffer the CxBuffer to read from
   1.197 - * \return the total number of elements read
   1.198 + * @param ptr a pointer to the memory area where to store the read data
   1.199 + * @param size the length of one element
   1.200 + * @param nitems the element count
   1.201 + * @param buffer the CxBuffer to read from
   1.202 + * @return the total number of elements read
   1.203   */
   1.204  size_t cxBufferRead(
   1.205          void *ptr,
   1.206 @@ -338,9 +338,9 @@
   1.207   *
   1.208   * On successful write, the position of the buffer is increased.
   1.209   *
   1.210 - * \param buffer the buffer to write to
   1.211 - * \param c the character to write
   1.212 - * \return the byte that has bean written or \c EOF when the end of the stream is
   1.213 + * @param buffer the buffer to write to
   1.214 + * @param c the character to write
   1.215 + * @return the byte that has bean written or \c EOF when the end of the stream is
   1.216   * reached and automatic extension is not enabled or not possible
   1.217   */
   1.218  int cxBufferPut(
   1.219 @@ -353,17 +353,17 @@
   1.220   *
   1.221   * The current position of the buffer is increased after a successful read.
   1.222   *
   1.223 - * \param buffer the buffer to read from
   1.224 - * \return the character or \c EOF, if the end of the buffer is reached
   1.225 + * @param buffer the buffer to read from
   1.226 + * @return the character or \c EOF, if the end of the buffer is reached
   1.227   */
   1.228  int cxBufferGet(CxBuffer buffer);
   1.229  
   1.230  /**
   1.231   * Writes a string to a buffer.
   1.232   *
   1.233 - * \param buffer the buffer
   1.234 - * \param str the zero-terminated string
   1.235 - * \return the number of bytes written
   1.236 + * @param buffer the buffer
   1.237 + * @param str the zero-terminated string
   1.238 + * @return the number of bytes written
   1.239   */
   1.240  size_t cxBufferPutString(
   1.241          CxBuffer buffer,

     2.1 --- a/src/cx/common.h	Mon Dec 27 17:02:32 2021 +0100
     2.2 +++ b/src/cx/common.h	Mon Dec 27 17:16:32 2021 +0100
     2.3 @@ -35,6 +35,46 @@
     2.4   * \author Olaf Wintermann
     2.5   * \version 3.0
     2.6   * \copyright 2-Clause BSD License
     2.7 + *
     2.8 + * \mainpage UAP Common Extensions
     2.9 + * Library with common and useful functions, macros and data structures.
    2.10 + * <p>
    2.11 + * Latest available source:<br>
    2.12 + * <a href="https://sourceforge.net/projects/ucx/files/">https://sourceforge.net/projects/ucx/files/</a>
    2.13 + * </p>
    2.14 + *
    2.15 + * <p>
    2.16 + * Repositories:<br>
    2.17 + * <a href="https://sourceforge.net/p/ucx/code">https://sourceforge.net/p/ucx/code</a>
    2.18 + * -&nbsp;or&nbsp;-
    2.19 + * <a href="https://develop.uap-core.de/hg/ucx">https://develop.uap-core.de/hg/ucx</a>
    2.20 + * </p>
    2.21 + *
    2.22 + * <h2>LICENCE</h2>
    2.23 + *
    2.24 + * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
    2.25 + *
    2.26 + * Redistribution and use in source and binary forms, with or without
    2.27 + * modification, are permitted provided that the following conditions are met:
    2.28 + *
    2.29 + *   1. Redistributions of source code must retain the above copyright
    2.30 + *      notice, this list of conditions and the following disclaimer.
    2.31 + *
    2.32 + *   2. Redistributions in binary form must reproduce the above copyright
    2.33 + *      notice, this list of conditions and the following disclaimer in the
    2.34 + *      documentation and/or other materials provided with the distribution.
    2.35 + *
    2.36 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    2.37 + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    2.38 + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    2.39 + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
    2.40 + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    2.41 + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    2.42 + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    2.43 + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    2.44 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    2.45 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    2.46 + * POSSIBILITY OF SUCH DAMAGE.
    2.47   */
    2.48  
    2.49  #ifndef UCX_COMMON_H

     3.1 --- a/src/cx/linked_list.h	Mon Dec 27 17:02:32 2021 +0100
     3.2 +++ b/src/cx/linked_list.h	Mon Dec 27 17:16:32 2021 +0100
     3.3 @@ -138,6 +138,7 @@
     3.4   *
     3.5   * @param node a pointer to a node in the list
     3.6   * @param loc_prev the location of the \c prev pointer
     3.7 + * @return a pointer to the first node
     3.8   */
     3.9  void *cx_linked_list_first(
    3.10          void *node,