From fe670d7440dc28beae5f0c08abe577a5f8f97089 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20F=C3=A4rber?= <01mf02@gmail.com>
Date: Thu, 3 Jul 2025 14:38:36 +0200
Subject: [PATCH 1/3] Convert inputs of `join` to strings.

This should close #289.
---
 jaq-std/src/defs.jq | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/jaq-std/src/defs.jq b/jaq-std/src/defs.jq
index 7d328ce48..cde55c50d 100644
--- a/jaq-std/src/defs.jq
+++ b/jaq-std/src/defs.jq
@@ -84,7 +84,7 @@ def map(f): [.[] | f];
 def map_values(f): .[] |= f;
 def add(f): reduce f as $x (null; . + $x);
 def add: add(.[]);
-def join(x): .[:-1][] += x | add;
+def join($x): .[] |= tostring | .[:-1][] += $x | add + "";
 def min_by(f): reduce min_by_or_empty(f) as $x (null; $x);
 def max_by(f): reduce max_by_or_empty(f) as $x (null; $x);
 def min: min_by(.);

From 283eafbfde84d5992c673bcbe89bc424928a1f88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20F=C3=A4rber?= <01mf02@gmail.com>
Date: Thu, 3 Jul 2025 14:43:42 +0200
Subject: [PATCH 2/3] Adapt tests to new `join` semantics.

---
 jaq-std/tests/defs.rs | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/jaq-std/tests/defs.rs b/jaq-std/tests/defs.rs
index 3698f466a..f65f24ae3 100644
--- a/jaq-std/tests/defs.rs
+++ b/jaq-std/tests/defs.rs
@@ -76,14 +76,13 @@ yields!(
     false
 );
 
-yields!(join_empty, r#"[] | join(" ")"#, json!(null));
+yields!(join_empty, r#"[] | join(" ")"#, "");
 yields!(
     join_strs,
     r#"["Hello", "world"] | join(" ")"#,
     "Hello world"
 );
-// 2 + 1 + 3 + 1 + 4 + 1 + 5
-yields!(join_nums, r#"[2, 3, 4, 5] | join(1)"#, 17);
+yields!(join_nums, r#"[2, 3, 4, 5] | join(",")"#, "2,3,4,5");
 
 yields!(map, "[1, 2] | map(.+1)", [2, 3]);
 

From 8610a68917b02a2eeae6907b36f61183342a960e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20F=C3=A4rber?= <01mf02@gmail.com>
Date: Mon, 7 Jul 2025 10:31:09 +0200
Subject: [PATCH 3/3] Update differences between jq and jaq for `join/1`.

---
 README.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e2e41d74d..b4be23a23 100644
--- a/README.md
+++ b/README.md
@@ -569,10 +569,11 @@ The interpretation of `reduce`/`foreach` in jaq has the following advantages ove
   When there is no more input value left,
   in jq, `input` yields an error, whereas in jaq, it yields no output value.
 * Joining:
-  When given an array `[x0, x1, ..., xn]`,
-  in jq, `join(x)` converts all elements of the input array to strings and intersperses them with `x`, whereas
-  in jaq, `join(x)` simply calculates `x0 + x + x1 + x + ... + xn`.
-  When all elements of the input array and `x` are strings, jq and jaq yield the same output.
+  When giving an array `[x1, ..., xn]` to `join($sep)`, jaq returns
+  `""` if the array is empty, otherwise `"\(x1)" + $sep + ... + $sep + "\(xn)"`;
+  that is, it concatenates the string representations of the array values interspersed with `$sep`.
+  Unlike jq, jaq does not map `null` values in the array to `""`,
+  nor does it reject array or object values in the array.