oakscriptjs 0.9.5 → 0.10.0

package/src/str/index.ts

@@ -12,6 +12,7 @@
 import { formatNumber } from './numberformat.js';
 import { formatMessage } from './messageformat.js';
 import { formatDate } from './dateformat.js';
+import { round_to_mintick } from '../math/index.js';
 import type { int, bool, float, simple_int, simple_string } from '../types/index.js';
 
 /**
@@ -34,20 +35,28 @@ export 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`
+ * @param format - Optional number format: a pattern ("#.##", "#,###.00", "0.00%", "0.00E0", "#.##;(#.##)") or
+ *   `format.percent` ("percent"), `format.volume` ("volume"), `format.mintick` ("mintick"),
+ *   `format.price` / `format.inherit`
+ * @param mintick - Tick size for `format.mintick` (PineScript `syminfo.mintick`, implicit there). Not part of the
+ *   PineScript signature: the core function cannot see the chart, so pass it, as for `math.round_to_mintick`
  * @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"
+ * - patterns round half away from zero on the shortest decimal form: 1.005 with "#.##" gives "1.01";
+ *   at most 16 decimals from 1e-3 up (0.0012345678901234567 with 20 '#' decimals gives "0.0012345678901235")
+ * - "pos;neg" patterns: a negative number takes the text of the negative subpattern ("#.##;(#.##)": "(3.5)")
  * - "#" 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
+ * - `format.mintick` rounds to the tick (`math.round_to_mintick`) and shows the tick's decimals ("#.##" for 0.01);
+ *   it throws without `mintick`
+ * - na gives "NaN" ("NaN%" with `format.percent`); an infinity gives "NaN" too ("NaN%" for `format.percent`,
+ *   "NaNT" for `format.volume`), except `format.mintick`, which gives "Infinity" / "-Infinity"
  *
  * @example
  * ```typescript
@@ -57,9 +66,14 @@ export function length(str: simple_string): int {
  * str.tostring(12345.678, format.volume) // "12.346K"
  * ```
  */
