1 /********************************************************************\ 2 * gnc-glib-utils.c -- utility functions based on glib functions * 3 * Copyright (C) 2006 David Hampton <hampton@employees.org> * 4 * * 5 * This program is free software; you can redistribute it and/or * 6 * modify it under the terms of the GNU General Public License as * 7 * published by the Free Software Foundation; either version 2 of * 8 * the License, or (at your option) any later version. * 9 * * 10 * This program is distributed in the hope that it will be useful, * 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 13 * GNU General Public License for more details. * 14 * * 15 * You should have received a copy of the GNU General Public License* 16 * along with this program; if not, contact: * 17 * * 18 * Free Software Foundation Voice: +1-617-542-5942 * 19 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 20 * Boston, MA 02110-1301, USA gnu@gnu.org * 21 * * 22 \********************************************************************/ 23 24 /** @addtogroup GLib 25 @{ */ 26 /** @addtogroup Helpers GLib Helpers 27 28 The API in this file is designed to provide support functions that 29 wrap the base glib functions and make them easier to use. 30 31 @{ */ 32 /** @file gnc-glib-utils.h 33 * @brief GLib helper routines 34 * @author Copyright (C) 2006 David Hampton <hampton@employees.org> 35 */ 36 37 #ifndef GNC_GLIB_UTILS_H 38 #define GNC_GLIB_UTILS_H 39 40 #include <glib.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** @name Character Sets 47 @{ 48 */ 49 50 /** Collate two UTF-8 strings. This function performs basic argument 51 * checking before calling g_utf8_collate. 52 * 53 * @param str1 The first string. 54 * 55 * @param str2 The first string. 56 * 57 * @return Same return value as g_utf8_collate. The values are: < 0 58 * if str1 compares before str2, 0 if they compare equal, > 0 if str1 59 * compares after str2. */ 60 int safe_utf8_collate (const char *str1, const char *str2); 61 62 /** 63 * @brief Validates UTF-8 encoded text for use in GnuCash. 64 * 65 * Validates the strict subset of UTF-8 that is valid XML text, as detailed in 66 * https://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535. 67 * 68 * <em>Copied from g_utf8_validate():</em> 69 * 70 * Validates UTF-8 encoded text, where @a str is the text to validate; if 71 * @a str is nul-terminated, then @a max_len can be -1, otherwise @a max_len 72 * should be the number of bytes to validate. If @a end is non-%NULL, then the 73 * end of the valid range will be stored there (i.e. the start of the first 74 * invalid character if some bytes were invalid, or the end of the text being 75 * validated otherwise). 76 * 77 * Returns %TRUE if all of @a str was valid. Many GLib and GTK+ 78 * routines @e require valid UTF-8 as input; 79 * so data read from a file or the network should be checked 80 * with g_utf8_validate() before doing anything else with it. 81 * 82 * @param str a pointer to character data 83 * @param max_len max bytes to validate, or -1 to go until NUL 84 * @param end return location for end of valid data 85 * 86 * @return %TRUE if the text was valid UTF-8. 87 **/ 88 gboolean gnc_utf8_validate(const gchar *str, gssize max_len, const gchar **end); 89 90 /** Strip any non-UTF-8 characters from a string. This function 91 * rewrites the string "in place" instead of allocating and returning 92 * a new string. This allows it to operate on strings that are 93 * defined as character arrays in a larger data structure. Note that 94 * it also removes some subset of invalid XML characters, too. 95 * See https://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535 96 * 97 * @param str A pointer to the string to strip of invalid 98 * characters. */ 99 void gnc_utf8_strip_invalid (gchar *str); 100 101 /** Returns a newly allocated copy of the given string but with any 102 * non-UTF-8 character stripped from it. 103 * 104 * Note that it also removes some subset of invalid XML characters, 105 * too. See https://www.w3.org/TR/REC-xml/#NT-Char linked from bug 106 * #346535 107 * 108 * @param str A pointer to the string to be copied and stripped of 109 * non-UTF-8 characters. 110 * 111 * @return A newly allocated string that has to be g_free'd by the 112 * caller. */ 113 gchar *gnc_utf8_strip_invalid_strdup (const gchar* str); 114 115 /** Strip any non-utf8 characters and any control characters (everything < 0x20, 116 * \b, \f, \n, \r, \t, and \v) from a string. Rewrites the string in-place. 117 * 118 * @param str Pointer to the string to clean up. 119 */ 120 121 void gnc_utf8_strip_invalid_and_controls (gchar* str); 122 123 /** 124 * @brief Converts a string from UTF-8 to the encoding used for 125 * strings in the current locale. 126 * 127 * This essentially is a wrapper for g_locale_from_utf8 that can 128 * be swigified for use with Scheme to avoid adding a dependency 129 * for guile-glib. 130 * 131 * @param str A pointer to a UTF-8 encoded string to be converted. 132 * 133 * @return A newly allocated string that has to be g_free'd by the 134 * caller. If an error occurs, NULL is returned. */ 135 gchar *gnc_locale_from_utf8(const gchar* str); 136 137 /** 138 * @brief Converts a string to UTF-8 from the encoding used for 139 * strings in the current locale. 140 * 141 * This essentially is a wrapper for g_locale_to_utf8 that can 142 * be swigified for use with Scheme to avoid adding a dependency 143 * for guile-glib. 144 * 145 * @param str A pointer to a string encoded according to locale. 146 * 147 * @return A newly allocated string that has to be g_free'd by the 148 * caller. If an error occurs, NULL is returned. */ 149 gchar *gnc_locale_to_utf8(const gchar* str); 150 151 /** @} */ 152 153 /** @name GList Manipulation 154 @{ 155 */ 156 typedef gpointer (*GncGMapFunc)(gpointer data, gpointer user_data); 157 158 /** 159 * @return Caller-owned GList* of results of apply @a fn to @a list in order. 160 **/ 161 GList* gnc_g_list_map(GList* list, GncGMapFunc fn, gpointer user_data); 162 163 /** 164 * Cut a GList into two parts; the @a cut_point is the beginning of the 165 * new list; @a list may need to be modified, but will be the list 166 * before the @a cut_point. 167 **/ 168 void gnc_g_list_cut(GList **list, GList *cut_point); 169 170 /** @} */ 171 172 /** @name Message Logging 173 @{ 174 */ 175 void gnc_scm_log_warn(const gchar *msg); 176 void gnc_scm_log_error(const gchar *msg); 177 void gnc_scm_log_msg(const gchar *msg); 178 void gnc_scm_log_debug(const gchar *msg); 179 180 /** @} */ 181 182 /** @name glib Miscellaneous Functions 183 @{ 184 */ 185 186 187 /** 188 * @brief Return a string joining a GList whose elements are gchar* 189 * strings. Returns NULL if an empty GList* is passed through. The 190 * optional sep string will be used as separator. Must be g_freed when 191 * not needed anymore. 192 * 193 * @param list_of_strings A GList of chars* 194 * 195 * @param sep a separator or NULL 196 * 197 * @return A newly allocated string that has to be g_free'd by the 198 * caller. 199 **/ 200 gchar * gnc_g_list_stringjoin (GList *list_of_strings, const gchar *sep); 201 202 /** 203 * @brief Scans the GList elements the minimum number of iterations 204 * required to test it against a specified size. Returns -1, 0 or 1 205 * depending on whether the GList length has less, same, or more 206 * elements than the size specified. 207 * 208 * @param lst A GList 209 * 210 * @param len the comparator length to compare the GList length with 211 * 212 * @return A signed int comparing GList length with specified size. 213 **/ 214 gint gnc_list_length_cmp (const GList *list, size_t len); 215 216 /** Kill a process. On UNIX send a SIGKILL, on Windows call TerminateProcess. 217 * 218 * @param pid The process ID. */ 219 void gnc_gpid_kill(GPid pid); 220 221 /** @} */ 222 223 #ifdef __cplusplus 224 } /* extern "C" */ 225 #endif 226 227 #endif /* GNC_GLIB_UTILS_H */ 228 /** @} */ 229 /** @} */ 230