From 66ebe1456f30e33cf8c9b219202b18b2ddcf5d1c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Borys=20=C5=BBmuda?= <rudashi@gmail.com>
Date: Mon, 2 Sep 2024 09:41:26 +0200
Subject: [PATCH] feat(#46): Added `position`

---
 src/Str.ts             |  2 ++
 src/Stringable.ts      |  4 ++++
 src/methods.ts         |  6 +++++
 tests/position.test.js | 54 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 66 insertions(+)
 create mode 100644 tests/position.test.js

diff --git a/src/Str.ts b/src/Str.ts
index c910e1d..59a8655 100644
--- a/src/Str.ts
+++ b/src/Str.ts
@@ -32,6 +32,7 @@ import {
     padLeft,
     padRight,
     parseCallback,
+    position,
     repeat,
     replaceArray,
     replace,
@@ -183,6 +184,7 @@ export const Str = {
             .map(() => characters[Math.floor(crypto.randomInt(random) % characters.length)])
             .join('');
     },
+    position,
     random: (length: number = 16): string => {
         const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
         const size = characters.length;
diff --git a/src/Stringable.ts b/src/Stringable.ts
index eaa34b7..f77b705 100644
--- a/src/Stringable.ts
+++ b/src/Stringable.ts
@@ -288,6 +288,10 @@ export class Stringable {
         return this;
     }
 
+    public position = (needle: string, offset: number = 0): number|boolean => {
+        return Str.position(this._value, needle, offset);
+    }
+
     public prepend = (...values: string[]): this => {
         this._value = values.join('') + this._value;
 
diff --git a/src/methods.ts b/src/methods.ts
index 309e1e1..b666a00 100644
--- a/src/methods.ts
+++ b/src/methods.ts
@@ -394,6 +394,12 @@ export const parseCallback = (callback: string, method: string | null = null): A
         : [callback, method];
 }
 
+export const position = (haystack: string, needle: string, offset: number = 0): number|boolean => {
+    const index = haystack.indexOf(needle, offset);
+
+    return index < 0 ? false : index;
+}
+
 export const repeat = (string: string, times: number): string => {
     return string.repeat(times)
 }
diff --git a/tests/position.test.js b/tests/position.test.js
new file mode 100644
index 0000000..99a1b65
--- /dev/null
+++ b/tests/position.test.js
@@ -0,0 +1,54 @@
+'use strict';
+
+const {Stringable} = require('../src/Stringable');
+const {Str} = require('../src/Str');
+const {position} = require('../src/methods');
+
+it('returns a position of the first occurrence of a given substring in the given string', () => {
+    expect(Stringable.of('Hello, World!').position('W'))
+        .toBe(7);
+
+    expect(Stringable.of('This is a test string.').position('test'))
+        .toBe(10);
+
+    expect(Stringable.of('This is a test string, test again.').position('test', 15))
+        .toBe(23);
+
+    expect(Stringable.of('Hello, World!').position('Hello'))
+        .toBe(0);
+
+    expect(Stringable.of('Hello, World!').position('World!'))
+        .toBe(7);
+
+    expect(Stringable.of('This is a tEsT string.').position('tEsT'))
+        .toBe(10);
+
+    expect(Stringable.of('Hello, World!').position('W', -6))
+        .toBe(7);
+
+    expect(Stringable.of('Äpfel, Birnen und Kirschen').position('Kirschen', -10))
+        .toBe(18);
+
+    expect(Stringable.of('@%€/=!"][$').position('$'))
+        .toBe(9);
+
+    expect(Str.position('Hello, World!', 'W'))
+        .toBe(7);
+
+    expect(position('Hello, World!', 'W'))
+        .toBe(7);
+});
+
+it('should return false when substring not exists in the given string', () => {
+    expect(Stringable.of('Hello, World!').position('w'))
+        .toBe(false);
+
+    expect(Stringable.of('Hello, World!').position('X'))
+        .toBe(false);
+
+    expect(Stringable.of('').position('test'))
+        .toBe(false);
+
+    expect(Stringable.of('Hello, World!').position('X'))
+        .toBe(false);
+});