1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD 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 Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.MatchInfo; 26 27 private import glib.ErrorG; 28 private import glib.GException; 29 private import glib.Regex; 30 private import glib.Str; 31 private import glib.c.functions; 32 public import glib.c.types; 33 public import gtkc.glibtypes; 34 private import gtkd.Loader; 35 36 37 /** 38 * A GMatchInfo is an opaque struct used to return information about 39 * matches. 40 */ 41 public class MatchInfo 42 { 43 /** the main Gtk struct */ 44 protected GMatchInfo* gMatchInfo; 45 protected bool ownedRef; 46 47 /** Get the main Gtk struct */ 48 public GMatchInfo* getMatchInfoStruct(bool transferOwnership = false) 49 { 50 if (transferOwnership) 51 ownedRef = false; 52 return gMatchInfo; 53 } 54 55 /** the main Gtk struct as a void* */ 56 protected void* getStruct() 57 { 58 return cast(void*)gMatchInfo; 59 } 60 61 /** 62 * Sets our main struct and passes it to the parent class. 63 */ 64 public this (GMatchInfo* gMatchInfo, bool ownedRef = false) 65 { 66 this.gMatchInfo = gMatchInfo; 67 this.ownedRef = ownedRef; 68 } 69 70 ~this () 71 { 72 if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef ) 73 g_match_info_unref(gMatchInfo); 74 } 75 76 77 /** 78 * Returns a new string containing the text in @string_to_expand with 79 * references and escape sequences expanded. References refer to the last 80 * match done with @string against @regex and have the same syntax used by 81 * g_regex_replace(). 82 * 83 * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was 84 * passed to g_regex_new(). 85 * 86 * The backreferences are extracted from the string passed to the match 87 * function, so you cannot call this function after freeing the string. 88 * 89 * @match_info may be %NULL in which case @string_to_expand must not 90 * contain references. For instance "foo\n" does not refer to an actual 91 * pattern and '\n' merely will be replaced with \n character, 92 * while to expand "\0" (whole match) one needs the result of a match. 93 * Use g_regex_check_replacement() to find out whether @string_to_expand 94 * contains references. 95 * 96 * Params: 97 * stringToExpand = the string to expand 98 * 99 * Returns: the expanded string, or %NULL if an error occurred 100 * 101 * Since: 2.14 102 * 103 * Throws: GException on failure. 104 */ 105 public string expandReferences(string stringToExpand) 106 { 107 GError* err = null; 108 109 auto retStr = g_match_info_expand_references(gMatchInfo, Str.toStringz(stringToExpand), &err); 110 111 if (err !is null) 112 { 113 throw new GException( new ErrorG(err) ); 114 } 115 116 scope(exit) Str.freeString(retStr); 117 return Str.toString(retStr); 118 } 119 120 /** 121 * Retrieves the text matching the @match_num'th capturing 122 * parentheses. 0 is the full text of the match, 1 is the first paren 123 * set, 2 the second, and so on. 124 * 125 * If @match_num is a valid sub pattern but it didn't match anything 126 * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty 127 * string is returned. 128 * 129 * If the match was obtained using the DFA algorithm, that is using 130 * g_regex_match_all() or g_regex_match_all_full(), the retrieved 131 * string is not that of a set of parentheses but that of a matched 132 * substring. Substrings are matched in reverse order of length, so 133 * 0 is the longest match. 134 * 135 * The string is fetched from the string passed to the match function, 136 * so you cannot call this function after freeing the string. 137 * 138 * Params: 139 * matchNum = number of the sub expression 140 * 141 * Returns: The matched substring, or %NULL if an error 142 * occurred. You have to free the string yourself 143 * 144 * Since: 2.14 145 */ 146 public string fetch(int matchNum) 147 { 148 auto retStr = g_match_info_fetch(gMatchInfo, matchNum); 149 150 scope(exit) Str.freeString(retStr); 151 return Str.toString(retStr); 152 } 153 154 /** 155 * Bundles up pointers to each of the matching substrings from a match 156 * and stores them in an array of gchar pointers. The first element in 157 * the returned array is the match number 0, i.e. the entire matched 158 * text. 159 * 160 * If a sub pattern didn't match anything (e.g. sub pattern 1, matching 161 * "b" against "(a)?b") then an empty string is inserted. 162 * 163 * If the last match was obtained using the DFA algorithm, that is using 164 * g_regex_match_all() or g_regex_match_all_full(), the retrieved 165 * strings are not that matched by sets of parentheses but that of the 166 * matched substring. Substrings are matched in reverse order of length, 167 * so the first one is the longest match. 168 * 169 * The strings are fetched from the string passed to the match function, 170 * so you cannot call this function after freeing the string. 171 * 172 * Returns: a %NULL-terminated array of gchar * 173 * pointers. It must be freed using g_strfreev(). If the previous 174 * match failed %NULL is returned 175 * 176 * Since: 2.14 177 */ 178 public string[] fetchAll() 179 { 180 auto retStr = g_match_info_fetch_all(gMatchInfo); 181 182 scope(exit) Str.freeStringArray(retStr); 183 return Str.toStringArray(retStr); 184 } 185 186 /** 187 * Retrieves the text matching the capturing parentheses named @name. 188 * 189 * If @name is a valid sub pattern name but it didn't match anything 190 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") 191 * then an empty string is returned. 192 * 193 * The string is fetched from the string passed to the match function, 194 * so you cannot call this function after freeing the string. 195 * 196 * Params: 197 * name = name of the subexpression 198 * 199 * Returns: The matched substring, or %NULL if an error 200 * occurred. You have to free the string yourself 201 * 202 * Since: 2.14 203 */ 204 public string fetchNamed(string name) 205 { 206 auto retStr = g_match_info_fetch_named(gMatchInfo, Str.toStringz(name)); 207 208 scope(exit) Str.freeString(retStr); 209 return Str.toString(retStr); 210 } 211 212 /** 213 * Retrieves the position in bytes of the capturing parentheses named @name. 214 * 215 * If @name is a valid sub pattern name but it didn't match anything 216 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") 217 * then @start_pos and @end_pos are set to -1 and %TRUE is returned. 218 * 219 * Params: 220 * name = name of the subexpression 221 * startPos = pointer to location where to store 222 * the start position, or %NULL 223 * endPos = pointer to location where to store 224 * the end position, or %NULL 225 * 226 * Returns: %TRUE if the position was fetched, %FALSE otherwise. 227 * If the position cannot be fetched, @start_pos and @end_pos 228 * are left unchanged. 229 * 230 * Since: 2.14 231 */ 232 public bool fetchNamedPos(string name, out int startPos, out int endPos) 233 { 234 return g_match_info_fetch_named_pos(gMatchInfo, Str.toStringz(name), &startPos, &endPos) != 0; 235 } 236 237 /** 238 * Retrieves the position in bytes of the @match_num'th capturing 239 * parentheses. 0 is the full text of the match, 1 is the first 240 * paren set, 2 the second, and so on. 241 * 242 * If @match_num is a valid sub pattern but it didn't match anything 243 * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos 244 * and @end_pos are set to -1 and %TRUE is returned. 245 * 246 * If the match was obtained using the DFA algorithm, that is using 247 * g_regex_match_all() or g_regex_match_all_full(), the retrieved 248 * position is not that of a set of parentheses but that of a matched 249 * substring. Substrings are matched in reverse order of length, so 250 * 0 is the longest match. 251 * 252 * Params: 253 * matchNum = number of the sub expression 254 * startPos = pointer to location where to store 255 * the start position, or %NULL 256 * endPos = pointer to location where to store 257 * the end position, or %NULL 258 * 259 * Returns: %TRUE if the position was fetched, %FALSE otherwise. If 260 * the position cannot be fetched, @start_pos and @end_pos are left 261 * unchanged 262 * 263 * Since: 2.14 264 */ 265 public bool fetchPos(int matchNum, out int startPos, out int endPos) 266 { 267 return g_match_info_fetch_pos(gMatchInfo, matchNum, &startPos, &endPos) != 0; 268 } 269 270 /** 271 * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does 272 * nothing. 273 * 274 * Since: 2.14 275 */ 276 public void free() 277 { 278 g_match_info_free(gMatchInfo); 279 ownedRef = false; 280 } 281 282 /** 283 * Retrieves the number of matched substrings (including substring 0, 284 * that is the whole matched text), so 1 is returned if the pattern 285 * has no substrings in it and 0 is returned if the match failed. 286 * 287 * If the last match was obtained using the DFA algorithm, that is 288 * using g_regex_match_all() or g_regex_match_all_full(), the retrieved 289 * count is not that of the number of capturing parentheses but that of 290 * the number of matched substrings. 291 * 292 * Returns: Number of matched substrings, or -1 if an error occurred 293 * 294 * Since: 2.14 295 */ 296 public int getMatchCount() 297 { 298 return g_match_info_get_match_count(gMatchInfo); 299 } 300 301 /** 302 * Returns #GRegex object used in @match_info. It belongs to Glib 303 * and must not be freed. Use g_regex_ref() if you need to keep it 304 * after you free @match_info object. 305 * 306 * Returns: #GRegex object used in @match_info 307 * 308 * Since: 2.14 309 */ 310 public Regex getRegex() 311 { 312 auto p = g_match_info_get_regex(gMatchInfo); 313 314 if(p is null) 315 { 316 return null; 317 } 318 319 return new Regex(cast(GRegex*) p, true); 320 } 321 322 /** 323 * Returns the string searched with @match_info. This is the 324 * string passed to g_regex_match() or g_regex_replace() so 325 * you may not free it before calling this function. 326 * 327 * Returns: the string searched with @match_info 328 * 329 * Since: 2.14 330 */ 331 public string getString() 332 { 333 return Str.toString(g_match_info_get_string(gMatchInfo)); 334 } 335 336 /** 337 * Usually if the string passed to g_regex_match*() matches as far as 338 * it goes, but is too short to match the entire pattern, %FALSE is 339 * returned. There are circumstances where it might be helpful to 340 * distinguish this case from other cases in which there is no match. 341 * 342 * Consider, for example, an application where a human is required to 343 * type in data for a field with specific formatting requirements. An 344 * example might be a date in the form ddmmmyy, defined by the pattern 345 * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". 346 * If the application sees the user’s keystrokes one by one, and can 347 * check that what has been typed so far is potentially valid, it is 348 * able to raise an error as soon as a mistake is made. 349 * 350 * GRegex supports the concept of partial matching by means of the 351 * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags. 352 * When they are used, the return code for 353 * g_regex_match() or g_regex_match_full() is, as usual, %TRUE 354 * for a complete match, %FALSE otherwise. But, when these functions 355 * return %FALSE, you can check if the match was partial calling 356 * g_match_info_is_partial_match(). 357 * 358 * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and 359 * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered 360 * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a 361 * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching 362 * stops at the partial match. 363 * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD 364 * are set, the latter takes precedence. 365 * 366 * There were formerly some restrictions on the pattern for partial matching. 367 * The restrictions no longer apply. 368 * 369 * See pcrepartial(3) for more information on partial matching. 370 * 371 * Returns: %TRUE if the match was partial, %FALSE otherwise 372 * 373 * Since: 2.14 374 */ 375 public bool isPartialMatch() 376 { 377 return g_match_info_is_partial_match(gMatchInfo) != 0; 378 } 379 380 /** 381 * Returns whether the previous match operation succeeded. 382 * 383 * Returns: %TRUE if the previous match operation succeeded, 384 * %FALSE otherwise 385 * 386 * Since: 2.14 387 */ 388 public bool matches() 389 { 390 return g_match_info_matches(gMatchInfo) != 0; 391 } 392 393 /** 394 * Scans for the next match using the same parameters of the previous 395 * call to g_regex_match_full() or g_regex_match() that returned 396 * @match_info. 397 * 398 * The match is done on the string passed to the match function, so you 399 * cannot free it before calling this function. 400 * 401 * Returns: %TRUE is the string matched, %FALSE otherwise 402 * 403 * Since: 2.14 404 * 405 * Throws: GException on failure. 406 */ 407 public bool next() 408 { 409 GError* err = null; 410 411 auto p = g_match_info_next(gMatchInfo, &err) != 0; 412 413 if (err !is null) 414 { 415 throw new GException( new ErrorG(err) ); 416 } 417 418 return p; 419 } 420 421 /** 422 * Increases reference count of @match_info by 1. 423 * 424 * Returns: @match_info 425 * 426 * Since: 2.30 427 */ 428 public MatchInfo doref() 429 { 430 auto p = g_match_info_ref(gMatchInfo); 431 432 if(p is null) 433 { 434 return null; 435 } 436 437 return new MatchInfo(cast(GMatchInfo*) p, true); 438 } 439 440 /** 441 * Decreases reference count of @match_info by 1. When reference count drops 442 * to zero, it frees all the memory associated with the match_info structure. 443 * 444 * Since: 2.30 445 */ 446 public void unref() 447 { 448 g_match_info_unref(gMatchInfo); 449 } 450 }