root/include/crm/common/strings_internal.h

/* */

INCLUDED FROM

DEFINITIONS

1. pcmk__s
2. pcmk__intkey_table
3. pcmk__intkey_table_insert
4. pcmk__intkey_table_lookup
5. pcmk__intkey_table_remove
6. pcmk__g_strcat
7. pcmk__add_word
8. pcmk__str_empty
9. pcmk__itoa
10. pcmk__ftoa
11. pcmk__ttoa
12. pcmk__btoa

   1 /*
   2  * Copyright 2015-2024 the Pacemaker project contributors
   3  *
   4  * The version control history for this file may have further details.
   5  *
   6  * This source code is licensed under the GNU Lesser General Public License
   7  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
   8  */
   9 
  10 #ifndef PCMK__CRM_COMMON_STRINGS_INTERNAL__H
  11 #define PCMK__CRM_COMMON_STRINGS_INTERNAL__H
  12 
  13 #include <stdbool.h>            // bool
  14 #include <stdint.h>             // uint32_t, etc.
  15 
  16 #include <glib.h>               // guint, GList, GHashTable
  17 
  18 #include <crm/common/options.h> // PCMK_VALUE_TRUE, PCMK_VALUE_FALSE
  19 #include <crm/common/strings.h> // crm_strdup_printf()
  20 
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24 
  25 /* internal constants for generic string functions (from strings.c) */
  26 
  27 #define PCMK__PARSE_INT_DEFAULT -1
  28 #define PCMK__PARSE_DBL_DEFAULT -1.0
  29 
  30 /* internal generic string functions (from strings.c) */
  31 
  32 enum pcmk__str_flags {
  33     pcmk__str_none          = 0,
  34     pcmk__str_casei         = 1 << 0,
  35     pcmk__str_null_matches  = 1 << 1,
  36     pcmk__str_regex         = 1 << 2,
  37     pcmk__str_star_matches  = 1 << 3,
  38 };
  39 
  40 int pcmk__scan_double(const char *text, double *result,
  41                       const char *default_text, char **end_text);
  42 int pcmk__guint_from_hash(GHashTable *table, const char *key, guint default_val,
  43                           guint *result);
  44 bool pcmk__starts_with(const char *str, const char *prefix);
  45 bool pcmk__ends_with(const char *s, const char *match);
  46 bool pcmk__ends_with_ext(const char *s, const char *match);
  47 char *pcmk__trim(char *str);
  48 void pcmk__add_separated_word(GString **list, size_t init_size,
  49                               const char *word, const char *separator);
  50 int pcmk__compress(const char *data, unsigned int length, unsigned int max,
  51                    char **result, unsigned int *result_len);
  52 
  53 int pcmk__scan_ll(const char *text, long long *result, long long default_value);
  54 int pcmk__scan_min_int(const char *text, int *result, int minimum);
  55 int pcmk__scan_port(const char *text, int *port);
  56 int pcmk__parse_ll_range(const char *srcstring, long long *start, long long *end);
  57 
  58 GHashTable *pcmk__strkey_table(GDestroyNotify key_destroy_func,
  59                                GDestroyNotify value_destroy_func);
  60 GHashTable *pcmk__strikey_table(GDestroyNotify key_destroy_func,
  61                                 GDestroyNotify value_destroy_func);
  62 GHashTable *pcmk__str_table_dup(GHashTable *old_table);
  63 void pcmk__insert_dup(GHashTable *table, const char *name, const char *value);
  64 
  65 /*!
  66  * \internal
  67  * \brief Get a string value with a default if NULL
  68  *
  69  * \param[in] s              String to return if non-NULL
  70  * \param[in] default_value  String (or NULL) to return if \p s is NULL
  71  *
  72  * \return \p s if \p s is non-NULL, otherwise \p default_value
  73  */
  74 static inline const char *
  75 pcmk__s(const char *s, const char *default_value)
     /*  */
  76 {
  77     return (s == NULL)? default_value : s;
  78 }
  79 
  80 /*!
  81  * \internal
  82  * \brief Create a hash table with integer keys
  83  *
  84  * \param[in] value_destroy_func  Function to free a value
  85  *
  86  * \return Newly allocated hash table
  87  * \note It is the caller's responsibility to free the result, using
  88  *       g_hash_table_destroy().
  89  */
  90 static inline GHashTable *
  91 pcmk__intkey_table(GDestroyNotify value_destroy_func)
     /*  */
  92 {
  93     return g_hash_table_new_full(g_direct_hash, g_direct_equal, NULL,
  94                                  value_destroy_func);
  95 }
  96 
  97 /*!
  98  * \internal
  99  * \brief Insert a value into a hash table with integer keys
 100  *
 101  * \param[in,out] hash_table  Table to insert into
 102  * \param[in]     key         Integer key to insert
 103  * \param[in]     value       Value to insert
 104  *
 105  * \return Whether the key/value was already in the table
 106  * \note This has the same semantics as g_hash_table_insert(). If the key
 107  *       already exists in the table, the old value is freed and replaced.
 108  */
 109 static inline gboolean
 110 pcmk__intkey_table_insert(GHashTable *hash_table, int key, gpointer value)
     /*  */
 111 {
 112     return g_hash_table_insert(hash_table, GINT_TO_POINTER(key), value);
 113 }
 114 
 115 /*!
 116  * \internal
 117  * \brief Look up a value in a hash table with integer keys
 118  *
 119  * \param[in] hash_table  Table to check
 120  * \param[in] key         Integer key to look for
 121  *
 122  * \return Value in table for \key (or NULL if not found)
 123  */
 124 static inline gpointer
 125 pcmk__intkey_table_lookup(GHashTable *hash_table, int key)
     /*  */
 126 {
 127     return g_hash_table_lookup(hash_table, GINT_TO_POINTER(key));
 128 }
 129 
 130 /*!
 131  * \internal
 132  * \brief Remove a key/value from a hash table with integer keys
 133  *
 134  * \param[in,out] hash_table  Table to modify
 135  * \param[in]     key         Integer key of entry to remove
 136  *
 137  * \return Whether \p key was found and removed from \p hash_table
 138  */
 139 static inline gboolean
 140 pcmk__intkey_table_remove(GHashTable *hash_table, int key)
     /*  */
 141 {
 142     return g_hash_table_remove(hash_table, GINT_TO_POINTER(key));
 143 }
 144 
 145 gboolean pcmk__str_in_list(const gchar *s, const GList *lst, uint32_t flags);
 146 
 147 bool pcmk__strcase_any_of(const char *s, ...) G_GNUC_NULL_TERMINATED;
 148 bool pcmk__str_any_of(const char *s, ...) G_GNUC_NULL_TERMINATED;
 149 bool pcmk__char_in_any_str(int ch, ...) G_GNUC_NULL_TERMINATED;
 150 
 151 int pcmk__strcmp(const char *s1, const char *s2, uint32_t flags);
 152 int pcmk__numeric_strcasecmp(const char *s1, const char *s2);
 153 
 154 char *pcmk__str_copy_as(const char *file, const char *function, uint32_t line,
 155                         const char *str);
 156 
 157 /*!
 158  * \internal
 159  * \brief Copy a string, asserting on failure
 160  *
 161  * \param[in] str  String to copy (can be \c NULL)
 162  *
 163  * \return Newly allocated copy of \p str, or \c NULL if \p str is \c NULL
 164  *
 165  * \note The caller is responsible for freeing the return value using \c free().
 166  */
 167 #define pcmk__str_copy(str) pcmk__str_copy_as(__FILE__, __func__, __LINE__, str)
 168 
 169 void pcmk__str_update(char **str, const char *value);
 170 
 171 void pcmk__g_strcat(GString *buffer, ...) G_GNUC_NULL_TERMINATED;
     /*  */
 172 
 173 static inline bool
 174 pcmk__str_eq(const char *s1, const char *s2, uint32_t flags)
 175 {
 176     return pcmk__strcmp(s1, s2, flags) == 0;
 177 }
 178 
 179 // Like pcmk__add_separated_word() but using a space as separator
 180 static inline void
 181 pcmk__add_word(GString **list, size_t init_size, const char *word)
     /*  */
 182 {
 183     return pcmk__add_separated_word(list, init_size, word, " ");
 184 }
 185 
 186 /* Correctly displaying singular or plural is complicated; consider "1 node has"
 187  * vs. "2 nodes have". A flexible solution is to pluralize entire strings, e.g.
 188  *
 189  * if (a == 1) {
 190  *     crm_info("singular message"):
 191  * } else {
 192  *     crm_info("plural message");
 193  * }
 194  *
 195  * though even that's not sufficient for all languages besides English (if we
 196  * ever desire to do translations of output and log messages). But the following
 197  * convenience macros are "good enough" and more concise for many cases.
 198  */
 199 
 200 /* Example:
 201  * crm_info("Found %d %s", nentries,
 202  *          pcmk__plural_alt(nentries, "entry", "entries"));
 203  */
 204 #define pcmk__plural_alt(i, s1, s2) (((i) == 1)? (s1) : (s2))
 205 
 206 // Example: crm_info("Found %d node%s", nnodes, pcmk__plural_s(nnodes));
 207 #define pcmk__plural_s(i) pcmk__plural_alt(i, "", "s")
 208 
 209 static inline int
 210 pcmk__str_empty(const char *s)
     /*  */
 211 {
 212     return (s == NULL) || (s[0] == '\0');
 213 }
 214 
 215 static inline char *
 216 pcmk__itoa(int an_int)
     /*  */
 217 {
 218     return crm_strdup_printf("%d", an_int);
 219 }
 220 
 221 static inline char *
 222 pcmk__ftoa(double a_float)
     /*  */
 223 {
 224     return crm_strdup_printf("%f", a_float);
 225 }
 226 
 227 static inline char *
 228 pcmk__ttoa(time_t epoch_time)
     /*  */
 229 {
 230     return crm_strdup_printf("%lld", (long long) epoch_time);
 231 }
 232 
 233 // note this returns const not allocated
 234 static inline const char *
 235 pcmk__btoa(bool condition)
     /*  */
 236 {
 237     return condition? PCMK_VALUE_TRUE : PCMK_VALUE_FALSE;
 238 }
 239 
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243 
 244 #endif // PCMK__CRM_COMMON_STRINGS_INTERNAL__H

/* */