lib Fix Part 4/6 – String.replaceAll and related changes

src/lib/es2015.core.d.ts

@@ -194,7 +194,7 @@ interface NumberConstructor {
     /**
      * The value of Number.EPSILON is the difference between 1 and the smallest value greater than 1
      * that is representable as a Number value, which is approximately:
-     * 2.2204460492503130808472633361816 x 10‍−‍16.
+     * 2.2204460492503130808472633361816E−‍16 (2^-52).
      */
     readonly EPSILON: number;
 
@@ -229,14 +229,14 @@ interface NumberConstructor {
     /**
      * The value of the largest integer n such that n and n + 1 are both exactly representable as
      * a Number value.
-     * The value of Number.MAX_SAFE_INTEGER is 9007199254740991 2^53 − 1.
+     * The value of Number.MAX_SAFE_INTEGER is 9007199254740991 (2^53 − 1).
      */
     readonly MAX_SAFE_INTEGER: number;
 
     /**
      * The value of the smallest integer n such that n and n − 1 are both exactly representable as
      * a Number value.
-     * The value of Number.MIN_SAFE_INTEGER is −9007199254740991 (−(2^53 − 1)).
+     * The value of Number.MIN_SAFE_INTEGER is −9007199254740991 (−2^53 + 1).
      */
     readonly MIN_SAFE_INTEGER: number;
 
@@ -379,11 +379,11 @@ interface RegExpConstructor {
 
 interface String {
     /**
-     * Returns a nonnegative integer Number less than 1114112 (0x110000) that is the code point
-     * value of the UTF-16 encoded code point starting at the string element at position pos in
-     * the String resulting from converting this object to a String.
-     * If there is no element at that position, the result is undefined.
-     * If a valid UTF-16 surrogate pair does not begin at pos, the result is the code unit at pos.
+     * Returns a non-negative integer less than 1114112 (0x110000) that is the code point value
+     * starting at the string element at the specified position.
+     * @param pos The zero-based index of the desired code point. If there is no character at the
+     * specified index, undefined is returned. If a UTF-16 surrogate pair does not begin at pos,
+     * the result is the code unit at pos.
      */
     codePointAt(pos: number): number | undefined;
 
@@ -397,46 +397,38 @@ interface String {
     includes(searchString: string, position?: number): boolean;
 
     /**
-     * Returns true if the sequence of elements of searchString converted to a String is the
-     * same as the corresponding elements of this object (converted to a String) starting at
-     * endPosition – length(this). Otherwise returns false.
+     * Determines whether the string ends with a substring, ending at the specified index.
+     * @param searchString The string to search for.
+     * @param endPosition The index at which to begin searching for. The default value is the
+     * length of searchString.
      */
     endsWith(searchString: string, endPosition?: number): boolean;
 
     /**
      * Returns the String value result of normalizing the string into the normalization form
      * named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.
-     * @param form Applicable values: "NFC", "NFD", "NFKC", or "NFKD", If not specified default
-     * is "NFC"
+     * @param form The normalization form to be used. The default value is "NFC".
      */
-    normalize(form: "NFC" | "NFD" | "NFKC" | "NFKD"): string;
-
-    /**
-     * Returns the String value result of normalizing the string into the normalization form
-     * named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.
-     * @param form Applicable values: "NFC", "NFD", "NFKC", or "NFKD", If not specified default
-     * is "NFC"
-     */
-    normalize(form?: string): string;
+    normalize(form?: "NFC" | "NFD" | "NFKC" | "NFKD"): string;
 
     /**
      * Returns a String value that is made from count copies appended together. If count is 0,
      * the empty string is returned.
-     * @param count number of copies to append
+     * @param count The number of copies to append
      */
     repeat(count: number): string;
 
     /**
-     * Returns true if the sequence of elements of searchString converted to a String is the
-     * same as the corresponding elements of this object (converted to a String) starting at
-     * position. Otherwise returns false.
+     * Determines whether the string starts with a substring, beginning at the specified index.
+     * @param searchString The string to search for.
+     * @param position The index at which to begin searching for. The default value is 0.
      */
     startsWith(searchString: string, position?: number): boolean;
 
     /**
-     * Returns an `<a>` HTML anchor element and sets the name attribute to the text value
+     * Returns an `<a>` HTML anchor element and sets the name attribute value
      * @deprecated A legacy feature for browser compatibility
-     * @param name
+     * @param name The name attribute value
      */
     anchor(name: string): string;
 
@@ -467,20 +459,16 @@ interface String {
     /**
      * Returns a `<font>` HTML element and sets the color attribute value
      * @deprecated A legacy feature for browser compatibility
+     * @param color The color attribute value
      */
     fontcolor(color: string): string;
 
     /**
      * Returns a `<font>` HTML element and sets the size attribute value
      * @deprecated A legacy feature for browser compatibility
+     * @param size The size attribute value
      */
-    fontsize(size: number): string;
-
-    /**
-     * Returns a `<font>` HTML element and sets the size attribute value
-     * @deprecated A legacy feature for browser compatibility
-     */
-    fontsize(size: string): string;
+    fontsize(size: number | string): string;
 
     /**
      * Returns an `<i>` HTML element
@@ -491,6 +479,7 @@ interface String {
     /**
      * Returns an `<a>` HTML element and sets the href attribute value
      * @deprecated A legacy feature for browser compatibility
+     * @param url The href attribute value
      */
     link(url: string): string;
 
@@ -521,8 +510,9 @@ interface String {
 
 interface StringConstructor {
     /**
-     * Return the String value whose elements are, in order, the elements in the List elements.
-     * If length is 0, the empty string is returned.
+     * Returns a string created by a sequence of code points.
+     * If no arguments are given, the empty string is returned.
+     * @param codePoints A sequence of code points.
      */
     fromCodePoint(...codePoints: number[]): string;
 
@@ -535,5 +525,5 @@ interface StringConstructor {
      * @param template A well-formed template string call site representation.
      * @param substitutions A set of substitution values.
      */
-    raw(template: { raw: readonly string[] | ArrayLike<string>}, ...substitutions: any[]): string;
+    raw(template: { raw: readonly string[] | ArrayLike<string> }, ...substitutions: any[]): string;
 }

src/lib/es2015.symbol.wellknown.d.ts

@@ -219,22 +219,24 @@ interface String {
     match(matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null;
 
     /**
-     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.
+     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
      * @param searchValue An object that supports searching for and replacing matches within a string.
+     * This object is expected to implement its own replacement algorithm.
      * @param replaceValue The replacement text.
      */
     replace(searchValue: { [Symbol.replace](string: string, replaceValue: string): string; }, replaceValue: string): string;
 
     /**
-     * Replaces text in a string, using an object that supports replacement within a string.
-     * @param searchValue A object can search for and replace matches within a string.
+     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
+     * @param searchValue An object that supports searching for and replacing matches within a string.
+     * This object is expected to implement its own replacement algorithm.
      * @param replacer A function that returns the replacement text.
      */
     replace(searchValue: { [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string; }, replacer: (substring: string, ...args: any[]) => string): string;
 
     /**
      * Finds the first substring match in a regular expression search.
-     * @param searcher An object which supports searching within a string.
+     * @param searcher An object that supports searching within a string.
      */
     search(searcher: { [Symbol.search](string: string): number; }): number;
 

src/lib/es2020.symbol.wellknown.d.ts

@@ -13,7 +13,7 @@ interface RegExp {
     /**
      * Matches a string with this regular expression, and returns an iterable of matches
      * containing the results of that search.
-     * @param string A string to search within.
+     * @param str A string to search within.
      */
     [Symbol.matchAll](str: string): IterableIterator<RegExpMatchArray>;
 }

src/lib/es2021.string.d.ts

@@ -1,15 +1,35 @@
 interface String {
     /**
-     * Replace all instances of a substring in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
-     * @param replaceValue A string containing the text to replace for every successful match of searchValue in this string.
+     * Replaces all occurrences of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, a `TypeError` will be thrown if the `g` (global) flag is not set
+     * (only those matches at the beginning are replaced if the `y` (sticky) flag is also present).
+     * @param searchValue A string or RegExp search value.
+     * @param replaceValue The replacement text.
      */
     replaceAll(searchValue: string | RegExp, replaceValue: string): string;
 
     /**
-     * Replace all instances of a substring in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
+     * Replaces all occurrences of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, a `TypeError` will be thrown if the `g` (global) flag is not set
+     * (only those matches at the beginning are replaced if the `y` (sticky) flag is also present).
+     * @param searchValue A string or RegExp search value.
      * @param replacer A function that returns the replacement text.
      */
     replaceAll(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string;
+
+    /**
+     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
+     * @param searchValue An object that supports searching for and replacing matches within a string.
+     * This object is expected to implement its own replacement algorithm.
+     * @param replaceValue The replacement text.
+     */
+    replaceAll(searchValue: { [Symbol.replace](string: string, replaceValue: string): string; }, replaceValue: string): string;
+
+    /**
+     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
+     * @param searchValue An object that supports searching for and replacing matches within a string.
+     * This object is expected to implement its own replacement algorithm.
+     * @param replacer A function that returns the replacement text.
+     */
+     replaceAll(searchValue: { [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string; }, replacer: (substring: string, ...args: any[]) => string): string;
 }

src/lib/es5.d.ts

@@ -387,7 +387,7 @@ interface String {
     charAt(pos: number): string;
 
     /**
-     * Returns the Unicode value of the character at the specified location.
+     * Returns a non-negative integer less than 65536 (0x10000) that is the code unit value of the character at the specified index.
      * @param index The zero-based index of the desired character. If there is no character at the specified index, NaN is returned.
      */
     charCodeAt(index: number): number;
@@ -413,42 +413,51 @@ interface String {
     lastIndexOf(searchString: string, position?: number): number;
 
     /**
-     * Determines whether two strings are equivalent in the current locale.
-     * @param that String to compare to target string
+     * Determines whether the reference string comes before, after or is equivalent to the specified string in the current locale.
+     * Returns a negative integer if it comes before, a positive number if it comes after, and 0 if they are equivalent.
+     * @param that The string to compare to.
      */
     localeCompare(that: string): number;
 
     /**
      * Matches a string with a regular expression, and returns an array containing the results of that search.
-     * @param regexp A variable name or string literal containing the regular expression pattern and flags.
+     * @param regexp The regular expression for matching. If the provided value is not a RegExp, it is implicitly
+     * converted to a RegExp by using `new RegExp(regexp)`.
      */
     match(regexp: string | RegExp): RegExpMatchArray | null;
 
     /**
-     * Replaces text in a string, using a regular expression or search string.
+     * Replaces one or more occurrences of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` (global) flag is set
+     * (or only those matches at the beginning, if the `y` (sticky) flag is also present).
+     * Otherwise, only the first match of {@linkcode searchValue} is replaced.
      * @param searchValue A string or regular expression to search for.
-     * @param replaceValue A string containing the text to replace. When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` flag is set (or only those matches at the beginning, if the `y` flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.
+     * @param replaceValue The replacement text.
      */
     replace(searchValue: string | RegExp, replaceValue: string): string;
 
     /**
-     * Replaces text in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
+     * Replaces one or more occurrences of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` (global) flag is set
+     * (or only those matches at the beginning, if the `y` (sticky) flag is also present).
+     * Otherwise, only the first match of {@linkcode searchValue} is replaced.
+     * @param searchValue A string or regular expression to search for.
      * @param replacer A function that returns the replacement text.
      */
     replace(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string;
 
     /**
      * Finds the first substring match in a regular expression search.
-     * @param regexp The regular expression pattern and applicable flags.
+     * @param regexp The regular expression for matching. If the provided value is not a RegExp, it is implicitly
+     * converted to a RegExp by using `new RegExp(regexp)`.
      */
     search(regexp: string | RegExp): number;
 
     /**
      * Returns a section of a string.
-     * @param start The index to the beginning of the specified portion of stringObj.
-     * @param end The index to the end of the specified portion of stringObj. The substring includes the characters up to, but not including, the character indicated by end.
-     * If this value is not specified, the substring continues to the end of stringObj.
+     * @param start The index to the beginning of the specified portion of the string.
+     * @param end The index to the end of the specified portion of the string. The substring includes the characters up to, but not including, the character indicated by end.
+     * If this value is not specified, the substring continues to the end of the string.
      */
     slice(start?: number, end?: number): string;
 
@@ -460,9 +469,9 @@ interface String {
     split(separator: string | RegExp, limit?: number): string[];
 
     /**
-     * Returns the substring at the specified location within a String object.
-     * @param start The zero-based index number indicating the beginning of the substring.
-     * @param end Zero-based index number indicating the end of the substring. The substring includes the characters up to, but not including, the character indicated by end.
+     * Returns the substring beginning at the specified index within a String object.
+     * @param start The zero-based index indicating the beginning of the substring.
+     * @param end The zero-based index indicating the end of the substring. The substring includes the characters up to, but not including, the character indicated by end.
      * If end is omitted, the characters from start through the end of the original string are returned.
      */
     substring(start: number, end?: number): string;
@@ -487,9 +496,9 @@ interface String {
 
     // IE extensions
     /**
-     * Gets a substring beginning at the specified location and having the specified length.
+     * Gets a substring beginning at the specified index and having the specified length.
      * @deprecated A legacy feature for browser compatibility
-     * @param from The starting position of the desired substring. The index of the first character in the string is zero.
+     * @param from The starting index of the desired substring. The index of the first character in the string is zero.
      * @param length The number of characters to include in the returned substring.
      */
     substr(from: number, length?: number): string;
@@ -508,7 +517,7 @@ interface StringConstructor {
 }
 
 /**
- * Allows manipulation and formatting of text strings and determination and location of substrings within strings.
+ * Allows manipulation and formatting of text strings and determination of location of substrings within strings.
  */
 declare var String: StringConstructor;
 
@@ -573,13 +582,13 @@ interface NumberConstructor {
 
     /**
      * A value that is less than the largest negative number that can be represented in JavaScript.
-     * JavaScript displays NEGATIVE_INFINITY values as -infinity.
+     * JavaScript displays NEGATIVE_INFINITY values as -Infinity.
      */
     readonly NEGATIVE_INFINITY: number;
 
     /**
      * A value greater than the largest number that can be represented in JavaScript.
-     * JavaScript displays POSITIVE_INFINITY values as infinity.
+     * JavaScript displays POSITIVE_INFINITY values as Infinity.
      */
     readonly POSITIVE_INFINITY: number;
 }
@@ -975,11 +984,16 @@ interface RegExp {
     /** Returns a Boolean value indicating the state of the multiline flag (m) used with a regular expression. Default is false. Read-only. */
     readonly multiline: boolean;
 
+    /**
+     * Gets or sets the index at which the {@link RegExp.exec()} or {@link RegExp.test()} methods start searching for a match in an arbitrary string.
+     * After each execution of {@link RegExp.exec()} or {@link RegExp.test()}, `lastIndex` will be set to the end index of the matched string,
+     * or 0 if a match was not found.
+     */
     lastIndex: number;
 
     // Non-standard extensions
     /** @deprecated A legacy feature for browser compatibility */
-    compile(pattern: string, flags?: string): this;
+    compile(pattern: string, flags?: string): RegExp;
 }
 
 interface RegExpConstructor {