oakscriptjs 0.8.1 → 0.9.0

package/dist/cjs/str/dateformat.js

@@ -0,0 +1,149 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dateformat_exports = {};
+__export(dateformat_exports, {
+  formatDate: () => formatDate
+});
+module.exports = __toCommonJS(dateformat_exports);
+var import_timezone = require("../time/timezone.js");
+const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December"
+];
+const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const pad = (n, width) => String(n).padStart(width, "0");
+function zoneName(time, timezone, offsetMs) {
+  if (timezone === "Etc/UTC") return "UTC";
+  if (/^(UTC|GMT)/.test(timezone)) {
+    if (offsetMs === 0) return "GMT";
+    const minutes = Math.abs(offsetMs) / 6e4;
+    return `GMT${offsetMs < 0 ? "-" : "+"}${pad(Math.floor(minutes / 60), 2)}:${pad(minutes % 60, 2)}`;
+  }
+  const part = new Intl.DateTimeFormat("en-US", { timeZone: timezone, timeZoneName: "short" }).formatToParts(time).find((p) => p.type === "timeZoneName");
+  return part?.value ?? timezone;
+}
+function weekOfYear(year, month, day) {
+  const date = Date.UTC(year, month - 1, day);
+  const dow = new Date(date).getUTCDay();
+  const weekStart = date - dow * 864e5;
+  if (weekStart + 6 * 864e5 >= Date.UTC(year + 1, 0, 1)) return 1;
+  const jan1 = Date.UTC(year, 0, 1);
+  const jan1Dow = new Date(jan1).getUTCDay();
+  return Math.floor((date - jan1 + jan1Dow * 864e5) / (7 * 864e5)) + 1;
+}
+function formatDate(time, pattern, timezone) {
+  if (Number.isNaN(time)) return "NaN";
+  const f = (0, import_timezone.zonedFields)(time, timezone);
+  const offset = (0, import_timezone.zoneOffset)(time, timezone);
+  const ms = (time % 1e3 + 1e3) % 1e3;
+  const dayOfYear = (Date.UTC(f.year, f.month - 1, f.day) - Date.UTC(f.year, 0, 1)) / 864e5 + 1;
+  let out = "";
+  for (let i = 0; i < pattern.length; ) {
+    const ch = pattern[i];
+    if (ch === "'") {
+      const end = pattern.indexOf("'", i + 1);
+      if (end === i + 1) {
+        out += "'";
+        i += 2;
+      } else {
+        out += pattern.slice(i + 1, end === -1 ? void 0 : end);
+        i = end === -1 ? pattern.length : end + 1;
+      }
+      continue;
+    }
+    if (!/[A-Za-z]/.test(ch)) {
+      out += ch;
+      i++;
+      continue;
+    }
+    let n = 1;
+    while (pattern[i + n] === ch) n++;
+    i += n;
+    const hour12 = f.hour % 12;
+    switch (ch) {
+      case "y":
+        out += n === 2 ? pad(f.year % 100, 2) : pad(f.year, n);
+        break;
+      case "M":
+        out += n >= 4 ? MONTHS[f.month - 1] : n === 3 ? MONTHS[f.month - 1].slice(0, 3) : pad(f.month, n);
+        break;
+      case "d":
+        out += pad(f.day, n);
+        break;
+      case "E":
+        out += n >= 4 ? DAYS[f.dayOfWeek - 1] : DAYS[f.dayOfWeek - 1].slice(0, 3);
+        break;
+      case "u":
+        out += pad(f.dayOfWeek === 1 ? 7 : f.dayOfWeek - 1, n);
+        break;
+      case "D":
+        out += pad(dayOfYear, n);
+        break;
+      case "w":
+        out += pad(weekOfYear(f.year, f.month, f.day), n);
+        break;
+      case "H":
+        out += pad(f.hour, n);
+        break;
+      case "k":
+        out += pad(f.hour === 0 ? 24 : f.hour, n);
+        break;
+      case "K":
+        out += pad(hour12, n);
+        break;
+      case "h":
+        out += pad(hour12 === 0 ? 12 : hour12, n);
+        break;
+      case "a":
+        out += f.hour < 12 ? "AM" : "PM";
+        break;
+      case "m":
+        out += pad(f.minute, n);
+        break;
+      case "s":
+        out += pad(f.second, n);
+        break;
+      case "S":
+        out += pad(ms, n);
+        break;
+      case "Z": {
+        const minutes = Math.abs(offset) / 6e4;
+        out += (offset < 0 ? "-" : "+") + pad(Math.floor(minutes / 60), 2) + pad(minutes % 60, 2);
+        break;
+      }
+      case "z":
+        out += zoneName(time, timezone, offset);
+        break;
+      default:
+        throw new SyntaxError(`Unsupported date pattern letter "${ch}" in "${pattern}"`);
+    }
+  }
+  return out;
+}
+//# sourceMappingURL=dateformat.js.map

