Add bit_array.to_string_lossy

CHANGELOG.md

@@ -7,6 +7,7 @@
   the JavaScript target.
 - Fixed a bug where tuples with atoms in the first position could be formatted
   incorrectly by `string.inspect`.
+- The `bit_array` module gains the `to_string_lossy` function.
 
 ## v0.56.0 - 2025-03-09
 

src/gleam/bit_array.gleam

@@ -95,6 +95,46 @@ pub fn to_string(bits: BitArray) -> Result(String, Nil) {
 @external(erlang, "gleam_stdlib", "identity")
 fn unsafe_to_string(a: BitArray) -> String
 
+/// Converts a bit array to a string. Invalid bits are passed to the provided
+/// callback and its result is included in the final string in place of the
+/// invalid data.
+///
+/// ## Examples
+///
+/// ```gleam
+/// to_string_lossy(<<"A":utf8, 0x80, "1":utf8, 0:size(5)>>, fn(_) { "�" })
+/// // -> "A�1�"
+/// ```
+/// 
+pub fn to_string_lossy(
+  bits: BitArray,
+  map_invalid_bits: fn(BitArray) -> String,
+) -> String {
+  to_string_lossy_impl(bits, map_invalid_bits, "")
+}
+
+fn to_string_lossy_impl(
+  bits: BitArray,
+  map_invalid_bits: fn(BitArray) -> String,
+  acc: String,
+) -> String {
+  case bits {
+    <<>> -> acc
+
+    <<x:utf8_codepoint, rest:bits>> ->
+      to_string_lossy_impl(
+        rest,
+        map_invalid_bits,
+        acc <> string.from_utf_codepoints([x]),
+      )
+
+    <<x:bytes-1, rest:bits>> ->
+      to_string_lossy_impl(rest, map_invalid_bits, acc <> map_invalid_bits(x))
+
+    _ -> acc <> map_invalid_bits(bits)
+  }
+}
+
 /// Creates a new bit array by joining multiple binaries.
 ///
 /// ## Examples

test/gleam/bit_array_test.gleam

@@ -207,6 +207,26 @@ pub fn to_string_test() {
   |> should.equal(Ok("ø"))
 }
 
+pub fn to_string_lossy_test() {
+  <<>>
+  |> bit_array.to_string_lossy(fn(_) { "�" })
+  |> should.equal("")
+
+  <<0x80, "A":utf8, 0x81>>
+  |> bit_array.to_string_lossy(fn(_) { "�" })
+  |> should.equal("�A�")
+
+  // Test some codepoints that require 2/3/4 bytes to be stored as UTF-8
+  <<"£И한𐍈":utf8>>
+  |> bit_array.to_string_lossy(fn(_) { "�" })
+  |> should.equal("£И한𐍈")
+
+  // Test unaligned bit array
+  <<"ø":utf8, 50:4>>
+  |> bit_array.to_string_lossy(fn(_) { "�" })
+  |> should.equal("ø�")
+}
+
 pub fn is_utf8_test() {
   <<>>
   |> bit_array.is_utf8