feat: add symbol/replace

lib/node_modules/@stdlib/symbol/replace/README.md

@@ -0,0 +1,88 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# ReplaceSymbol
+
+> Well-known [`Symbol.replace`][mdn-symbol], used by `String.prototype.replace()` to customize replacement behavior.
+
+<section class="intro">
+
+</section>
+
+<section class="usage">
+
+## Usage
+
+```javascript
+/* eslint-disable */
+
+var ReplaceSymbol = require( '@stdlib/symbol/replace' );
+
+var s = typeof ReplaceSymbol;
+// e.g., returns 'symbol'
+
+if ( ReplaceSymbol ) {
+    function CustomReplacer() {}
+
+    CustomReplacer.prototype[ ReplaceSymbol ] = function namedReplace( str ) {
+        return 'REPLACED: ' + str;
+    };
+
+    var out = 'hello world'.replace( new CustomReplacer() );
+    console.log( out );
+    // => 'REPLACED: hello world'
+} else {
+    console.log( ReplaceSymbol );
+    // => null
+}
+
+/* eslint-enable */
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[mdn-symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
+
+</section>
+
+<!-- /.links -->
+

lib/node_modules/@stdlib/symbol/replace/docs/repl.txt

@@ -0,0 +1,17 @@
+{{alias}}
+    Replace symbol.
+
+    This well-known symbol specifies the method that replaces matched
+    substrings. It is used by `String.prototype.replace()` to delegate
+    replacement behavior to an object.
+
+    The symbol is only supported in ES6/ES2015+ environments. In
+    unsupported environments, the value is `null`.
+
+    Examples
+    --------
+    > var s = {{alias}}
+    e.g., <symbol>
+
+    See Also
+    --------

lib/node_modules/@stdlib/symbol/replace/docs/types/index.d.ts

@@ -0,0 +1,34 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+// EXPORTS //
+
+/**
+* Replace symbol.
+*
+* ## Notes
+*
+* -   This well-known symbol specifies the method that replaces matched substrings.
+*     It is used by `String.prototype.replace()` to delegate replacement behavior.
+* -   The symbol is only supported in ES6/ES2015+ environments. In non-supporting
+*     environments, the exported value is `null`.
+*/
+export = Symbol.replace;
+

lib/node_modules/@stdlib/symbol/replace/docs/types/test.ts

@@ -0,0 +1,29 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+
+import ReplaceSymbol = require( './index' );
+
+// TESTS //
+
+// The exported value is the `replace` symbol...
+{
+	ReplaceSymbol;
+}
+

lib/node_modules/@stdlib/symbol/replace/examples/index.js

@@ -0,0 +1,66 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var ReplaceSymbol = require( './../lib' );
+
+
+// VARIABLES //
+
+var out;
+
+
+// FUNCTIONS //
+
+/**
+* Custom replacer object.
+*
+* @private
+* @constructor
+*/
+function CustomReplacer() {
+	// Empty constructor
+}
+
+/**
+* Replacement method.
+*
+* @private
+* @param {string} str - input string
+* @returns {string} replaced string
+*/
+function replace( str ) {
+	return 'REPLACED: ' + str;
+}
+
+
+// MAIN //
+
+if ( ReplaceSymbol ) {
+	CustomReplacer.prototype[ ReplaceSymbol ] = replace;
+
+	out = 'hello world'.replace( new CustomReplacer() );
+	console.log( out );
+	// => 'REPLACED: hello world'
+} else {
+	console.log( ReplaceSymbol );
+	// => null
+}

lib/node_modules/@stdlib/symbol/replace/lib/index.js

@@ -0,0 +1,56 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Well-known symbol `Symbol.replace`.
+*
+* This symbol specifies the method that replaces matched substrings and is used
+* by `String.prototype.replace()` to delegate replacement behavior to an object.
+*
+* @module @stdlib/symbol/replace
+*
+* @example
+* var ReplaceSymbol = require( '@stdlib/symbol/replace' );
+*
+* if ( ReplaceSymbol ) {
+*     function CustomReplacer() {}
+*
+*     CustomReplacer.prototype[ ReplaceSymbol ] = function( str ) {
+*         return 'REPLACED: ' + str;
+*     };
+*
+*     var out = 'hello world'.replace( new CustomReplacer() );
+*     console.log( out );
+*     // => 'REPLACED: hello world'
+* }
+* else {
+*     console.log( ReplaceSymbol );
+*     // => null
+* }
+*/
+
+// MAIN //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

lib/node_modules/@stdlib/symbol/replace/lib/main.js

@@ -0,0 +1,54 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var hasReplaceSymbolSupport = require( '@stdlib/assert/has-replace-symbol-support' );
+
+
+// MAIN //
+
+/**
+* Replace symbol.
+*
+* @name ReplaceSymbol
+* @constant
+* @type {(symbol|null)}
+*
+* @example
+* var ReplaceSymbol = require( '@stdlib/symbol/replace' );
+*
+* if ( ReplaceSymbol ) {
+*     function Replacer() {}
+*
+*     Replacer.prototype[ ReplaceSymbol ] = function ( str ) {
+*         return 'REPLACED: ' + str;
+*     };
+*
+*     var out = 'hello world'.replace( new Replacer() );
+*     console.log( out );
+* }
+*/
+var ReplaceSymbol = ( hasReplaceSymbolSupport() ) ? Symbol.replace : null;
+
+
+// EXPORTS //
+
+module.exports = ReplaceSymbol;