Document str_split trailing separator behavior

CHANGELOG.md

@@ -11,6 +11,7 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Made `gh_run` report failed GitHub CLI commands even when callers enable
   `set -e`, and preserved argument boundaries in GitHub command failure logs.
+- Documented and tested `str_split` trailing-separator behavior.
 
 ## [1.2.0] - 2026-07-04
 

lib/bash/str/README.md

@@ -60,6 +60,8 @@ str_join joined "|" parts
 - Predicate helpers require exactly two arguments, return shell status, and do
   not print output.
 - `str_split` preserves empty fields between repeated delimiters.
+- `str_split` preserves a trailing empty field when the input ends with the
+  separator.
 - `str_join` preserves empty array elements, including trailing empty elements.
 - Use `list_contains` from `lib/bash/list/lib_list.sh` for indexed-array
   membership checks.

lib/bash/str/lib_str.sh

@@ -75,6 +75,8 @@ str_ends_with() {
     [[ "$value" == *"$suffix" ]]
 }
 
+# Splits a value into a caller-owned indexed array. Empty fields are preserved,
+# including the final empty field produced by a trailing separator.
 str_split() {
     local __str_split_result_name="${1-}" __str_split_value="${2-}" __str_split_separator="${3-}"
 

lib/bash/str/tests/lib_str.bats

@@ -137,6 +137,17 @@ EOF
     [ "${parts[3]}" = "gamma" ]
 }
 
+@test "str_split preserves a trailing empty field after a trailing separator" {
+    local -a parts=()
+
+    str_split parts "alpha,beta," ","
+
+    [ "${#parts[@]}" -eq 3 ]
+    [ "${parts[0]}" = "alpha" ]
+    [ "${parts[1]}" = "beta" ]
+    [ "${parts[2]}" = "" ]
+}
+
 @test "str_split can store results in an array named fields" {
     local -a fields=()