include/a/version.h

   1 /*!
   2  @file version.h
   3  @brief algorithm library version
   4 */
   5
   6 #ifndef LIBA_VERSION_H
   7 #define LIBA_VERSION_H
   8
   9 #include "a.h"
  10
  11 /*!
  12  @ingroup liba
  13  @addtogroup a_version algorithm library version
  14  @{
  15 */
  16
  17 /*! algorithm library version major */
  18 #ifndef A_VERSION_MAJOR
  19 #define A_VERSION_MAJOR 0
  20 #endif /* A_VERSION_MAJOR */
  21 #undef major
  22
  23 /*! algorithm library version minor */
  24 #ifndef A_VERSION_MINOR
  25 #define A_VERSION_MINOR 1
  26 #endif /* A_VERSION_MINOR */
  27 #undef minor
  28
  29 /*! algorithm library version patch */
  30 #ifndef A_VERSION_PATCH
  31 #define A_VERSION_PATCH 14
  32 #endif /* A_VERSION_PATCH */
  33 #undef patch
  34
  35 /*! algorithm library version tweak */
  36 #ifndef A_VERSION_TWEAK
  37 #define A_VERSION_TWEAK 20240630
  38 #endif /* A_VERSION_TWEAK */
  39
  40 #define A_VERSION_TOSTR(X) A_CAST_1(X)
  41 /*! algorithm library version string */
  42 #ifndef A_VERSION
  43 #define A_VERSION A_VERSION_TOSTR(A_VERSION_MAJOR) "." A_VERSION_TOSTR(A_VERSION_MINOR) "." A_VERSION_TOSTR(A_VERSION_PATCH)
  44 #endif /* A_VERSION */
  45
  46 typedef struct a_version a_version;
  47 #define A_VERSION_0() A_VERSION_1(0)
  48 #define A_VERSION_1(major) A_VERSION_2(major, 0)
  49 #define A_VERSION_2(major, minor) A_VERSION_3(major, minor, 0)
  50 #define A_VERSION_3(major, minor, third) A_VERSION_4(major, minor, third, 0)
  51 // clang-format off
  52 #if defined(__cplusplus)
  53 #define A_VERSION_4(major, minor, third, extra) {major, minor, third, extra, {'.', 0, 0, 0}}
  54 #else /* !__cplusplus */
  55 #define A_VERSION_4(major, minor, third, extra) (a_version){major, minor, third, extra, {'.', 0, 0, 0}}
  56 #endif /* __cplusplus */
  57 // clang-format on
  58
  59 #if defined(__cplusplus)
  60 namespace a
  61 {
  62 typedef a_version version;
  63 } /* namespace a */
  64 extern "C" {
  65 #endif /* __cplusplus */
  66
  67 /*! algorithm library version major */
  68 A_EXTERN unsigned int const a_version_major;
  69 /*! algorithm library version minor */
  70 A_EXTERN unsigned int const a_version_minor;
  71 /*! algorithm library version patch */
  72 A_EXTERN unsigned int const a_version_patch;
  73 /*! algorithm library version tweak */
  74 A_EXTERN a_u32 const a_version_tweak;
  75
  76 /*!
  77  @brief algorithm library version check
  78  @param[in] major required major number
  79  @param[in] minor required minor number
  80  @param[in] patch required patch number
  81  @return result of comparison
  82   @retval <0 library version is higher than required version
  83   @retval >0 library version is lower than required version
  84   @retval 0 library version is equal to required version
  85 */
  86 A_EXTERN int a_version_check(unsigned int major, unsigned int minor, unsigned int patch);
  87 #define A_VERSION_CHECK() a_version_check(A_VERSION_MAJOR, A_VERSION_MINOR, A_VERSION_PATCH)
  88
  89 /*!
  90  @brief convert version to string
  91  @param[in] ctx points to an instance structure for version
  92  @param[in] pdata points to string buffer
  93  @param[in] nbyte length of string buffer
  94  @return number of used characters
  95 */
  96 A_EXTERN unsigned int a_version_tostr(a_version const *ctx, void *pdata, a_size nbyte);
  97
  98 /*!
  99  @brief parse version string to version
 100  @param[in,out] ctx points to an instance structure for version
 101  @param[in] ver version string to be parsed
 102  @return number of parsed characters
 103 */
 104 A_EXTERN unsigned int a_version_parse(a_version *ctx, char const *ver);
 105
 106 /*!
 107  @brief compare the version `lhs` with the version `rhs`
 108  @param[in] lhs version structure to be compared
 109  @param[in] rhs version structure to be compared
 110  @return relationship between the versions
 111   @retval <0 version `lhs` < version `rhs`
 112   @retval >0 version `lhs` > version `rhs`
 113   @retval 0 version `lhs` == version `rhs`
 114 */
 115 A_EXTERN int a_version_cmp(a_version const *lhs, a_version const *rhs);
 116
 117 /*!
 118  @brief version lhs is less than version rhs
 119  @param[in] lhs operand on the left
 120  @param[in] rhs operand on the right
 121  @return result of comparison
 122 */
 123 A_EXTERN a_bool a_version_lt(a_version const *lhs, a_version const *rhs);
 124
 125 /*!
 126  @brief version lhs is greater than version rhs
 127  @param[in] lhs operand on the left
 128  @param[in] rhs operand on the right
 129  @return result of comparison
 130 */
 131 A_EXTERN a_bool a_version_gt(a_version const *lhs, a_version const *rhs);
 132
 133 /*!
 134  @brief version lhs is less than or equal to version rhs
 135  @param[in] lhs operand on the left
 136  @param[in] rhs operand on the right
 137  @return result of comparison
 138 */
 139 A_EXTERN a_bool a_version_le(a_version const *lhs, a_version const *rhs);
 140
 141 /*!
 142  @brief version lhs is greater than or equal to version rhs
 143  @param[in] lhs operand on the left
 144  @param[in] rhs operand on the right
 145  @return result of comparison
 146 */
 147 A_EXTERN a_bool a_version_ge(a_version const *lhs, a_version const *rhs);
 148
 149 /*!
 150  @brief version lhs is equal to version rhs
 151  @param[in] lhs operand on the left
 152  @param[in] rhs operand on the right
 153  @return result of comparison
 154 */
 155 A_EXTERN a_bool a_version_eq(a_version const *lhs, a_version const *rhs);
 156
 157 /*!
 158  @brief version lhs is not equal to version rhs
 159  @param[in] lhs operand on the left
 160  @param[in] rhs operand on the right
 161  @return result of comparison
 162 */
 163 A_EXTERN a_bool a_version_ne(a_version const *lhs, a_version const *rhs);
 164
 165 /*!
 166  @brief set alphabet for version
 167  @param[in,out] ctx points to an instance structure for version
 168  @param[in] alpha new alphabet
 169 */
 170 A_EXTERN void a_version_set_alpha(a_version *ctx, char const *alpha);
 171
 172 /*!
 173  @brief get alphabet for version
 174  @param[in] ctx points to an instance structure for version
 175  @param[out] alpha string buffer, >sizeof(ctx->alpha)
 176 */
 177 A_EXTERN void a_version_alpha(a_version const *ctx, char alpha[5]);
 178
 179 #if defined(__cplusplus)
 180 } /* extern "C" */
 181 #endif /* __cplusplus */
 182
 183 /*!
 184  @brief instance structure for version
 185 */
 186 struct a_version
 187 {
 188     unsigned int major; //!< major number
 189     unsigned int minor; //!< minor number
 190     unsigned int third; //!< third number
 191     unsigned int extra; //!< extra number
 192     char alpha_[4]; //!< alphabet
 193 #if defined(__cplusplus)
 194     A_INLINE void alpha(char str[5]) const
 195     {
 196         a_version_alpha(this, str);
 197     }
 198     A_INLINE void set_alpha(char const *str)
 199     {
 200         a_version_set_alpha(this, str);
 201     }
 202     A_INLINE unsigned int parse(char const *ver)
 203     {
 204         return a_version_parse(this, ver);
 205     }
 206     A_INLINE unsigned int tostr(void *p, a_size n) const
 207     {
 208         return a_version_tostr(this, p, n);
 209     }
 210     A_INLINE bool operator<(a_version const &ver) const
 211     {
 212         return a_version_lt(this, &ver);
 213     }
 214     A_INLINE bool operator>(a_version const &ver) const
 215     {
 216         return a_version_gt(this, &ver);
 217     }
 218     A_INLINE bool operator<=(a_version const &ver) const
 219     {
 220         return a_version_le(this, &ver);
 221     }
 222     A_INLINE bool operator>=(a_version const &ver) const
 223     {
 224         return a_version_ge(this, &ver);
 225     }
 226     A_INLINE bool operator==(a_version const &ver) const
 227     {
 228         return a_version_eq(this, &ver);
 229     }
 230     A_INLINE bool operator!=(a_version const &ver) const
 231     {
 232         return a_version_ne(this, &ver);
 233     }
 234     A_INLINE int cmp(a_version const &ver) const
 235     {
 236         return a_version_cmp(this, &ver);
 237     }
 238 #endif /* __cplusplus */
 239 };
 240
 241 /*! @} a_version */
 242
 243 #endif /* a/version.h */