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  * ADG_UTF8_DEGREE:
 107  *
 108  * String constant that embeds a UTF-8 encoded degree symbol (U+00B0).
 109  * It is used to suffix by the default implementation of #AdgADim to
 110  * suffix the set value, but can be also used manually:
 111  *
 112  * |[
 113  * adg_dim_set_value(dim, "<>" ADG_UTF8_DEGREE);
 114  * ]|
 115  **/
 116
 117
 118 #include "adg-internal.h"
 119 #include "adg-utils.h"
 120 #include <string.h>
 121 #include <limits.h>
 122
 123
 124 #if GLIB_CHECK_VERSION(2, 16, 0)
 125 #else
 126 /**
 127  * g_strcmp0:
 128  * @str1: a C string or %NULL
 129  * @str2: another C string or %NULL
 130  *
 131  * Compares @str1 and @str2 like strcmp(). Handles %NULL
 132  * gracefully by sorting it before non-%NULL strings.
 133  * This is a backward compatibility fallback for GLib
 134  * prior to 2.16.0
 135  *
 136  * Returns: -1, 0 or 1, if @str1 is <, == or > than @str2.
 137  */
 138 int
 139 g_strcmp0(const char *str1, const char *str2)
 140 {
 141     if (!str1)
 142         return -(str1 != str2);
 143
 144     if (!str2)
 145         return str1 != str2;
 146
 147     return strcmp(str1, str2);
 148 }
 149 #endif
 150
 151 /**
 152  * adg_is_string_empty:
 153  * @str: the subject string
 154  *
 155  * Checks if @str is an empty string, that is if is %NULL or if
 156  * its first character is %'\0'.
 157  *
 158  * Returns: %TRUE if @str is an empty string, %FALSE otherwise
 159  **/
 160 gboolean
 161 adg_is_string_empty(const gchar *str)
 162 {
 163     return str == NULL || str[0] == '\0';
 164 }
 165
 166 /**
 167  * adg_is_enum_value:
 168  * @value: the enum value to check
 169  * @enum_type: a #GEnum based type
 170  *
 171  * Checks if @value is a valid @enum_type value.
 172  *
 173  * Returns: %TRUE if @value is a valid @enum_type, %FALSE otherwise
 174  **/
 175 gboolean
 176 adg_is_enum_value(int value, GType enum_type)
 177 {
 178     GEnumClass *enum_class;
 179     gboolean found;
 180
 181     enum_class = g_type_class_ref(enum_type);
 182     g_return_val_if_fail(enum_class != NULL, FALSE);
 183
 184     found = FALSE;
 185
 186     if (value >= enum_class->minimum && value <= enum_class->maximum) {
 187         GEnumValue *enum_value;
 188         guint n;
 189
 190         for (n = 0; !found && n < enum_class->n_values; ++n) {
 191             enum_value = enum_class->values + n;
 192             found = value == enum_value->value;
 193         }
 194     }
 195
 196     g_type_class_unref(enum_class);
 197
 198     return found;
 199 }
 200
 201 /**
 202  * adg_is_boolean_value:
 203  * @value: the gboolean value to check
 204  *
 205  * Checks if @value is a valid #gboolean value, that is if it is %TRUE
 206  * or %FALSE. No other values are accepted.
 207  *
 208  * Returns: %TRUE if @value is a valid #gboolean, %FALSE otherwise
 209  **/
 210 gboolean
 211 adg_is_boolean_value(gboolean value)
 212 {
 213     return value == TRUE || value == FALSE;
 214 }
 215
 216 /**
 217  * adg_string_replace:
 218  * @str: the original string
 219  * @from: the substring to replace
 220  * @to: the replacement string
 221  *
 222  * Replaces @from with @to inside @str and returns the result as a
 223  * newly allocated string.
 224  *
 225  * @str and @from must be non-null valid C strings while @to can be
 226  * %NULL, in which case an empty string ("") will be implied.
 227  *
 228  * Returns: a newly allocated string to be freed with g_free() or
 229  *          %NULL on errors
 230  **/
 231 gchar *
 232 adg_string_replace(const gchar *str, const gchar *from, const gchar *to)
 233 {
 234     gchar *result;
 235     int from_len;
 236     gchar *ptr, *old_result;
 237
 238     g_return_val_if_fail(str != NULL, NULL);
 239     g_return_val_if_fail(from != NULL, NULL);
 240
 241     from_len = strlen(from);
 242
 243     g_return_val_if_fail(from_len > 0, NULL);
 244
 245     if (to == NULL)
 246         to = "";
 247
 248     result = g_strdup(str);
 249
 250     while ((ptr = strstr(result, from)) != NULL) {
 251         *ptr = '\0';
 252         old_result = result;
 253         result = g_strconcat(old_result, to, ptr + from_len, NULL);
 254         g_free(old_result);
 255     }
 256
 257     return result;
 258 }