From faabdbb6dbc83c6540af8b7e6ba82ddea74f283e Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Thu, 5 Dec 2019 16:25:26 -0500
Subject: [PATCH] docs(schema): clarify that `uppercase`, `lowercase`, and
 `trim` options for SchemaString don't affect RegExp queries

Fix #8333
---
 lib/schema/string.js | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/lib/schema/string.js b/lib/schema/string.js
index 645c4c3571e..ff8a33a84d4 100644
--- a/lib/schema/string.js
+++ b/lib/schema/string.js
@@ -232,6 +232,14 @@ SchemaString.prototype.enum = function() {
  *     console.log(m.email) // someemail@example.com
  *     M.find({ email: 'SomeEmail@example.com' }); // Queries by 'someemail@example.com'
  *
+ * Note that `lowercase` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Still queries for documents whose `email` matches the regular
+ *     // expression /SomeEmail/. Mongoose does **not** convert the RegExp
+ *     // to lowercase.
+ *     M.find({ email: /SomeEmail/ });
+ *
  * @api public
  * @return {SchemaType} this
  */
@@ -262,6 +270,12 @@ SchemaString.prototype.lowercase = function(shouldApply) {
  *     console.log(m.caps) // AN EXAMPLE
  *     M.find({ caps: 'an example' }) // Matches documents where caps = 'AN EXAMPLE'
  *
+ * Note that `uppercase` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Mongoose does **not** convert the RegExp to uppercase.
+ *     M.find({ email: /an example/ });
+ *
  * @api public
  * @return {SchemaType} this
  */
@@ -288,12 +302,21 @@ SchemaString.prototype.uppercase = function(shouldApply) {
  *
  * ####Example:
  *
- *     var s = new Schema({ name: { type: String, trim: true }})
- *     var M = db.model('M', s)
- *     var string = ' some name '
- *     console.log(string.length) // 11
- *     var m = new M({ name: string })
- *     console.log(m.name.length) // 9
+ *     var s = new Schema({ name: { type: String, trim: true }});
+ *     var M = db.model('M', s);
+ *     var string = ' some name ';
+ *     console.log(string.length); // 11
+ *     var m = new M({ name: string });
+ *     console.log(m.name.length); // 9
+ *
+ *     // Equivalent to `findOne({ name: string.trim() })`
+ *     M.findOne({ name: string });
+ *
+ * Note that `trim` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Mongoose does **not** trim whitespace from the RegExp.
+ *     M.find({ name: / some name / });
  *
  * @api public
  * @return {SchemaType} this