add rtruncate, ltruncate, ctruncate for truncating strings

[IanButterworth]

Co-authored with @tecosaur

Looking at the implementation of these functions in Profile (which are touched in #55335) uncovered issues and it seems to make sense to make and test the proper functions and add them to Base.

[oscardssmith]

Isn't this font and terminal emulator dependent? (e.g. 🏳️‍🌈 is 1 wide in a browser but in my terminal emulator, displaying as 🏳️🌈)

[IanButterworth]

I'm far from an expert on this, but isn't that lack of adherence to the standard by the terminal, not variability that should be handled?

[nsajko]

isn't that lack of adherence to the standard by the terminal

In any case, textwidth seems to follow the behavior in the terminal. So textwidth itself, and thus these proposed functions, are really specific to terminal, or at least fixed-width usage?

[oscardssmith]

I'm far from an expert on this, but isn't that lack of adherence to the standard by the terminal, not variability that should be handled?

no. Quoting https://www.unicode.org/emoji/charts/emoji-zwj-sequences.html:

The following are the recommended emoji zwj sequences, which use a U+200D ZERO WIDTH JOINER (ZWJ) to join the characters into a single glyph if available. When not available, the ZWJ characters are ignored and a fallback sequence of separate emoji is displayed. Thus an emoji zwj sequence should only be supported where the fallback sequence would also make sense to a viewer.

[IanButterworth]

These are adjacent functions to rpad/lpad and it was decided to make those textwidth-based, so isn't the point moot? #38256

[stevengj]

(It definitely depends on the terminal; see the classic issue #3721 — but alternatives like length are even worse.)

[stevengj]

Do we really need all three of these in the stdlib? ctrunc seems especially esoteric.

[tecosaur]

I see two arguments for this functionality finding its way into Base.

• With respect to fitting a string to a certain width, it's the other half of lpad/rpad
• A naive implementation of truncation is prone to bugs, even appearing in the stdlib (see: the bugs I picked up in Profile that Ian referenced)

With regards to why ctrunc should be included at all, I'd consider centered truncation to be similarly common to ltrunc / rtrunc. For example, it's what string's 3-arg show does: "abc..." ⋯ 326 bytes ⋯ "...xyz".

While cpad is easy to implement based on lpad and rpad:

cpad(str, w) = lpad(rpad(str, w ÷ 2), w)

and this was given as the reason why cpad was depreciated in 2017 (#23187).

Unlike cpad, ctrunc is not trivially formed from a combination of ltrunc and rtrunc, and shares all of the same risks with naive implementations. On this basis, I see it as a worthwhile inclusion.

[tecosaur]

Oh also, I've just discovered a generalised truncation function I implemented in About.jl 😆 (that would have been helpful while Ian and I repeated the work in our DMs on Slack)

function struncate(str::AbstractString, maxwidth::Int, joiner::AbstractString = "…", mode::Symbol = :center)
    textwidth(str) <= maxwidth && return str
    left, right = firstindex(str), lastindex(str)
    width = textwidth(joiner)
    while true
        if mode ∈ (:right, :center)
            (width += textwidth(str[left])) <= maxwidth || break
            left = nextind(str, left)
        end
        if mode ∈ (:left, :center) && width < maxwidth
            (width += textwidth(str[right])) <= maxwidth || break
            right = prevind(str, right)
        end
    end
    str[begin:prevind(str, left)] * joiner * str[nextind(str, right):end]
end

[IanButterworth]

A single function like that seems tidier, but is it too atypical to put key functionality on a kwarg? Otherwise we might have had pad(.., mode = :right).

[stevengj]

A single function like that seems tidier, but is it too atypical to put key functionality on a kwarg?

We could always use a single-function implementation internally (maybe with a Val argument?) but still expose ltrunc etc as the API.

[IanButterworth]

Indeed. Just updated to the single internal implementation

[stevengj]

Suggested change

	function struncate(str::AbstractString, maxwidth::Int, replacement::Union{AbstractString,Char}, mode::Symbol = :center, prefer_left::Bool = true)
	function _struncate(str::AbstractString, maxwidth::Int, replacement::Union{AbstractString,Char}, ::Val{mode}, prefer_left::Bool = true) where {mode}

use an underscore to indicate that this is an internal method, and use Val so that the mode checks can be elided by the compiler?

(Especially since the mode checks occur in the inner loop.)

[IanButterworth]

Now that we have public we don't need to mark internals by name convention?

Val sounds good. I didn't appreciate why before.

[KristofferC]

Why Val and not e.g. a Symbol keyword arg?

[nsajko]

Now that we have public we don't need to mark internals by name convention?

because the REPL autocompletes and even gives hints for private names: #51327

[IanButterworth]

That change just needs implementing, right? That can happen in time for 1.12 along with this code.

[KristofferC]

I want to make sure that the mode == ... conditionals are evaluated at compile time.

This should be backed up by some benchmark in my opinion. A single pointer equality check seems to me insignificant from the work of the function.

In principle this could also happen with enum or Symbol arguments if we ensure that the function is inlined.

I don't think constant propagation requires inlining. And there is also @constprop :aggressive.

Val is never really a good idea to make an API upon (any longer).

[stevengj]

This should be backed up by some benchmark in my opinion. A single pointer equality check seems to me insignificant from the work of the function.

I tried this with

s = randstring(10^5)
@btime struncate($s, 100, '…', :center);

and I got about an 8% speedup by hard-coding the mode checks. (This is after doing the total_width optimization noted below — otherwise, it spends all its time on the textwidth(str) check.)

[stevengj]

I get another 60% speedup by replacing textwidth(::Char) with an optimized version that has a fast path for ASCII characters. We might want to do this in a separate PR:

const textwidth_ascii = Cint[textwidth(Char(i)) for i = 0:127]
function textwidth2(c::AbstractChar)
    b = bswap(reinterpret(UInt32, c))
    b < 0x80 && @inbounds return Int(textwidth_ascii[b+1]) # ASCII fast path
    Base.ismalformed(c) && return 1
    Int(ccall(:utf8proc_charwidth, Cint, (UInt32,), c))
end

Update: this optimization is #55398

[IanButterworth]

Using Val I do see reduction from

julia> @b ctrunc("dsadsafsadsadsafdsad", 10)
150.062 ns (4 allocs: 112 bytes)

to

136.986 ns (4 allocs: 112 bytes)

That's without #55398

[IanButterworth]

After #55398 this is now

julia> @b ctruncate("dsadsafsadsadsafdsad", 10)
91.665 ns (4 allocs: 112 bytes)

[nsajko]

Could the exported functions get more descriptive names? E.g., truncate_from_left. Or even truncate_string_from_left.

[IanButterworth]

@nsajko these are supposed to be the counterparts to to rpad/lpad. I think the names make sense with that context?

[nsajko]

IMO, given that using Base is the default for modules, the less names are exported from Base, cluttering non-bare modules, the better. Especially if the names are very short or not used especially often. Not sure how prevalent this opinion is, but there it is.

So, IMO, in order of preference:

1. descriptive public names
2. descriptive export-ed names or shorthand public names
3. shorthand export-ed names.

FWIW.

[IanButterworth]

Ok. Fair.

truncate_right? Allows extending methods for non string types.

[IanButterworth]

@nsajko Regarding renaming. I'm wavering. We have rpad rsplit rstrip, lpad lstrip.
Moving to truncate_right etc. feels a bit awkward for something so closely tied.

What about rtruncate?

[nsajko]

Yeah, rtruncate is much better, I vote for rtruncate.

[tecosaur]

I do generally like unabbreviated names (nextind continues to annoy me).

However... I do wonder if there's a danger in ltruncate (& co.) being very similar in name to truncate yet doing something completely different?

[tecosaur]

Not to open a can of worms, but it occurs to me that in cases like:

julia> struncate("🍕🍕🍕🍕🍕🍕xxxxxxxxxxx", 9, "…")
"🍕🍕🍕…xx"

The "centre" truncate call has 6 cells of 🍕 on the left, and 2 of x, which isn't very centred 😬.

(Sorry Ian 😅)

[IanButterworth]

Just pushed a fix

julia> @time ctruncate("🍕🍕🍕🍕🍕🍕xxxxxxxxxxx", 9)
  0.000014 seconds (4 allocations: 112 bytes)
"🍕🍕…xxxx"