minor: implement "sip" w/ tests & update README

Author: pr0fix

README.md

@@ -31,6 +31,7 @@ To install caffeinated-strings, run the following command:
 | `.repeat()`      | `refillCup`    | Constructs a new string which contains a specified number of copies of the input string (like refilling a coffee cup a specific amount of times). |
 | `.toLowerCase()` | `coolDown`     | Transforms the string to lowercase (like cooling down a cup of coffee).                                                                           |
 | `.toUpperCase()` | `froth`        | Transforms the string to uppercase (like frothing the milk to create a creamy top).                                                               |
+| `.trim()`        | `sip`          | Removes whitespace from both ends of string (like sipping away the excess on top).                                                                |
 
 ## 🔧 Usage
 
@@ -127,7 +128,7 @@ console.log(refillCup(drink, 3)); // "cappuccino cappuccino cappuccino "
 
 ```js
 let drink = "ESPRESSO";
-console.log(froth(drink)); // "espresso"
+console.log(coolDown(drink)); // "espresso"
 ```
 
 11. `froth(str)`
@@ -138,3 +139,12 @@ console.log(froth(drink)); // "espresso"
 let drink = "espresso";
 console.log(froth(drink)); // "ESPRESSO"
 ```
+
+12. `sip(str)`
+    Removes whitespace from both ends of the string (like sipping away the excess on top).
+    Returns a new `string` without modifying the original:
+
+```js
+let drink = "   espresso is lovely!!     ";
+console.log(sip(drink)); // "espresso is lovely!!"
+```

src/index.ts

@@ -8,4 +8,5 @@ export { froth } from "./froth";
 export { hasMilk } from "./hasMilk";
 export { pourCoffee } from "./pourCoffee";
 export { refillCup } from "./refillCup";
+export { sip } from "./sip";
 export { sipAt } from "./sipAt";

src/refillCup.ts

@@ -4,7 +4,8 @@
  * @param str The input string
  * @param count The input count
  *
- * @returns A string with specified number of copies of input string, concatenated together.
+ * @returns A string with specified number of copies of input string concatenated together, 
+ * or `null` if the inputs are of wrong type.
  *
  * @example
  * ```typescript

src/sip.ts

@@ -0,0 +1,53 @@
+/**
+ * Removes whitespace from both ends of the input string.
+ *
+ * @param str The input string
+ *
+ * @returns A new string with whitespace removed without modifying the original string,
+ * or `null` if the input is not a string or is empty.
+ *
+ * @example
+ * ```typescript
+ * sip("      coffee tastes good!     "); // Returns "coffee tastes good!"
+ * sip(123); // Returns null
+ * sip(""); // Returns null
+ * ```
+ */
+export function sip(str: string): string | null {
+  if (typeof str !== "string" || str === "") {
+    return null;
+  }
+
+  let start = 0;
+
+  while (
+    str[start] === " " ||
+    str[start] === "\t" ||
+    str[start] === "\n" ||
+    str[start] === "\r"
+  ) {
+    start++;
+  }
+
+  let end = 0;
+  while (str[end] !== undefined) {
+    end++;
+  }
+
+  end--;
+  while (
+    end >= start &&
+    (str[end] === " " ||
+      str[end] === "\t" ||
+      str[end] === "\n" ||
+      str[end] === "\r")
+  ) {
+    end--;
+  }
+
+  let result = "";
+  for (let i = start; i <= end; i++) {
+    result += str[i];
+  }
+  return result;
+}

tests/sip.test.ts

@@ -0,0 +1,28 @@
+import { sip } from "../src/index";
+
+test("sip should remove whitespace from string", () => {
+  expect(sip("  coffee    ")).toBe("coffee");
+});
+
+test("sip should remove whitespace correctly for strings with spaces", () => {
+  expect(sip("   coffee is what we love!    ")).toBe("coffee is what we love!");
+  expect(sip("we love coffee")).toBe("we love coffee");
+});
+
+test("sip should remove whitespace from strings with special characters", () => {
+  expect(sip("    café  ")).toBe("café");
+  expect(sip("   123!@#  ")).toBe("123!@#");
+});
+
+test("sip should return null for an empty string", () => {
+  expect(sip("")).toBeNull();
+});
+
+test("sip should return null for non strings", () => {
+  expect(sip(0 as any)).toBeNull();
+  expect(sip(true as any)).toBeNull();
+  expect(sip({} as any)).toBeNull();
+  expect(sip([] as any)).toBeNull();
+  expect(sip(undefined as any)).toBeNull();
+  expect(sip(null as any)).toBeNull();
+});