src/adg/adg-utils.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009,2010  Nicola Fontana <ntd at entidi.it>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17  * Boston, MA  02110-1301, USA.
  18  */
  19
  20
  21 /**
  22  * SECTION:adg-utils
  23  * @Section_Id:utilities
  24  * @title: Utilities
  25  * @short_description: Assorted macros and functions
  26  *
  27  * Collection of macros and functions that do not fit inside any other topic.
  28  **/
  29
  30 /**
  31  * ADG_FORWARD_DECL:
  32  * @id: The name of a struct
  33  *
  34  * Forward declaration of struct @id. It is equivalent to a typical
  35  * struct forward declaration, for example:
  36  *
  37  * |[
  38  * ADG_FORWARD_DECL(test)
  39  * ]|
  40  *
  41  * will expand to:
  42  *
  43  * |[
  44  * typedef struct _test test
  45  * ]|
  46  *
  47  * This macro is needed to fake <command>gtk-doc</command>, because
  48  * up to now (v.1.12) it generates two conflicting links when using
  49  * forward declarations: the first in the source with the declaration
  50  * and the second where the type is defined. Using ADG_FORWARD_DECL()
  51  * instead of the usual typedef avoids the parsing of the declaration
  52  * in the first file (<command>gtk-doc</command> is not able to do C
  53  * preprocessing).
  54  *
  55  * The same principle can be applied in the definition file. Following
  56  * the previous example, you can use something like this where struct
  57  * _type is defined:
  58  *
  59  * |[
  60  * #if 0
  61  * // This is declared in another file
  62  * typedef struct _type type;
  63  * #endif
  64  * struct _type {
  65  * ...
  66  * };
  67  * ]|
  68  **/
  69
  70 /**
  71  * ADG_DIR_RIGHT:
  72  *
  73  * Symbolic constant for the right direction (in radians).
  74  **/
  75
  76 /**
  77  * ADG_DIR_DOWN:
  78  *
  79  * Symbolic constant for the down direction (in radians).
  80  **/
  81
  82 /**
  83  * ADG_DIR_LEFT:
  84  *
  85  * Symbolic constant for the left direction (in radians).
  86  **/
  87
  88 /**
  89  * ADG_DIR_UP:
  90  *
  91  * Symbolic constant for the up direction (in radians).
  92  **/
  93
  94 /**
  95  * ADG_UTF8_DIAMETER:
  96  *
  97  * String constant that embeds a UTF-8 encoded diameter (U+2300).
  98  * It can be used to prefix diameter quotes, such as:
  99  *
 100  * |[
 101  * adg_dim_set_value(dim, ADG_UTF8_DIAMETER "<>");
 102  * ]|
 103  **/
 104
 105
 106 #include "adg-internal.h"
 107 #include "adg-utils.h"
 108 #include <string.h>
 109 #include <limits.h>
 110
 111
 112 #if GLIB_CHECK_VERSION(2, 16, 0)
 113 #else
 114 /**
 115  * g_strcmp0:
 116  * @str1: a C string or %NULL
 117  * @str2: another C string or %NULL
 118  *
 119  * Compares @str1 and @str2 like strcmp(). Handles %NULL
 120  * gracefully by sorting it before non-%NULL strings.
 121  * This is a backward compatibility fallback for GLib
 122  * prior to 2.16.0
 123  *
 124  * Returns: -1, 0 or 1, if @str1 is <, == or > than @str2.
 125  */
 126 int
 127 g_strcmp0(const char *str1, const char *str2)
 128 {
 129     if (!str1)
 130         return -(str1 != str2);
 131
 132     if (!str2)
 133         return str1 != str2;
 134
 135     return strcmp(str1, str2);
 136 }
 137 #endif
 138
 139 /**
 140  * adg_is_string_empty:
 141  * @str: the subject string
 142  *
 143  * Checks if @str is an empty string, that is if is %NULL or if
 144  * its first character is %'\0'.
 145  *
 146  * Returns: %TRUE if @str is an empty string, %FALSE otherwise
 147  **/
 148 gboolean
 149 adg_is_string_empty(const gchar *str)
 150 {
 151     return str == NULL || str[0] == '\0';
 152 }
 153
 154 /**
 155  * adg_is_enum_value:
 156  * @value: the enum value to check
 157  * @enum_type: a #GEnum based type
 158  *
 159  * Checks if @value is a valid @enum_type value.
 160  *
 161  * Returns: %TRUE if @value is a valid @enum_type, %FALSE otherwise
 162  **/
 163 gboolean
 164 adg_is_enum_value(int value, GType enum_type)
 165 {
 166     GEnumClass *enum_class;
 167     gboolean found;
 168
 169     enum_class = g_type_class_ref(enum_type);
 170     g_return_val_if_fail(enum_class != NULL, FALSE);
 171
 172     found = FALSE;
 173
 174     if (value >= enum_class->minimum && value <= enum_class->maximum) {
 175         GEnumValue *enum_value;
 176         guint n;
 177
 178         for (n = 0; !found && n < enum_class->n_values; ++n) {
 179             enum_value = enum_class->values + n;
 180             found = value == enum_value->value;
 181         }
 182     }
 183
 184     g_type_class_unref(enum_class);
 185
 186     return found;
 187 }
 188
 189 /**
 190  * adg_is_boolean_value:
 191  * @value: the gboolean value to check
 192  *
 193  * Checks if @value is a valid #gboolean value, that is if it is %TRUE
 194  * or %FALSE. No other values are accepted.
 195  *
 196  * Returns: %TRUE if @value is a valid #gboolean, %FALSE otherwise
 197  **/
 198 gboolean
 199 adg_is_boolean_value(gboolean value)
 200 {
 201     return value == TRUE || value == FALSE;
 202 }
 203
 204 /**
 205  * adg_string_replace:
 206  * @str: the original string
 207  * @from: the substring to replace
 208  * @to: the replacement string
 209  *
 210  * Replaces @from with @to inside @str and returns the result as a
 211  * newly allocated string.
 212  *
 213  * @str and @from must be non-null valid C strings while @to can be
 214  * %NULL, in which case an empty string ("") will be implied.
 215  *
 216  * Returns: a newly allocated string to be freed with g_free() or
 217  *          %NULL on errors
 218  **/
 219 gchar *
 220 adg_string_replace(const gchar *str, const gchar *from, const gchar *to)
 221 {
 222     gchar *result;
 223     int from_len;
 224     gchar *ptr, *old_result;
 225
 226     g_return_val_if_fail(str != NULL, NULL);
 227     g_return_val_if_fail(from != NULL, NULL);
 228
 229     from_len = strlen(from);
 230
 231     g_return_val_if_fail(from_len > 0, NULL);
 232
 233     if (to == NULL)
 234         to = "";
 235
 236     result = g_strdup(str);
 237
 238     while ((ptr = strstr(result, from)) != NULL) {
 239         *ptr = '\0';
 240         old_result = result;
 241         result = g_strconcat(old_result, to, ptr + from_len, NULL);
 242         g_free(old_result);
 243     }
 244
 245     return result;
 246 }