Document query string behavior (#210)

fidian · blakeembrey · commit 43e87bf7bc6f · 2019-11-20T11:20:14.000-08:00
diff --git a/Readme.md b/Readme.md
@@ -45,7 +45,7 @@ const regexp = pathToRegexp("/foo/:bar", keys);
 // keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
 ```
 
-**Please note:** The `RegExp` returned by `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).
+**Please note:** The `RegExp` returned by `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc). When using paths that contain query strings, you need to escape the question mark (`?`) to ensure it does not flag the parameter as [optional](#optional).
 
 ### Parameters
 
@@ -138,6 +138,19 @@ regexp.exec("/test/route");
 
 **Tip:** The prefix is also optional, escape the prefix `\/` to make it required.
 
+When dealing with query strings, escape the question mark (`?`) so it doesn't mark the parameter as optional. Handling unordered data is outside the scope of this library.
+
+```js
+const regexp = pathToRegexp("/search/:tableName\\?useIndex=true&term=amazing");
+
+regexp.exec("/search/people?useIndex=true&term=amazing");
+//=> [ '/search/people?useIndex=true&term=amazing', 'people', index: 0, input: '/search/people?useIndex=true&term=amazing', groups: undefined ]
+
+// This library does not handle query strings in different orders
+regexp.exec("/search/people?term=amazing&useIndex=true");
+//=> null
+```
+
 ##### Zero or more
 
 Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches.
