From 219e0073389575a4022c7852a4ad06eabfb9cb5e Mon Sep 17 00:00:00 2001
From: Matt Mayer <matt@matthewmayer.co.uk>
Date: Mon, 11 Mar 2024 08:07:10 +0700
Subject: [PATCH] add better docs for removed methods

---
 docs/guide/upgrading_v9/2729.md | 40 +++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/guide/upgrading_v9/2729.md b/docs/guide/upgrading_v9/2729.md
index e003091592f..0e43183ca6f 100644
--- a/docs/guide/upgrading_v9/2729.md
+++ b/docs/guide/upgrading_v9/2729.md
@@ -6,3 +6,43 @@ Removed deprecated helpers methods
 | --------------------------------------- | -------------------------------------------------------------- |
 | `faker.helpers.replaceSymbolWithNumber` | `string.replace(/#+/g, (m) => faker.string.numeric(m.length))` |
 | `faker.helpers.regexpStyleStringParse`  | `faker.helpers.fromRegExp`                                     |
+
+Note these are not exact replacements:
+
+#### `faker.helpers.replaceSymbolWithNumber`
+
+The `replaceSymbolWithNumber` method was deprecated in Faker 8.4 and removed in 9.0. The method parsed the given string symbol by symbol and replaces the `#` symbol with digits (`0` - `9`) and the `!` symbol with digits >=2 (`2` - `9`). This was primarily used internally by Faker for generating phone numbers. If needed, you can use a simple string replace combined with `faker.string.numeric` to replace this
+
+```js
+// old
+faker.helpers.replaceSymbolWithNumber('#####-##'); // '04812-67'
+
+// new
+'#####-##'.replace(/#+/g, (m) => faker.string.numeric(m.length));
+
+// old
+faker.helpers.replaceSymbolWithNumber('!#####'); // '123152'
+
+// new
+'!#####'
+  .replace(/#+/g, (m) => faker.string.numeric(m.length))
+  .replace(/!+/g, (m) =>
+    faker.string.numeric({ length: m.length, exclude: ['0', '1'] })
+  );
+```
+
+#### `faker.helpers.regexpStyleStringParse`
+
+The `regexpStyleStringParse` method in `faker.helpers` was deprecated in Faker 8.1 and removed in 9.0. A likely replacement is the more powerful `faker.helpers.fromRegExp`.
+
+```js
+faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
+faker.helpers.fromRegExp('a{3,6}'); // aaaaa
+```
+
+However, please note that `faker.helpers.fromRegExp` is not an exact replacement for `faker.helpers.regexpStyleStringParse` as `fromRegExp` cannot handle numeric ranges. This will now need to be handled separately.
+
+```js
+faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
+faker.helpers.fromRegExp('a{3,6}') + faker.number.int({ min: 1, max: 100 });
+```