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