Hamming distance between two strings (Compares Unicode code points)

CONTRIBUTORS

@@ -24,6 +24,7 @@ Golden <[email protected]>
 Harshita Kalani <[email protected]>
 Jaimin Godhani <[email protected]>
 James Gelok <[email protected]>
+Jay Pokale <[email protected]>
 Jaysukh Makvana <[email protected]>
 Jithin KS <[email protected]>
 Joey Reed <[email protected]>

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/README.md

@@ -0,0 +1,126 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 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.
+
+-->
+
+# hammingCodePointsDistance
+
+> Calculate the [Hamming code points distance][hamming-distance] between two equal-length unicode code points.
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var hammingCodePointsDistance = require("@stdlib/string/base/distances/hamming-code-points");
+```
+
+#### hammingCodePointsDistance( s1, s2 )
+
+Calculate the [Hamming code points distance][hamming-distance] between two equal-length unicode code points.
+
+```javascript
+var dist
+
+dist = hammingCodePointsDistance(["Hello, world!", "Héllö, wörld!"]);
+// returns 3
+
+dist = hammingCodePointsDistance("a😊c", "a😃c");
+// returns 1
+
+dist = hammingCodePointsDistance("नमस्ते", "नमस्का");
+// returns 2
+
+dist = hammingCodePointsDistance("", "");
+// returns 0
+
+dist = hammingCodePointsDistance("你好", "世界");
+// returns 2
+
+dist = hammingCodePointsDistance("こんにちは", "さようなら");
+// returns 5
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+- If the two strings differ in length, the [Hamming code points distance][hamming-distance] is not defined. Consequently, when provided two input strings of unequal length, the function returns a sentinel value of `-1`.
+- As the function calculates the [Hamming code points distance][hamming-distance] by comparing UTF-16 code units, the function should behave as expected for strings composed of all unicode charracters.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var dist
+
+dist = hammingCodePointsDistance(["Hello, world!", "Héllö, wörld!"]);
+// returns 3
+
+dist = hammingCodePointsDistance("a😊c", "a😃c");
+// returns 1
+
+dist = hammingCodePointsDistance("नमस्ते", "नमस्का");
+// returns 2
+
+dist = hammingCodePointsDistance("", "");
+// returns 0
+
+dist = hammingCodePointsDistance("你好", "世界");
+// returns 2
+
+dist = hammingCodePointsDistance("こんにちは", "さようなら");
+// returns 5
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- 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">
+
+[hamming-distance]: https://en.wikipedia.org/wiki/Hamming_distance
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/benchmark/benchmark.js

@@ -0,0 +1,60 @@
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2024 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 bench = require("@stdlib/bench");
+var pkg = require("./../package.json").name;
+var hammingCodePointsDistance = require("./../lib");
+
+// MAIN //
+
+bench(pkg, function benchmark(b) {
+  var value;
+  var out;
+
+  var values = [
+    ["", ""],
+    ["a", "a"],
+    ["a", "b"],
+    ["xy", "xy"],
+    ["xx", "xy"],
+    ["Hello, world!", "Héllö, wörld!"],
+    ["a😊c", "a😃c"],
+    ["नमस्ते", "नमस्का"],
+    ["你好", "世界"],
+    ["こんにちは", "さようなら"],
+  ];
+
+  b.tic();
+  for (var i = 0; i < b.iterations; i++) {
+    value = values[i % values.length];
+    out = hammingCodePointsDistance(value[0], value[1]);
+    if (typeof out !== "number") {
+      b.fail("should return a number");
+    }
+  }
+  b.toc();
+  if (typeof out !== "number") {
+    b.fail("should return a number");
+  }
+  b.pass("benchmark finished");
+  b.end();
+});

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/docs/repl.txt

@@ -0,0 +1,34 @@
+
+{{alias}}( s1, s2 )
+    Calculates the Hamming code points distance between two equal-length unicode code points.
+
+    The function returns a sentinel value of -1 if the input string lengths
+    differ.
+
+    Parameters
+    ----------
+    s1: string
+        First input string.
+
+    s2: string
+        Second input string.
+
+    Returns
+    -------
+    out: number
+        Hamming code points distance.
+
+    Examples
+    --------
+    > var d = {{alias}}( "Hello, world!", "Héllö, wörld!" )
+    3
+    > d = {{alias}}( "a😊c", "a😃c" )
+    1
+    > d = {{alias}}( "こんにちは", "さようなら" )
+    5
+    > d = {{alias}}( "a", "abcissa" )
+    -1
+
+    See Also
+    --------
+

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/docs/types/index.d.ts

@@ -0,0 +1,48 @@
+/*
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2024 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
+
+/**
+ * Calculates the Hamming code points distance between two equal-length unicode code points.
+ *
+ * ## Notes
+ *
+ * -   The function returns a sentinel value of `-1` if the input string lengths differ.
+ *
+ * @param str1 - first input string
+ * @param str2 - second input string
+ * @returns Hamming code points distance
+ *
+ * @example
+ * var dist = hammingCodePointsDistance( "Hello, world!", "Héllö, wörld!" );
+ * // returns 3
+ *
+ * @example
+ * var dist = hammingCodePointsDistance( "a😊c", "a😃c" );
+ * // returns 1
+ *
+ * @example
+ * var dist = hammingCodePointsDistance( "こんにちは", "さようなら" );
+ * // returns 5
+ */
+declare function hammingCodePointsDistance(str1: string, str2: string): number;
+
+// EXPORTS //
+
+export = hammingCodePointsDistance;

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/docs/types/test.ts

@@ -0,0 +1,57 @@
+/*
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2024 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.
+ */
+
+import hammingCodePointsDistance from "./index";
+
+// TESTS //
+
+// The function returns a number...
+{
+  hammingCodePointsDistance("", ""); // $ExpectType number
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a string...
+{
+  hammingCodePointsDistance(true, ""); // $ExpectError
+  hammingCodePointsDistance(false, ""); // $ExpectError
+  hammingCodePointsDistance(null, ""); // $ExpectError
+  hammingCodePointsDistance(undefined, ""); // $ExpectError
+  hammingCodePointsDistance(5, ""); // $ExpectError
+  hammingCodePointsDistance([], ""); // $ExpectError
+  hammingCodePointsDistance({}, ""); // $ExpectError
+  hammingCodePointsDistance((x: number): number => x, ""); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a string...
+{
+  hammingCodePointsDistance("", true); // $ExpectError
+  hammingCodePointsDistance("", false); // $ExpectError
+  hammingCodePointsDistance("", null); // $ExpectError
+  hammingCodePointsDistance("", undefined); // $ExpectError
+  hammingCodePointsDistance("", 5); // $ExpectError
+  hammingCodePointsDistance("", []); // $ExpectError
+  hammingCodePointsDistance("", {}); // $ExpectError
+  hammingCodePointsDistance("", (x: number): number => x); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+  hammingCodePointsDistance(); // $ExpectError
+  hammingCodePointsDistance(""); // $ExpectError
+  hammingCodePointsDistance("", "", 3); // $ExpectError
+}

lib/node_modules/@stdlib/string/base/distances/hamming-code-points/examples/index.js

@@ -0,0 +1,33 @@
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2024 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";
+
+var hammingCodePointsDistance = require("./../lib");
+
+console.log(hammingCodePointsDistance("Hello, world!", "Héllö, wörld!"));
+// => 3
+
+console.log(hammingCodePointsDistance("a😊c", "a😃c"));
+// => 1
+
+console.log(hammingCodePointsDistance("こんにちは", "さようなら"));
+// => 5
+
+console.log(hammingCodePointsDistance("a", "abcissa"));
+// => -1