From a153088968c2a7ef3a89e637de916a4e0c291d5b Mon Sep 17 00:00:00 2001
From: Prasad1-S <subhojeetprasad0@gmail.com>
Date: Thu, 13 Nov 2025 16:16:52 +0530
Subject: [PATCH] Add @stdlib/string/base/concat: concatenate two strings (RFC)

---
 .../@stdlib/string/base/concat/README.md      | 92 +++++++++++++++++++
 .../string/base/concat/examples/index.js      |  5 +
 .../@stdlib/string/base/concat/lib/index.js   | 40 ++++++++
 .../@stdlib/string/base/concat/lib/main.js    | 41 +++++++++
 .../@stdlib/string/base/concat/package.json   | 63 +++++++++++++
 .../@stdlib/string/base/concat/test/test.js   | 51 ++++++++++
 6 files changed, 292 insertions(+)
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/README.md
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/examples/index.js
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/lib/index.js
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/lib/main.js
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/package.json
 create mode 100644 lib/node_modules/@stdlib/string/base/concat/test/test.js

diff --git a/lib/node_modules/@stdlib/string/base/concat/README.md b/lib/node_modules/@stdlib/string/base/concat/README.md
new file mode 100644
index 000000000000..92dcea73a6bf
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/README.md
@@ -0,0 +1,92 @@
+<!--
+
+@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.
+
+-->
+
+# concat
+
+> Concatenate two strings (wraps String.prototype.concat).
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var concat = require( '@stdlib/string/base/concat' );
+```
+
+#### concat( str1, str2 )
+
+Concatenates `str1` and `str2` and returns the concatenated string.
+
+```javascript
+var s = concat( 'beep', 'boop' );
+// returns 'beepboop'
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var concat = require( '@stdlib/string/base/concat' );
+
+var s = concat( 'foo', 'bar' );
+// returns 'foobar'
+
+s = concat( 'hello', ' world' );
+// returns 'hello world'
+
+s = concat( '', 'empty' );
+// returns 'empty'
+
+s = concat( 'a', '' );
+// returns 'a'
+```
+
+</section>
+
+<!-- /.examples -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/string/base/lowercase`][@stdlib/string/base/lowercase]</span><span class="delimiter">: </span><span class="description">convert a string to lowercase.</span>
+
+</section>
+
+<section class="links">
+
+[@stdlib/string/base/lowercase]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/base/lowercase
+
+</section>
diff --git a/lib/node_modules/@stdlib/string/base/concat/examples/index.js b/lib/node_modules/@stdlib/string/base/concat/examples/index.js
new file mode 100644
index 000000000000..5be7a329334a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/examples/index.js
@@ -0,0 +1,5 @@
+// Simple example using relative require so you can run the file directly:
+var concat = require( './../lib' );
+
+console.log( concat( 'foo', 'bar' ) ); // 'foobar'
+console.log( concat( 'hello', ' world' ) ); // 'hello world'
diff --git a/lib/node_modules/@stdlib/string/base/concat/lib/index.js b/lib/node_modules/@stdlib/string/base/concat/lib/index.js
new file mode 100644
index 000000000000..58a974f04dc9
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/lib/index.js
@@ -0,0 +1,40 @@
+/**
+* @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';
+
+/**
+* Concatenate two strings.
+*
+* @module @stdlib/string/base/concat
+*
+* @example
+* var concat = require( '@stdlib/string/base/concat' );
+*
+* var s = concat( 'beep', 'boop' );
+* // returns 'beepboop'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/concat/lib/main.js b/lib/node_modules/@stdlib/string/base/concat/lib/main.js
new file mode 100644
index 000000000000..7141351c0e6d
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/lib/main.js
@@ -0,0 +1,41 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Concatenates two strings.
+*
+* @param {string} str1 - first string
+* @param {string} str2 - second string
+* @returns {string} concatenated string
+*
+* @example
+* var s = concat( 'beep', 'boop' );
+* // returns 'beepboop'
+*/
+function concat( str1, str2 ) {
+    return String.prototype.concat.call( str1, str2 );
+}
+
+
+// EXPORTS //
+
+module.exports = concat;
diff --git a/lib/node_modules/@stdlib/string/base/concat/package.json b/lib/node_modules/@stdlib/string/base/concat/package.json
new file mode 100644
index 000000000000..a2367ae5b52f
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/package.json
@@ -0,0 +1,63 @@
+{
+  "name": "@stdlib/string/base/concat",
+  "version": "0.0.0",
+  "description": "Concatenate two strings (wraps String.prototype.concat).",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "directories": {
+    "benchmark": "./benchmark",
+    "doc": "./docs",
+    "example": "./examples",
+    "lib": "./lib",
+    "test": "./test"
+  },
+  "types": "./docs/types",
+  "scripts": {},
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "stdstring",
+    "utilities",
+    "utility",
+    "utils",
+    "util",
+    "base",
+    "concat",
+    "string",
+    "str"
+  ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/concat/test/test.js b/lib/node_modules/@stdlib/string/base/concat/test/test.js
new file mode 100644
index 000000000000..312d0e9f5c75
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/concat/test/test.js
@@ -0,0 +1,51 @@
+/**
+* @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 tape = require( 'tape' );
+var concat = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+    t.ok( true, __filename );
+    t.strictEqual( typeof concat, 'function', 'main export is a function' );
+    t.end();
+});
+
+tape( 'the function concatenates two strings', function test( t ) {
+    var actual;
+
+    actual = concat( 'beep', 'boop' );
+    t.strictEqual( actual, 'beepboop', 'concatenates strings' );
+
+    actual = concat( 'hello', ' world' );
+    t.strictEqual( actual, 'hello world', 'concatenates strings with space' );
+
+    actual = concat( '', 'empty' );
+    t.strictEqual( actual, 'empty', 'concatenates empty first string' );
+
+    actual = concat( 'a', '' );
+    t.strictEqual( actual, 'a', 'concatenates empty second string' );
+
+    t.end();
+});