add rtrunc, ltrunc, ctrunc for truncating strings

Co-Authored-By: Timothy <[email protected]>

Author: IanButterworth

NEWS.md

@@ -102,6 +102,7 @@ New library features
   the uniquing checking ([#53474])
 * `RegexMatch` objects can now be used to construct `NamedTuple`s and `Dict`s ([#50988])
 * `Lockable` is now exported ([#54595])
+* New `ltrunc`, `rtrunc` and `ctrunc` functions for truncating strings to text width, accounting for char widths ([#55351])
 
 Standard library changes
 ------------------------

base/exports.jl

@@ -596,6 +596,7 @@ export
     codepoint,
     codeunit,
     codeunits,
+    ctrunc,
     digits,
     digits!,
     eachsplit,
@@ -620,6 +621,7 @@ export
     join,
     lpad,
     lstrip,
+    ltrunc,
     ncodeunits,
     ndigits,
     nextind,
@@ -632,6 +634,7 @@ export
     rpad,
     rsplit,
     rstrip,
+    rtrunc,
     split,
     string,
     strip,

base/strings/util.jl

@@ -513,6 +513,126 @@ function rpad(
     r == 0 ? stringfn(s, p^q) : stringfn(s, p^q, first(p, r))
 end
 
+"""
+    rtrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…")
+
+Truncate `str` to at most `w` characters (see [`textwidth`](@ref)), replacing the last characters
+with `replace_str` if necessary. The default replacement string is "…".
+
+# Examples
+```jldoctest
+julia> s = rtrunc("🍕🍕 I love 🍕", 10)
+"🍕🍕 I lo…"
+
+julia> textwidth(s)
+10
+
+julia> rtrunc("foo", 3)
+"foo"
+```
+
+!!! compat "Julia 1.12"
+    This function was added in Julia 1.12.
+
+See also [`ltrunc`](@ref) and [`ctrunc`](@ref).
+"""
+function rtrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…")
+    if textwidth(str) <= w
+        return str
+    else
+        i, accwidth = firstindex(str), textwidth(replace_str)
+        while true
+            tw = textwidth(str[i])
+            accwidth + tw <= w || break # no need to check if we go out of bounds because of the first if branch
+            accwidth += tw
+            i = nextind(str, i)
+        end
+        return str[firstindex(str):prevind(str, i)] * replace_str
+    end
+end
+
+"""
+    ltrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…")
+
+Truncate `str` to at most `w` characters (see [`textwidth`](@ref)), replacing the first characters
+with `replace_str` if necessary. The default replacement string is "…".
+
+# Examples
+```jldoctest
+julia> s = ltrunc("🍕🍕 I love 🍕", 10)
+"…I love 🍕"
+
+julia> textwidth(s)
+10
+
+julia> ltrunc("foo", 3)
+"foo"
+```
+
+!!! compat "Julia 1.12"
+    This function was added in Julia 1.12.
+
+See also [`rtrunc`](@ref) and [`ctrunc`](@ref).
+"""
+function ltrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…")
+    if textwidth(str) <= w
+        return str
+    else
+        i, accwidth = lastindex(str), textwidth(replace_str)
+        while true
+            tw = textwidth(str[i])
+            accwidth + tw <= w || break # no need to check if we go out of bounds because of the first if branch
+            accwidth += tw
+            i = prevind(str, i)
+        end
+        return replace_str * str[nextind(str, i):lastindex(str)]
+    end
+end
+
+"""
+    ctrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…"; prefer_left::Bool = true)
+
+Truncate `str` to at most `w` characters (see [`textwidth`](@ref)), replacing the middle characters
+with `replace_str` if necessary. The default replacement string is "…". By default, the truncation
+prefers keeping chars on the left, but this can be changed by setting `prefer_left` to `false`.
+
+# Examples
+```jldoctest
+julia> s = ctrunc("🍕🍕 I love 🍕", 10)
+"🍕🍕 …e 🍕"
+
+julia> textwidth(s)
+10
+
+julia> ctrunc("foo", 3)
+"foo"
+```
+
+!!! compat "Julia 1.12"
+    This function was added in Julia 1.12.
+
+See also [`ltrunc`](@ref) and [`rtrunc`](@ref).
+"""
+function ctrunc(str::AbstractString, w::Int, replace_str::AbstractString = "…"; prefer_left::Bool = true)
+    if textwidth(str) <= w
+        return str
+    else
+        l, r, accwidth = firstindex(str), lastindex(str), textwidth(replace_str)
+        isleft = prefer_left
+        while true
+            tw = if isleft textwidth(str[l]) else textwidth(str[r]) end
+            (accwidth += tw) <= w || break
+            if isleft
+                l = nextind(str, l)
+            else
+                r = prevind(str, r)
+            end
+            isleft = !isleft
+        end
+        return str[firstindex(str):prevind(str, l)] * replace_str * str[nextind(str, r):lastindex(str)]
+    end
+end
+
 """
     eachsplit(str::AbstractString, dlm; limit::Integer=0, keepempty::Bool=true)
     eachsplit(str::AbstractString; limit::Integer=0, keepempty::Bool=false)

doc/src/base/strings.md

@@ -48,6 +48,9 @@ Base.:(==)(::AbstractString, ::AbstractString)
 Base.cmp(::AbstractString, ::AbstractString)
 Base.lpad
 Base.rpad
+Base.ltrunc
+Base.rtrunc
+Base.ctrunc
 Base.findfirst(::AbstractString, ::AbstractString)
 Base.findnext(::AbstractString, ::AbstractString, ::Integer)
 Base.findnext(::AbstractChar, ::AbstractString, ::Integer)

test/strings/util.jl

@@ -53,6 +53,36 @@ SubStr(s) = SubString("abc$(s)de", firstindex(s) + 3, lastindex(s) + 3)
     @test rpad("⟨k|H₁|k⟩", 12) |> textwidth == 12
 end
 
+@testset "string truncation (ltrunc and rtrunc)" begin
+    @test ltrunc("foo", 4) == "foo"
+    @test ltrunc("foo", 3) == "foo"
+    @test ltrunc("foo", 2) == "…o"
+    @test ltrunc("🍕🍕 I love 🍕", 10) == "…I love 🍕" # handle wide emojis
+    @test ltrunc("🍕🍕 I love 🍕", 10, "[…]") == "[…]love 🍕"
+    # when the replacement string is longer than the trunc
+    # trust that the user wants the replacement string rather than erroring
+    @test ltrunc("abc", 2, "xxxxxx") == "xxxxxx"
+
+    @test rtrunc("foo", 4) == "foo"
+    @test rtrunc("foo", 3) == "foo"
+    @test rtrunc("foo", 2) == "f…"
+    @test rtrunc("🍕🍕 I love 🍕", 10) == "🍕🍕 I lo…"
+    @test rtrunc("🍕🍕 I love 🍕", 10, "[…]") == "🍕🍕 I […]"
+    @test rtrunc("abc", 2, "xxxxxx") == "xxxxxx"
+
+    @test ctrunc("foo", 4) == "foo"
+    @test ctrunc("foo", 3) == "foo"
+    @test ctrunc("foo", 2) == "f…"
+    @test ctrunc("foo", 2; prefer_left=true) == "f…"
+    @test ctrunc("foo", 2; prefer_left=false) == "…o"
+    @test ctrunc("foobar", 6) == "foobar"
+    @test ctrunc("foobar", 5) == "fo…ar"
+    @test ctrunc("foobar", 4) == "fo…r"
+    @test ctrunc("🍕🍕 I love 🍕", 10) == "🍕🍕 …e 🍕"
+    @test ctrunc("🍕🍕 I love 🍕", 10, "[…]") == "🍕🍕[…] 🍕"
+    @test ctrunc("abc", 2, "xxxxxx") == "xxxxxx"
+end
+
 # string manipulation
 @testset "lstrip/rstrip/strip" begin
     @test strip("") == ""