Document pattern matching interface (#499)

docs/api/mg_match.md

@@ -0,0 +1,63 @@
+# Civetweb API Reference
+
+### `struct mg_match_element;`
+### `struct mg_match_context;`
+### `mg_match( pat, str, mcx );`
+
+### Parameters of `mg_match()`
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`pat`**|`const char *`|A pattern string to search for.|
+|**`str`**|`const char *`|The pattern will be searched in this string.|
+|**`mcx`**|`struct mg_match_context *`|Pointer to a "match context" structure. Optional: can be NULL.|
+
+### Fields of `struct mg_match_context`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+|**`case_sensitive`**|`int`| Input: 1 for case sensitive or for 0 insensitive match. |
+|**`num_matches`**|`size_t`| Output: Number of wildcard matches found in `str`. |
+|**`match`**|`struct mg_match_element[]`| Output: This array is filled with matches. |
+
+In case `mcx` is not provided to `mg_match()` (a NULL pointer is provided), case insensitive pattern matching will be performed. The wildcard matches will not be stored.
+
+The size of the `match` array is defined by the compile time constant `MG_MATCH_CONTEXT_MAX_MATCHES`.
+
+### Fields of `struct mg_match_element`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+|**`str`**|`const char *`| Pointer to the begin of a wildcard match in `str`. |
+|**`len`**|`size_t`| Length of the wildcard match. |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`ptrdiff_t`| Number of characters matched, counting from the beginning or `str`. If the pattern does not match -1 is returned. Note that 0 may be a valid match for some patterns. |
+
+### Description
+
+Pattern matching function. Try to find characters matching pattern `pat` in string `str`.
+A definition of valid pattern can be found in the [User Manual](../UserManual.md).
+
+E.g.:
+`mg_match("**.cgi$", "anywhere/anyname.cgi", NULL)` will return 20 (`strlen(str)`).
+
+`mg_match("**.cgi$", "anywhere/anyname.cgi", &mcx)` will return 20 (`strlen(str)`). 
+Furthermore will set `mcx.match[0].str` to point to the first match "anywhere/anyname" (that is `str+0`)
+and `mcx.match[0].len` to 16 (`strlen("anywhere/anyname")`), but it will not terminate the string.
+The value of `mcx.num_matches` is 1, since the only wildcard pattern `**` matches everything.
+
+`mg_match("a?*/?*g", "ABC/DEFG", &mcx)` with `mcx.case_sensitive = 0` will return 8 (`strlen(str)`).
+The value of `mcx.num_matches` is 2, one for each `?*` wildcard.
+The first match `mcx.match[0].str` will point to "BC" (`str+1`) and `mcx.match[0].len == 2`.
+The second match `mcx.match[1].str` will point to "DEF" (`str+4`) and `mcx.match[1].len == 3`.
+
+Note: This is an experimental interface. 
+Structure definitions may change in future versions.
+
+### See Also
+
+* Pattern Matching in the [User Manual](../UserManual.md).

src/match.inl

@@ -63,7 +63,7 @@ mg_match_impl(const char *pat,
 
 		/* Pattern $ matches end of string */
 		if (pat[i_pat] == '$') {
-			return (str[i_str] == '\0') ? i_str : -1;
+			return (str[i_str] == '\0') ? (ptrdiff_t)i_str : -1;
 		}
 
 		/* Pattern * or ** matches multiple characters */