package/dist/cjs/str/dateformat.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/str/dateformat.ts"],
+  "sourcesContent": ["/**\n * Date patterns of `str.format_time` and `str.format(\"{0,date,...}\")`, as PineScript formats them\n * (Java SimpleDateFormat letters, English names):\n *\n * y year, M month (M, MM, MMM, MMMM), d day, E weekday (EEE, EEEE), u weekday number (1 = Monday),\n * D day of year, w week of year (weeks start on Sunday, week 1 contains 1 January), H hour 0-23,\n * k hour 1-24, K hour 0-11, h hour 1-12, a AM/PM, m minute, s second, S millisecond,\n * Z offset (+0530), z time zone name, 'text' literal text ('' is a quote).\n *\n * `z` gives \"UTC\" for Etc/UTC, \"GMT\" for \"UTC\"/\"GMT\", \"GMT+05:00\" for other offsets, and the\n * host's short English name for IANA zones (PineScript's names can differ, e.g. \"IST\" for Asia/Kolkata).\n */\n\nimport { zonedFields, zoneOffset } from '../time/timezone.js';\n\nconst MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September',\n  'October', 'November', 'December'];\nconst DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];\n\nconst pad = (n: number, width: number): string => String(n).padStart(width, '0');\n\nfunction zoneName(time: number, timezone: string, offsetMs: number): string {\n  if (timezone === 'Etc/UTC') return 'UTC';\n  if (/^(UTC|GMT)/.test(timezone)) {\n    if (offsetMs === 0) return 'GMT';\n    const minutes = Math.abs(offsetMs) / 60000;\n    return `GMT${offsetMs < 0 ? '-' : '+'}${pad(Math.floor(minutes / 60), 2)}:${pad(minutes % 60, 2)}`;\n  }\n  const part = new Intl.DateTimeFormat('en-US', { timeZone: timezone, timeZoneName: 'short' })\n    .formatToParts(time)\n    .find((p) => p.type === 'timeZoneName');\n  return part?.value ?? timezone;\n}\n\n/** Week of year: weeks start on Sunday and week 1 is the week that contains 1 January. */\nfunction weekOfYear(year: number, month: number, day: number): number {\n  const date = Date.UTC(year, month - 1, day);\n  const dow = new Date(date).getUTCDay();\n  const weekStart = date - dow * 86_400_000;\n  // the week that contains 1 January of the next year is week 1\n  if (weekStart + 6 * 86_400_000 >= Date.UTC(year + 1, 0, 1)) return 1;\n  const jan1 = Date.UTC(year, 0, 1);\n  const jan1Dow = new Date(jan1).getUTCDay();\n  return Math.floor((date - jan1 + jan1Dow * 86_400_000) / (7 * 86_400_000)) + 1;\n}\n\n/** Formats a UNIX time (ms) with a SimpleDateFormat pattern in `timezone`. */\nexport function formatDate(time: number, pattern: string, timezone: string): string {\n  if (Number.isNaN(time)) return 'NaN';\n  const f = zonedFields(time, timezone);\n  const offset = zoneOffset(time, timezone);\n  const ms = ((time % 1000) + 1000) % 1000;\n  const dayOfYear = (Date.UTC(f.year, f.month - 1, f.day) - Date.UTC(f.year, 0, 1)) / 86_400_000 + 1;\n\n  let out = '';\n  for (let i = 0; i < pattern.length; ) {\n    const ch = pattern[i]!;\n    if (ch === \"'\") {\n      const end = pattern.indexOf(\"'\", i + 1);\n      if (end === i + 1) {\n        out += \"'\";\n        i += 2;\n      } else {\n        out += pattern.slice(i + 1, end === -1 ? undefined : end);\n        i = end === -1 ? pattern.length : end + 1;\n      }\n      continue;\n    }\n    if (!/[A-Za-z]/.test(ch)) {\n      out += ch;\n      i++;\n      continue;\n    }\n    let n = 1;\n    while (pattern[i + n] === ch) n++;\n    i += n;\n    const hour12 = f.hour % 12;\n    switch (ch) {\n      case 'y': out += n === 2 ? pad(f.year % 100, 2) : pad(f.year, n); break;\n      case 'M': out += n >= 4 ? MONTHS[f.month - 1] : n === 3 ? MONTHS[f.month - 1]!.slice(0, 3) : pad(f.month, n); break;\n      case 'd': out += pad(f.day, n); break;\n      case 'E': out += n >= 4 ? DAYS[f.dayOfWeek - 1] : DAYS[f.dayOfWeek - 1]!.slice(0, 3); break;\n      case 'u': out += pad(f.dayOfWeek === 1 ? 7 : f.dayOfWeek - 1, n); break;\n      case 'D': out += pad(dayOfYear, n); break;\n      case 'w': out += pad(weekOfYear(f.year, f.month, f.day), n); break;\n      case 'H': out += pad(f.hour, n); break;\n      case 'k': out += pad(f.hour === 0 ? 24 : f.hour, n); break;\n      case 'K': out += pad(hour12, n); break;\n      case 'h': out += pad(hour12 === 0 ? 12 : hour12, n); break;\n      case 'a': out += f.hour < 12 ? 'AM' : 'PM'; break;\n      case 'm': out += pad(f.minute, n); break;\n      case 's': out += pad(f.second, n); break;\n      case 'S': out += pad(ms, n); break;\n      case 'Z': {\n        const minutes = Math.abs(offset) / 60000;\n        out += (offset < 0 ? '-' : '+') + pad(Math.floor(minutes / 60), 2) + pad(minutes % 60, 2);\n        break;\n      }\n      case 'z': out += zoneName(time, timezone, offset); break;\n      default: throw new SyntaxError(`Unsupported date pattern letter \"${ch}\" in \"${pattern}\"`);\n    }\n  }\n  return out;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,sBAAwC;AAExC,MAAM,SAAS;AAAA,EAAC;AAAA,EAAW;AAAA,EAAY;AAAA,EAAS;AAAA,EAAS;AAAA,EAAO;AAAA,EAAQ;AAAA,EAAQ;AAAA,EAAU;AAAA,EACxF;AAAA,EAAW;AAAA,EAAY;AAAU;AACnC,MAAM,OAAO,CAAC,UAAU,UAAU,WAAW,aAAa,YAAY,UAAU,UAAU;AAE1F,MAAM,MAAM,CAAC,GAAW,UAA0B,OAAO,CAAC,EAAE,SAAS,OAAO,GAAG;AAE/E,SAAS,SAAS,MAAc,UAAkB,UAA0B;AAC1E,MAAI,aAAa,UAAW,QAAO;AACnC,MAAI,aAAa,KAAK,QAAQ,GAAG;AAC/B,QAAI,aAAa,EAAG,QAAO;AAC3B,UAAM,UAAU,KAAK,IAAI,QAAQ,IAAI;AACrC,WAAO,MAAM,WAAW,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,MAAM,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,IAAI,UAAU,IAAI,CAAC,CAAC;AAAA,EAClG;AACA,QAAM,OAAO,IAAI,KAAK,eAAe,SAAS,EAAE,UAAU,UAAU,cAAc,QAAQ,CAAC,EACxF,cAAc,IAAI,EAClB,KAAK,CAAC,MAAM,EAAE,SAAS,cAAc;AACxC,SAAO,MAAM,SAAS;AACxB;AAGA,SAAS,WAAW,MAAc,OAAe,KAAqB;AACpE,QAAM,OAAO,KAAK,IAAI,MAAM,QAAQ,GAAG,GAAG;AAC1C,QAAM,MAAM,IAAI,KAAK,IAAI,EAAE,UAAU;AACrC,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,YAAY,IAAI,SAAc,KAAK,IAAI,OAAO,GAAG,GAAG,CAAC,EAAG,QAAO;AACnE,QAAM,OAAO,KAAK,IAAI,MAAM,GAAG,CAAC;AAChC,QAAM,UAAU,IAAI,KAAK,IAAI,EAAE,UAAU;AACzC,SAAO,KAAK,OAAO,OAAO,OAAO,UAAU,UAAe,IAAI,MAAW,IAAI;AAC/E;AAGO,SAAS,WAAW,MAAc,SAAiB,UAA0B;AAClF,MAAI,OAAO,MAAM,IAAI,EAAG,QAAO;AAC/B,QAAM,QAAI,6BAAY,MAAM,QAAQ;AACpC,QAAM,aAAS,4BAAW,MAAM,QAAQ;AACxC,QAAM,MAAO,OAAO,MAAQ,OAAQ;AACpC,QAAM,aAAa,KAAK,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAG,EAAE,GAAG,IAAI,KAAK,IAAI,EAAE,MAAM,GAAG,CAAC,KAAK,QAAa;AAEjG,MAAI,MAAM;AACV,WAAS,IAAI,GAAG,IAAI,QAAQ,UAAU;AACpC,UAAM,KAAK,QAAQ,CAAC;AACpB,QAAI,OAAO,KAAK;AACd,YAAM,MAAM,QAAQ,QAAQ,KAAK,IAAI,CAAC;AACtC,UAAI,QAAQ,IAAI,GAAG;AACjB,eAAO;AACP,aAAK;AAAA,MACP,OAAO;AACL,eAAO,QAAQ,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAY,GAAG;AACxD,YAAI,QAAQ,KAAK,QAAQ,SAAS,MAAM;AAAA,MAC1C;AACA;AAAA,IACF;AACA,QAAI,CAAC,WAAW,KAAK,EAAE,GAAG;AACxB,aAAO;AACP;AACA;AAAA,IACF;AACA,QAAI,IAAI;AACR,WAAO,QAAQ,IAAI,CAAC,MAAM,GAAI;AAC9B,SAAK;AACL,UAAM,SAAS,EAAE,OAAO;AACxB,YAAQ,IAAI;AAAA,MACV,KAAK;AAAK,eAAO,MAAM,IAAI,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,IAAI,EAAE,MAAM,CAAC;AAAG;AAAA,MAClE,KAAK;AAAK,eAAO,KAAK,IAAI,OAAO,EAAE,QAAQ,CAAC,IAAI,MAAM,IAAI,OAAO,EAAE,QAAQ,CAAC,EAAG,MAAM,GAAG,CAAC,IAAI,IAAI,EAAE,OAAO,CAAC;AAAG;AAAA,MAC9G,KAAK;AAAK,eAAO,IAAI,EAAE,KAAK,CAAC;AAAG;AAAA,MAChC,KAAK;AAAK,eAAO,KAAK,IAAI,KAAK,EAAE,YAAY,CAAC,IAAI,KAAK,EAAE,YAAY,CAAC,EAAG,MAAM,GAAG,CAAC;AAAG;AAAA,MACtF,KAAK;AAAK,eAAO,IAAI,EAAE,cAAc,IAAI,IAAI,EAAE,YAAY,GAAG,CAAC;AAAG;AAAA,MAClE,KAAK;AAAK,eAAO,IAAI,WAAW,CAAC;AAAG;AAAA,MACpC,KAAK;AAAK,eAAO,IAAI,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;AAAG;AAAA,MAC7D,KAAK;AAAK,eAAO,IAAI,EAAE,MAAM,CAAC;AAAG;AAAA,MACjC,KAAK;AAAK,eAAO,IAAI,EAAE,SAAS,IAAI,KAAK,EAAE,MAAM,CAAC;AAAG;AAAA,MACrD,KAAK;AAAK,eAAO,IAAI,QAAQ,CAAC;AAAG;AAAA,MACjC,KAAK;AAAK,eAAO,IAAI,WAAW,IAAI,KAAK,QAAQ,CAAC;AAAG;AAAA,MACrD,KAAK;AAAK,eAAO,EAAE,OAAO,KAAK,OAAO;AAAM;AAAA,MAC5C,KAAK;AAAK,eAAO,IAAI,EAAE,QAAQ,CAAC;AAAG;AAAA,MACnC,KAAK;AAAK,eAAO,IAAI,EAAE,QAAQ,CAAC;AAAG;AAAA,MACnC,KAAK;AAAK,eAAO,IAAI,IAAI,CAAC;AAAG;AAAA,MAC7B,KAAK,KAAK;AACR,cAAM,UAAU,KAAK,IAAI,MAAM,IAAI;AACnC,gBAAQ,SAAS,IAAI,MAAM,OAAO,IAAI,KAAK,MAAM,UAAU,EAAE,GAAG,CAAC,IAAI,IAAI,UAAU,IAAI,CAAC;AACxF;AAAA,MACF;AAAA,MACA,KAAK;AAAK,eAAO,SAAS,MAAM,UAAU,MAAM;AAAG;AAAA,MACnD;AAAS,cAAM,IAAI,YAAY,oCAAoC,EAAE,SAAS,OAAO,GAAG;AAAA,IAC1F;AAAA,EACF;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/cjs/str/index.d.ts

@@ -0,0 +1,459 @@
+/**
+ * String namespace
+ * Mirrors PineScript's str.* functions for string manipulation and analysis.
+ *
+ * @remarks
+ * All string functions in this namespace follow PineScript v6 API specifications.
+ * String operations are case-sensitive unless otherwise specified.
+ *
+ * @version 6
+ */
+import type { int, bool, float, simple_int, simple_string } from '../types/index.js';
+/**
+ * Returns the length of a string.
+ *
+ * @param str - The string to measure
+ * @returns The number of characters in the string
+ *
+ * @example
+ * ```typescript
+ * str.length("Hello") // Returns: 5
+ * str.length("") // Returns: 0
+ * ```
+ */
+export declare function length(str: simple_string): int;
+/**
+ * Converts a value to its string representation (PineScript `str.tostring`).
+ *
+ * @param value - The value to convert (number, boolean, string, etc.)
+ * @param format - Optional number format: a pattern ("#.##", "#,###.00", "0.00%", "0.00E0") or
+ *   `format.percent` ("percent"), `format.volume` ("volume"), `format.price` / `format.inherit`
+ * @returns String representation of the value
+ *
+ * @remarks
+ * As in PineScript:
+ * - without format, numbers show up to 10 decimals ("0.3333333333"); 1e21 and more use "1E21"
+ * - patterns round half away from zero on the shortest decimal form: 1.005 with "#.##" gives "1.01"
+ * - "#" is an optional digit ("1.5" with "#.##"), "0" a required digit ("1.50" with "0.00"),
+ *   "," groups thousands, "%" multiplies by 100, 'text' is literal text
+ * - `format.percent` shows 2 decimals and "%" without multiplying; `format.volume` uses K, M, B, T
+ * - `format.price` and `format.inherit` give "price1" / "inherit1" in PineScript: they are patterns
+ *   without digit characters, and oakscriptjs does the same
+ * - `format.mintick` needs the symbol's tick size and throws here
+ *
+ * @example
+ * ```typescript
+ * str.tostring(123) // "123"
+ * str.tostring(1.5, "#.##") // "1.5"
+ * str.tostring(0.5, "#.00") // ".50"
+ * str.tostring(12345.678, format.volume) // "12.346K"
+ * ```
+ */
+export declare function tostring(value: any, format?: simple_string): string;
+/**
+ * Converts a string to a number (float).
+ *
+ * @param str - The string to convert
+ * @returns The numeric value, or null if conversion fails
+ *
+ * @remarks
+ * - Returns null for invalid number strings
+ * - Supports scientific notation (e.g., "1e3")
+ * - Supports decimal numbers (e.g., "0.5", ".5")
+ * - Whitespace is ignored
+ * - "NaN" string returns null
+ *
+ * @example
+ * ```typescript
+ * str.tonumber("123") // Returns: 123
+ * str.tonumber("45.67") // Returns: 45.67
+ * str.tonumber("abc") // Returns: null
+ * str.tonumber("1e3") // Returns: 1000
+ * ```
+ */
+export declare function tonumber(str: simple_string): float | null;
+/**
+ * Extracts a substring from a string.
+ *
+ * @param str - The source string
+ * @param begin - Starting index (0-based, inclusive)
+ * @param end - Ending index (0-based, exclusive). If omitted, extracts to end of string
+ * @returns The extracted substring
+ *
+ * @remarks
+ * - If begin > end, indices are swapped (JavaScript behavior)
+ * - Negative indices are treated as 0
+ * - Indices beyond string length return empty string
+ *
+ * @example
+ * ```typescript
+ * str.substring("hello world", 0, 5) // Returns: "hello"
+ * str.substring("hello world", 6) // Returns: "world"
+ * str.substring("test", 1, 3) // Returns: "es"
+ * ```
+ */
+export declare function substring(str: simple_string, begin: simple_int, end?: simple_int): string;
+/**
+ * Converts all characters in a string to uppercase.
+ *
+ * @param str - The string to convert
+ * @returns The uppercase string
+ *
+ * @example
+ * ```typescript
+ * str.upper("hello") // Returns: "HELLO"
+ * str.upper("Hello World") // Returns: "HELLO WORLD"
+ * str.upper("test123") // Returns: "TEST123"
+ * ```
+ */
+export declare function upper(str: simple_string): string;
+/**
+ * Converts all characters in a string to lowercase.
+ *
+ * @param str - The string to convert
+ * @returns The lowercase string
+ *
+ * @example
+ * ```typescript
+ * str.lower("HELLO") // Returns: "hello"
+ * str.lower("Hello World") // Returns: "hello world"
+ * str.lower("TEST123") // Returns: "test123"
+ * ```
+ */
+export declare function lower(str: simple_string): string;
+/**
+ * Checks if a string contains a substring.
+ *
+ * @param source - The string to search in
+ * @param str - The substring to search for
+ * @returns True if source contains str, false otherwise
+ *
+ * @remarks
+ * - Search is case-sensitive
+ * - Empty string is contained in any string
+ *
+ * @example
+ * ```typescript
+ * str.contains("hello world", "world") // Returns: true
+ * str.contains("hello world", "World") // Returns: false (case-sensitive)
+ * str.contains("test", "xyz") // Returns: false
+ * ```
+ */
+export declare function contains(source: simple_string, str: simple_string): bool;
+/**
+ * Returns the position of the first occurrence of a substring.
+ *
+ * @param source - The string to search in
+ * @param str - The substring to search for
+ * @returns The 0-based index of the first occurrence, or -1 if not found
+ *
+ * @remarks
+ * - Search is case-sensitive
+ * - Returns 0 for empty search string
+ * - Returns -1 if substring is not found
+ *
+ * @example
+ * ```typescript
+ * str.pos("hello world", "world") // Returns: 6
+ * str.pos("hello world", "o") // Returns: 4 (first occurrence)
+ * str.pos("hello", "xyz") // Returns: -1
+ * ```
+ */
+export declare function pos(source: simple_string, str: simple_string): int;
+/**
+ * Replaces occurrences of a substring with another string.
+ *
+ * @param source - The source string
+ * @param target - The substring to replace
+ * @param replacement - The string to replace with
+ * @param occurrence - If 0, replaces first occurrence only; otherwise replaces all occurrences (default: all)
+ * @returns The string with replacements made
+ *
+ * @remarks
+ * - Search is case-sensitive
+ * - If target is not found, returns source unchanged
+ * - occurrence parameter: 0 = first only, any other value = all occurrences
+ *
+ * @example
+ * ```typescript
+ * str.replace("hello world hello", "hello", "hi", 0) // Returns: "hi world hello"
+ * str.replace("hello world hello", "hello", "hi") // Returns: "hi world hi"
+ * str.replace("test", "xyz", "abc") // Returns: "test"
+ * ```
+ */
+export declare function replace(source: simple_string, target: simple_string, replacement: simple_string, occurrence?: simple_int): string;
+/**
+ * Replaces all occurrences of a target string with a replacement string.
+ *
+ * @param source - The source string
+ * @param target - The substring to find
+ * @param replacement - The replacement string
+ * @returns String with all occurrences replaced
+ *
+ * @remarks
+ * - Replaces all occurrences of the target string
+ * - Case sensitive
+ * - If target is empty string, returns original string
+ * - This matches PineScript's `str.replace_all()` behavior
+ *
+ * @example
+ * ```typescript
+ * str.replace_all("hello world hello", "hello", "hi") // Returns: "hi world hi"
+ * str.replace_all("a-b-c", "-", "_") // Returns: "a_b_c"
+ * str.replace_all("test", "x", "y") // Returns: "test" (no match)
+ * ```
+ */
+export declare function replace_all(source: simple_string, target: simple_string, replacement: simple_string): string;
+/**
+ * Splits a string into an array of substrings using a separator.
+ *
+ * @param str - The string to split
+ * @param separator - The separator string
+ * @returns Array of substrings
+ *
+ * @remarks
+ * - Empty separator splits into individual characters
+ * - If separator is not found, returns array with original string
+ * - Consecutive separators create empty strings in result
+ *
+ * @example
+ * ```typescript
+ * str.split("a,b,c", ",") // Returns: ["a", "b", "c"]
+ * str.split("hello", "") // Returns: ["h", "e", "l", "l", "o"]
+ * str.split("a,,b", ",") // Returns: ["a", "", "b"]
+ * ```
+ */
+export declare function split(str: simple_string, separator: simple_string): string[];
+/**
+ * Concatenates multiple strings into one.
+ *
+ * @param strings - Variable number of strings to concatenate
+ * @returns The concatenated string
+ *
+ * @example
+ * ```typescript
+ * str.concat("hello", " ", "world") // Returns: "hello world"
+ * str.concat("a", "b", "c") // Returns: "abc"
+ * str.concat("test") // Returns: "test"
+ * ```
+ */
+export declare function concat(...strings: simple_string[]): string;
+/**
+ * Formats a string with placeholders (PineScript `str.format`, Java MessageFormat syntax).
+ *
+ * @param formatStr - Pattern with `{0}`, `{1,number,#.##}`, `{0,number,percent}`, `{0,date,yyyy-MM-dd}`...
+ * @param args - Values for the placeholders
+ * @returns Formatted string
+ *
+ * @remarks
+ * As in PineScript: numbers in `{n}` use
+ * "#,##0.###" (1234.5678 gives "1,234.568"); number patterns round half to even on the exact
+ * value; `'...'` is literal text and `''` a quote; a missing argument leaves `{n}` in the text.
+ * Dates are formatted in UTC here; PineScript uses the exchange time zone.
+ *
+ * @example
+ * ```typescript
+ * str.format('Close: {0,number,#.##}', 101.456) // "Close: 101.46"
+ * str.format('{0} and {1}', 'a', 2) // "a and 2"
+ * ```
+ */
+export declare function format(formatStr: simple_string, ...args: any[]): string;
+/**
+ * Checks if a string starts with a specific prefix.
+ *
+ * @param source - The string to check
+ * @param str - The prefix to look for
+ * @returns True if source starts with str, false otherwise
+ *
+ * @remarks
+ * - Search is case-sensitive
+ * - Empty string prefix always returns true
+ *
+ * @example
+ * ```typescript
+ * str.startswith("hello world", "hello") // Returns: true
+ * str.startswith("hello world", "Hello") // Returns: false (case-sensitive)
+ * str.startswith("test", "testing") // Returns: false
+ * ```
+ */
+export declare function startswith(source: simple_string, str: simple_string): bool;
+/**
+ * Checks if a string ends with a specific suffix.
+ *
+ * @param source - The string to check
+ * @param str - The suffix to look for
+ * @returns True if source ends with str, false otherwise
+ *
+ * @remarks
+ * - Search is case-sensitive
+ * - Empty string suffix always returns true
+ *
+ * @example
+ * ```typescript
+ * str.endswith("hello world", "world") // Returns: true
+ * str.endswith("hello world", "World") // Returns: false (case-sensitive)
+ * str.endswith("testing", "test") // Returns: false
+ * ```
+ */
+export declare function endswith(source: simple_string, str: simple_string): bool;
+/**
+ * Returns the character at a specific position in a string.
+ *
+ * @param str - The source string
+ * @param pos - The 0-based position
+ * @returns The character at the position, or empty string if out of bounds
+ *
+ * @remarks
+ * - Returns empty string for negative or out-of-bounds positions
+ * - Unicode characters may span multiple code units
+ *
+ * @example
+ * ```typescript
+ * str.charAt("hello", 0) // Returns: "h"
+ * str.charAt("hello", 4) // Returns: "o"
+ * str.charAt("hello", 10) // Returns: ""
+ * ```
+ */
+export declare function charAt(str: simple_string, pos: simple_int): string;
+/**
+ * Removes whitespace from both ends of a string.
+ *
+ * @param str - The string to trim
+ * @returns The trimmed string
+ *
+ * @remarks
+ * - Removes spaces, tabs, newlines, and other whitespace characters
+ * - Preserves internal whitespace
+ *
+ * @example
+ * ```typescript
+ * str.trim("  hello  ") // Returns: "hello"
+ * str.trim("  hello world  ") // Returns: "hello world"
+ * str.trim("\thello\n") // Returns: "hello"
+ * ```
+ */
+export declare function trim(str: simple_string): string;
+/**
+ * Removes whitespace from the left (start) of a string.
+ *
+ * @param str - The string to trim
+ * @returns The trimmed string
+ *
+ * @remarks
+ * - Only removes leading whitespace
+ * - Preserves trailing and internal whitespace
+ *
+ * @example
+ * ```typescript
+ * str.trimLeft("  hello  ") // Returns: "hello  "
+ * str.trimLeft("  hello") // Returns: "hello"
+ * str.trimLeft("\thello") // Returns: "hello"
+ * ```
+ */
+export declare function trimLeft(str: simple_string): string;
+/**
+ * Removes whitespace from the right (end) of a string.
+ *
+ * @param str - The string to trim
+ * @returns The trimmed string
+ *
+ * @remarks
+ * - Only removes trailing whitespace
+ * - Preserves leading and internal whitespace
+ *
+ * @example
+ * ```typescript
+ * str.trimRight("  hello  ") // Returns: "  hello"
+ * str.trimRight("hello  ") // Returns: "hello"
+ * str.trimRight("hello\t") // Returns: "hello"
+ * ```
+ */
+export declare function trimRight(str: simple_string): string;
+/**
+ * Tests if a string matches a regular expression pattern.
+ *
+ * @param source - The string to test
+ * @param regex - The regular expression pattern
+ * @returns True if the pattern matches, false otherwise
+ *
+ * @remarks
+ * - Uses JavaScript regex syntax
+ * - Match is case-sensitive by default
+ * - Pattern is tested against entire string
+ *
+ * @example
+ * ```typescript
+ * str.match("hello123", "\\d+") // Returns: true
+ * str.match("test@example.com", "^[a-z]+@[a-z]+\\.[a-z]+$") // Returns: true
+ * str.match("abc", "[A-Z]+") // Returns: false
+ * ```
+ */
+export declare function match(source: simple_string, regex: simple_string): bool;
+/**
+ * Formats a timestamp as a string according to the specified format.
+ *
+ * @param time - Unix timestamp in milliseconds
+ * @param format - Format string using PineScript format specifiers
+ * @returns Formatted date/time string
+ *
+ * @remarks
+ * Supported format specifiers (case-sensitive):
+ * - `yyyy` - 4-digit year (e.g., "2024")
+ * - `yy` - 2-digit year (e.g., "24")
+ * - `MMMM` - Full month name (e.g., "January")
+ * - `MMM` - Abbreviated month name (e.g., "Jan")
+ * - `MM` - 2-digit month (01-12)
+ * - `M` - Month (1-12)
+ * - `dd` - 2-digit day (01-31)
+ * - `d` - Day (1-31)
+ * - `HH` - 2-digit hour (00-23)
+ * - `H` - Hour (0-23)
+ * - `hh` - 2-digit hour (01-12)
+ * - `h` - Hour (1-12)
+ * - `mm` - 2-digit minute (00-59)
+ * - `m` - Minute (0-59)
+ * - `ss` - 2-digit second (00-59)
+ * - `s` - Second (0-59)
+ * - `a` - AM/PM
+ *
+ * @example
+ * ```typescript
+ * const timestamp = 1609459200000; // Jan 1, 2021 00:00:00 UTC
+ * str.format_time(timestamp, "dd MMM yyyy") // Returns: "01 Jan 2021"
+ * str.format_time(timestamp, "yyyy-MM-dd HH:mm:ss") // Returns: "2021-01-01 00:00:00"
+ * str.format_time(timestamp, "MMM d, yyyy") // Returns: "Jan 1, 2021"
+ * str.format_time(timestamp, "hh:mm a") // Returns: "12:00 AM"
+ * ```
+ */
+/**
+ * Constructs a new string containing the source string repeated N times with an optional separator.
+ *
+ * @param source - The string to repeat
+ * @param count - Number of times to repeat (must be >= 0)
+ * @param separator - String to inject between repeated instances. Optional, defaults to empty string.
+ * @returns The repeated string, or null if source is null/undefined
+ *
+ * @example
+ * ```typescript
+ * str.repeat("ab", 3) // Returns: "ababab"
+ * str.repeat("?", 3, ",") // Returns: "?,?,?"
+ * str.repeat("hello", 0) // Returns: ""
+ * str.repeat("x", 1) // Returns: "x"
+ * ```
+ */
+export declare function repeat(source: simple_string, count: simple_int, separator?: simple_string): string | null;
+/**
+ * Formats a UNIX time (ms) with a date pattern (PineScript `str.format_time`).
+ *
+ * @param time - UNIX time in milliseconds
+ * @param format - Java SimpleDateFormat pattern, e.g. "yyyy-MM-dd HH:mm:ss", "dd MMM yyyy", "hh:mm a"
+ * @param timezone - UTC/GMT offset ("UTC-5") or IANA name ("America/New_York"). PineScript's default is
+ *   the exchange time zone, which is not known here: the default is UTC
+ * @returns Formatted date string
+ *
+ * @remarks
+ * Letters: y, M, d, E, u, D, w,
+ * H, k, K, h, a, m, s, S, Z, z; 'text' is literal text.
+ */
+export declare function format_time(time: simple_int, format?: simple_string, timezone?: simple_string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/str/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/str/index.ts"],"names":[],"mappings":"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"}