fix: document function substring and change it into a standalone function

Author: josdejong

docs/index.html

@@ -179,6 +179,10 @@ <h1>JSON Query</h1>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#split"
                     target="_blank"><code>split(text, separator)</code></a>
                 </li>
+                <li>
+                  <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#substring"
+                    target="_blank"><code>substring(text, start, end)</code></a>
+                </li>
                 <li>
                   <a href="https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#uniq"
                     target="_blank"><code>uniq()</code></a>
@@ -480,7 +484,7 @@ <h3 class="title">Debugger</h3>
   </div>
 
   <script type="module">
-    import { jsonquery, stringify, parse, compile } from 'https://cdn.jsdelivr.net/npm/@jsonquerylang/jsonquery@4/lib/jsonquery.js'
+    import { jsonquery, stringify, parse, compile } from '../lib/jsonquery.js'
     import { Formatter, FracturedJsonOptions } from 'https://cdn.jsdelivr.net/npm/fracturedjsonjs/+esm'
 
     window.jsonquery = { jsonquery, stringify, parse, compile }

reference/functions.md

@@ -531,6 +531,32 @@ jsonquery(data, 'split("a,b,c", ",")')
 // ["a", "b", "c"]
 ```
 
+## substring
+
+Extract a substring from a string. When `end` is not provided, the length of the string will be used as `end`.
+
+```text
+substring(text, start)
+substring(text, start, end)
+```
+
+Examples:
+
+```js
+const events = [
+  {"type": "start", "time": "2024-11-06 23:14:00" },
+  {"type": "initialize", "time": "2025-11-08 09:00:00" },
+  {"type": "end", "time": "2025-11-24 10:27:00" }
+]
+
+jsonquery(events, 'map(substring(.time, 0, 10))')
+// [
+//   "2024-11-06",
+//   "2025-11-08",
+//   "2025-11-24"
+// ]
+```
+
 ## uniq
 
 Create a copy of an array where all duplicates are removed.

src/functions.ts

@@ -210,7 +210,9 @@ export const functions: FunctionBuildersMap = {
     separator !== undefined ? text.split(separator) : text.trim().split(/\s+/)
   ),
 
-  substring: (start: number, end: number) => (data: string) => data.slice(Math.max(start, 0), end),
+  substring: buildFunction((text: string, start: number, end?: number) =>
+    text.slice(Math.max(start, 0), end)
+  ),
 
   uniq:
     () =>

test-suite/compile.test.json

@@ -543,42 +543,42 @@
       "category": "substring",
       "description": "should get a substring of a string with a start index",
       "input": "123456",
-      "query": ["substring", 3],
+      "query": ["substring", ["get"], 3],
       "output": "456"
     },
     {
       "category": "substring",
       "description": "should get a substring of a string with a start and end index",
-      "input": "123456",
-      "query": ["substring", 2, 4],
+      "input": { "value": "123456" },
+      "query": ["substring", ["get", "value"], 2, 4],
       "output": "34"
     },
     {
       "category": "substring",
       "description": "should get a substring of a string with a start exceeding the string length",
-      "input": "123456",
-      "query": ["substring", 10],
+      "input": null,
+      "query": ["substring", "123456", 10],
       "output": ""
     },
     {
       "category": "substring",
       "description": "should get a substring of a string with an end exceeding the string length",
-      "input": "123456",
-      "query": ["substring", 0, 10],
+      "input": null,
+      "query": ["substring", "123456", 0, 10],
       "output": "123456"
     },
     {
       "category": "substring",
       "description": "should get a substring of a string with an end index smaller than the start index",
-      "input": "123456",
-      "query": ["substring", 3, 0],
+      "input": null,
+      "query": ["substring", "123456", 3, 0],
       "output": ""
     },
     {
       "category": "substring",
       "description": "should get a substring of a string with a negative start index",
-      "input": "123456",
-      "query": ["substring", -2],
+      "input": null,
+      "query": ["substring", "123456", -2],
       "output": "123456"
     },