-export function tostring(value: any, format?: simple_string): string {
+export function tostring(value: any, format?: simple_string, mintick?: float): string {
   if (typeof value !== 'number') return String(value);
-  if (!Number.isFinite(value)) return String(value); // NaN (na), Infinity
+  if (Number.isNaN(value)) return format === 'percent' ? 'NaN%' : 'NaN';
+  if (!Number.isFinite(value)) {
+    // the chart formatter has no infinity: NaN with the format's suffix
+    if (format === 'mintick') return String(value);
+    return format === 'percent' ? 'NaN%' : format === 'volume' ? 'NaNT' : 'NaN';
+  }
   if (format === undefined || format === '') {
     if (Math.abs(value) >= 1e21 && Number.isFinite(value)) {
       return String(value).replace('e+', 'E').replace(/\.0+E/, 'E');
@@ -76,8 +90,16 @@ export function tostring(value: any, format?: simple_string): string {
       }
       return formatNumber(value, '#', 'halfUpShortest');
     }
-    case 'mintick':
-      throw new Error('str.tostring(x, format.mintick) needs the symbol tick size (syminfo.mintick), which is not known here');
+    case 'mintick': {
+      if (mintick === undefined) {
+        throw new Error('str.tostring(x, format.mintick) needs the tick size: pass it as str.tostring(x, format.mintick, syminfo.mintick)');
+      }
+      // mask: one '#' per decimal of the tick ("#.##" for 0.01, "#" for 1)
+      const m = /^\d+(?:\.(\d+))?(?:e-(\d+))?$/.exec(String(mintick));
+      const decimals = m ? (m[1]?.length ?? 0) + Number(m[2] ?? 0) : 0;
+      const mask = decimals ? '#.' + '#'.repeat(decimals) : '#';
+      return formatNumber(round_to_mintick(value, mintick), mask, 'halfUpShortest');
+    }
     default:
       return formatNumber(value, format, 'halfUpShortest');
   }
@@ -87,26 +109,33 @@ export 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
+ * @returns The numeric value, or null (na) 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
+ * As in PineScript:
+ * - The whole text must be a number: a sign, digits and one optional "." ("0.5", ".5", "5.", "-12"); "12abc" is na
+ * - Scientific notation ("1e3"), "Infinity", "NaN", hexadecimal, "1,000" give na
+ * - The characters U+0000 to U+0020 (space, tab, line feed...) around the number are ignored; other spaces
+ *   (no-break space U+00A0, U+3000) give na
  *
  * @example
  * ```typescript
  * str.tonumber("123") // Returns: 123
  * str.tonumber("45.67") // Returns: 45.67
  * str.tonumber("abc") // Returns: null
- * str.tonumber("1e3") // Returns: 1000
+ * str.tonumber("12abc") // Returns: null
+ * str.tonumber("1e3") // Returns: null
  * ```
  */
 export function tonumber(str: simple_string): float | null {
-  const num = parseFloat(str);
-  return isNaN(num) ? null : num;
+  // remove the characters U+0000..U+0020 at both ends
+  let start = 0;
+  let end = str.length;
+  while (start < end && str.charCodeAt(start) <= 0x20) start++;
+  while (end > start && str.charCodeAt(end - 1) <= 0x20) end--;
+  const text = str.slice(start, end);
+  if (!/^[+-]?(?:\d+\.?\d*|\.\d+)$/.test(text)) return null;
+  return parseFloat(text);
 }
 
 /**
@@ -118,6 +147,7 @@ export function tonumber(str: simple_string): float | null {
  * @returns The extracted substring
  *
  * @remarks
+ * - An na `end` (NaN / null) is a runtime error in PineScript: it throws
  * - If begin > end, indices are swapped (JavaScript behavior)
  * - Negative indices are treated as 0
  * - Indices beyond string length return empty string
@@ -130,6 +160,7 @@ export function tonumber(str: simple_string): float | null {
  * ```
  */
 export function substring(str: simple_string, begin: simple_int, end?: simple_int): string {
+  if (end === null || Number.isNaN(end)) throw new Error('str.substring: the end position is na');
   return str.substring(begin, end);
 }
 
@@ -194,51 +225,63 @@ export function contains(source: simple_string, str: simple_string): bool {
  *
  * @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
+ * @returns The 0-based index of the first occurrence, or na (NaN) if not found
  *
  * @remarks
  * - Search is case-sensitive
  * - Returns 0 for empty search string
- * - Returns -1 if substring is not found
+ * - Returns na (NaN) if substring is not found, as in PineScript
  *
  * @example
  * ```typescript
  * str.pos("hello world", "world") // Returns: 6
  * str.pos("hello world", "o") // Returns: 4 (first occurrence)
- * str.pos("hello", "xyz") // Returns: -1
+ * str.pos("hello", "xyz") // Returns: NaN (na)
  * ```
  */
 export function pos(source: simple_string, str: simple_string): int {
-  return source.indexOf(str);
+  const index = source.indexOf(str);
+  return index === -1 ? NaN : index;
 }
 
 /**
- * Replaces occurrences of a substring with another string.
+ * Replaces the Nth occurrence of a substring (PineScript `str.replace`).
  *
  * @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
+ * @param occurrence - 0-based occurrence to replace (default 0, the first one)
+ * @returns The string with one occurrence replaced
  *
  * @remarks
- * - Search is case-sensitive
- * - If target is not found, returns source unchanged
- * - occurrence parameter: 0 = first only, any other value = all occurrences
+ * PineScript rules:
+ * - only the Nth occurrence is replaced; an na occurrence is 0 (`str.replace("aaa", "a", "-", na)` is "-aa")
+ * - occurrences overlap: "aa" occurs at 0 and 1 in "aaa" (`str.replace("aaa", "aa", "-", 1)` is "a-")
+ * - an empty target inserts the replacement at character N, at most at the end
+ *   (`str.replace("abc", "", "-", 2)` is "ab-c")
+ * - fewer than N + 1 occurrences (or a negative N) leave the source unchanged
  *
  * @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("hello world hello", "hello", "hi") // Returns: "hi world hello"
+ * str.replace("hello world hello", "hello", "hi", 1) // Returns: "hello world hi"
  * str.replace("test", "xyz", "abc") // Returns: "test"
  * ```
  */
-export function replace(source: simple_string, target: simple_string, replacement: simple_string, occurrence?: simple_int): string {
-  if (occurrence === 0) {
-    return source.replace(target, replacement);
+export function replace(source: simple_string, target: simple_string, replacement: simple_string, occurrence: simple_int = 0): string {
+  const n = occurrence === null || Number.isNaN(occurrence) ? 0 : Math.trunc(occurrence);
+  if (n < 0) return source;
+  let index: number;
+  if (target === '') {
+    index = Math.min(n, source.length);
   } else {
-    return source.replaceAll(target, replacement);
+    index = -1;
+    for (let k = 0; k <= n; k++) {
+      index = source.indexOf(target, index + 1);
+      if (index === -1) return source;
+    }
   }
+  return source.slice(0, index) + replacement + source.slice(index + target.length);
 }
 
 /**
@@ -274,7 +317,7 @@ export function replace_all(source: simple_string, target: simple_string, replac
  * @returns Array of substrings
  *
  * @remarks
- * - Empty separator splits into individual characters
+ * - Empty separator splits into individual characters; an empty string gives [""] (also with "")
  * - If separator is not found, returns array with original string
  * - Consecutive separators create empty strings in result
  *
@@ -286,7 +329,8 @@ export function replace_all(source: simple_string, target: simple_string, replac
  * ```
  */
 export function split(str: simple_string, separator: simple_string): string[] {
-  return str.split(separator);
+  // JavaScript gives [] for "".split(""); PineScript gives [""]
+  return str === '' ? [''] : str.split(separator);
 }
 
 /**
@@ -316,7 +360,8 @@ export function concat(...strings: simple_string[]): 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.
+ * value (16 decimals at most from 1e-3 up); an array gives "[a, b]"; `'...'` 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
@@ -459,26 +504,25 @@ export function trimRight(str: simple_string): string {
 }
 
 /**
- * Tests if a string matches a regular expression pattern.
+ * Returns the first substring of `source` that matches the `regex` (PineScript `str.match`).
  *
- * @param source - The string to test
- * @param regex - The regular expression pattern
- * @returns True if the pattern matches, false otherwise
+ * @param source - Source string
+ * @param regex - Regular expression
+ * @returns The first match (searched anywhere in the string), or na (null) when nothing matches or the match is empty
  *
  * @remarks
+ * - As PineScript: "Hello World!" with "o" gives "o", with "[a-z]+" gives "ello"; no match gives na
  * - 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
+ * str.match("abc123def", "[0-9]+") // Returns: "123"
+ * str.match("abc", "[0-9]+") // Returns: null (na)
  * ```
  */
-export function match(source: simple_string, regex: simple_string): bool {
-  return new RegExp(regex).test(source);
+export function match(source: simple_string, regex: simple_string): simple_string | null {
+  const found = new RegExp(regex).exec(source);
+  return found && found[0] !== '' ? found[0] : null;
 }
 
 /**
@@ -521,21 +565,21 @@ export function match(source: simple_string, regex: simple_string): bool {
  * 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 count - Number of times to repeat
  * @param separator - String to inject between repeated instances. Optional, defaults to empty string.
- * @returns The repeated string, or null if source is null/undefined
+ * @returns The repeated string, or null (na) if source is na or count is 0 / negative / na, as in PineScript
  *
  * @example
  * ```typescript
  * str.repeat("ab", 3) // Returns: "ababab"
  * str.repeat("?", 3, ",") // Returns: "?,?,?"
- * str.repeat("hello", 0) // Returns: ""
+ * str.repeat("hello", 0) // Returns: null (na)
  * str.repeat("x", 1) // Returns: "x"
  * ```
  */
 export function repeat(source: simple_string, count: simple_int, separator: simple_string = ''): string | null {
   if (source == null) return null;
-  if (count <= 0) return '';
+  if (!(count > 0)) return null; // 0, negative or na: na
   return Array(count).fill(source).join(separator);
 }
 

package/src/str/messageformat.ts

@@ -1,7 +1,8 @@
 /**
  * `str.format` patterns as PineScript formats them (Java MessageFormat):
  *
- * - `{n}` inserts argument n; numbers use "#,##0.###" (1234.5678 gives "1,234.568")
+ * - `{n}` inserts argument n; numbers use "#,##0.###" (1234.5678 gives "1,234.568"); an array gives
+ *   "[Hello, World!]"
  * - `{n,number}`, `{n,number,integer}` ("#,##0"), `{n,number,percent}` ("#,##0%"),
  *   `{n,number,currency}` ("$1,234.57", "-$7.00"), `{n,number,<pattern>}`
  * - `{n,date}`, `{n,time}`, `{n,date,<pattern>}`, `{n,time,<pattern>}` (styles short, medium, long, full)
@@ -44,7 +45,11 @@ function formatArgument(
   timezone: string | (() => string)
 ): string {
   if (value === undefined) return '';
-  if (!type) return typeof value === 'number' ? number(value, '#,##0.###') : String(value);
+  if (!type) {
+    // an array gives "[a, b]" (PineScript); the element format of numbers is not measured: plain JS text
+    if (Array.isArray(value)) return '[' + value.map((v) => (v == null ? 'NaN' : String(v))).join(', ') + ']';
+    return typeof value === 'number' ? number(value, '#,##0.###') : String(value);
+  }
   switch (type.trim()) {
     case 'number': {
       const s = style?.trim();

package/src/str/numberformat.ts

@@ -12,6 +12,10 @@
  * - with an exponent, the value is first rounded to the fraction digits ("0.00E0": 0.125 gives "1.30E-1")
  * - a pattern without digit characters (`format.price` is "price") formats like "#" after its text,
  *   and keeps the sign: -0.004 gives "-price0"
+ * - "pos;neg": a negative number uses the text around the digits of the negative subpattern instead of "-"
+ *   ("#.##;(#.##)" gives "(3.5)" for -3.5); the digits follow the positive subpattern, as in Java
+ * - at most 16 decimals when |x| >= 1e-3 (the shortest digits of a double never have more there):
+ *   0.1 with 20 '#' decimals gives "0.1" in both rounding modes
  */
 
 export type Rounding = 'halfUpShortest' | 'halfEvenExact';
@@ -19,6 +23,9 @@ export type Rounding = 'halfUpShortest' | 'halfEvenExact';
 interface Pattern {
   prefix: string;
   suffix: string;
+  /** Text around the digits of the negative subpattern ("pos;neg"), or null without one */
+  negPrefix: string | null;
+  negSuffix: string | null;
   minInt: number;
   minFrac: number;
   maxFrac: number;
@@ -32,9 +39,27 @@ interface Pattern {
 
 const patterns = new Map<string, Pattern>();
 
+/** Index of the first ';' outside quotes, or -1. */
+function subpatternSplit(pattern: string): number {
+  let quoted = false;
+  for (let i = 0; i < pattern.length; i++) {
+    if (pattern[i] === "'") quoted = !quoted;
+    else if (pattern[i] === ';' && !quoted) return i;
+  }
+  return -1;
+}
+
 function parsePattern(pattern: string): Pattern {
   const cached = patterns.get(pattern);
   if (cached) return cached;
+  const semi = subpatternSplit(pattern);
+  if (semi !== -1) {
+    // only the text around the digits of the negative subpattern is used
+    const neg = parsePattern(pattern.slice(semi + 1));
+    const parsed = { ...parsePattern(pattern.slice(0, semi)), negPrefix: neg.prefix, negSuffix: neg.suffix };
+    patterns.set(pattern, parsed);
+    return parsed;
+  }
 
   let prefix = '';
   let suffix = '';
@@ -72,6 +97,8 @@ function parsePattern(pattern: string): Pattern {
   const parsed: Pattern = {
     prefix,
     suffix,
+    negPrefix: null,
+    negSuffix: null,
     // as in Java, a pattern with a decimal point and no '0' at all ("#.##") shows one integer digit
     minInt: !mantissa.includes('0') && mantissa.includes('.') ? 1 : [...intPart].filter((c) => c === '0').length,
     minFrac: [...fracPart].filter((c) => c === '0').length,
@@ -169,7 +196,7 @@ function layout(d: Digits, p: Pattern): string {
 export function formatNumber(value: number, pattern: string, mode: Rounding): string {
   if (Number.isNaN(value)) return 'NaN';
   const p = parsePattern(pattern);
-  if (!Number.isFinite(value)) return (value < 0 ? '-' : '') + p.prefix + '∞' + p.suffix;
+  if (!Number.isFinite(value)) return affixes(p, value < 0, '∞');
   const x = p.percent ? value * 100 : value;
   const toDigits = mode === 'halfUpShortest' ? shortestDigits : exactDigits;
 
@@ -188,10 +215,18 @@ export function formatNumber(value: number, pattern: string, mode: Rounding): st
     const e = String(Math.abs(exponent)).padStart(p.exponent, '0');
     body = layout(mant, p) + 'E' + (exponent < 0 ? '-' : '') + e;
   } else {
-    const rounded = roundDigits(toDigits(x), p.hasDigits ? p.maxFrac : 0, mode);
+    // 16 decimals at most from 1e-3 up (the shortest digits of a double have no more there)
+    const frac = !p.hasDigits ? 0 : Math.abs(x) >= 1e-3 ? Math.min(p.maxFrac, 16) : p.maxFrac;
+    const rounded = roundDigits(toDigits(x), frac, mode);
     isZero = rounded.digits === '';
     body = p.hasDigits ? layout(rounded, p) : layout(rounded, { ...p, minInt: 0, maxFrac: 0, minFrac: 0 });
   }
-  const negative = x < 0 && (!isZero || !p.hasDigits);
-  return (negative ? '-' : '') + p.prefix + body + p.suffix;
+  return affixes(p, x < 0 && (!isZero || !p.hasDigits), body);
+}
+
+/** `body` with the text of the positive pattern, or of the negative one ("-" + prefix without "pos;neg"). */
+function affixes(p: Pattern, negative: boolean, body: string): string {
+  if (!negative) return p.prefix + body + p.suffix;
+  if (p.negPrefix === null) return '-' + p.prefix + body + p.suffix;
+  return p.negPrefix + body + p.negSuffix!;
 }