Implement takestring!

This function creates a string from an IOBuffer or a Vector, emptying the input
object and reusing the memory where possible.

Author: jakobnissen

NEWS.md

@@ -50,6 +50,7 @@ New library features
 * `fieldoffset` now also accepts the field name as a symbol as `fieldtype` already did ([#58100]).
 * `sort(keys(::Dict))` and `sort(values(::Dict))` now automatically collect, they previously threw ([#56978]).
 * `Base.AbstractOneTo` is added as a supertype of one-based axes, with `Base.OneTo` as its subtype ([#56902]).
+* `takestring!(::IOBuffer)` removes the content from the buffer, returning the content as a `String`.
 
 Standard library changes
 ------------------------

base/exports.jl

@@ -682,6 +682,7 @@ export
     split,
     string,
     strip,
+    takestring!,
     textwidth,
     thisind,
     titlecase,

base/iobuffer.jl

@@ -783,6 +783,80 @@ function take!(io::IOBuffer)
     return data
 end
 
+"Internal method. This method can be faster than takestring!, because it does not
+reset the buffer to a usable state, and it does not check for io.reinit.
+Using the buffer after calling unsafe_takestring! may cause undefined behaviour.
+This function is meant to be used when the buffer is only used as a temporary
+string builder, which is discarded after the string is built."
+function unsafe_takestring!(io::IOBuffer)
+    used_span = get_used_span(io)
+    nbytes = length(used_span)
+    from = first(used_span)
+    isempty(used_span) && return ""
+    # The C function can only copy from the start of the memory.
+    # Fortunately, in most cases, the offset will be zero.
+    return if isone(from)
+        ccall(:jl_genericmemory_to_string, Ref{String}, (Any, Int), io.data, nbytes)
+    else
+        mem = StringMemory(nbytes % UInt)
+        unsafe_copyto!(mem, 1, io.data, from, nbytes)
+        unsafe_takestring(mem)
+    end
+end
+
+"""
+    takestring!(io::IOBuffer) -> String
+
+Return the content of `io` as a `String`, resetting the buffer to its initial
+state.
+This is preferred over calling `String(take!(io))` to create a string from
+an `IOBuffer`.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer();
+
+julia> write(io, [0x61, 0x62, 0x63]);
+
+julia> s = takestring!(io)
+"abc"
+
+julia> isempty(take!(io)) # io is now empty
+true
+```
+
+!!! compat "Julia 1.13"
+    This function requires at least Julia 1.13.
+"""
+function takestring!(io::IOBuffer)
+    # If the buffer has been used up and needs to be replaced, there are no bytes, and
+    # we can return an empty string without interacting with the buffer at all.
+    io.reinit && return ""
+
+    # If the iobuffer is writable, taking will remove the buffer from `io`.
+    # So, we reset the iobuffer, and directly unsafe takestring.
+    return if io.writable
+        s = unsafe_takestring!(io)
+        io.reinit = true
+        io.mark = -1
+        io.ptr = 1
+        io.size = 0
+        io.offset_or_compacted = 0
+        s
+    else
+        # If the buffer is not writable, taking will NOT remove the buffer,
+        # so if we just converted the buffer to a string, garbage collecting
+        # the string would free the memory underneath the iobuffer
+        used_span = get_used_span(io)
+        mem = StringMemory(length(used_span))
+        unsafe_copyto!(mem, 1, io.data, first(used_span), length(used_span))
+        unsafe_takestring(mem)
+    end
+end
+
+# Fallback methods
+takestring!(io::GenericIOBuffer) = String(take!(io))
+
 """
     _unsafe_take!(io::IOBuffer)
 

base/strings/string.jl

@@ -62,8 +62,8 @@ In other cases, `Vector{UInt8}` data may be copied, but `v` is truncated anyway
 to guarantee consistent behavior.
 """
 String(v::AbstractVector{UInt8}) = unsafe_takestring(copyto!(StringMemory(length(v)), v))
+
 function String(v::Vector{UInt8})
-    #return ccall(:jl_array_to_string, Ref{String}, (Any,), v)
     len = length(v)
     len == 0 && return ""
     ref = v.ref
@@ -84,6 +84,24 @@ function unsafe_takestring(m::Memory{UInt8})
     isempty(m) ? "" : ccall(:jl_genericmemory_to_string, Ref{String}, (Any, Int), m, length(m))
 end
 
+"""
+    takestring!(x) -> String
+
+Create a string from the content of `x`, emptying `x`.
+
+# Examples
+```jldoctest
+julia> v = [0x61, 0x62, 0x63];
+
+julia> s = takestring!(v)
+"abc"
+
+julia> isempty(v)
+true
+```
+"""
+takestring!(v::Vector{UInt8}) = String(v)
+
 """
     unsafe_string(p::Ptr{UInt8}, [length::Integer])
 

doc/src/base/strings.md

@@ -29,6 +29,7 @@ Base.SubstitutionString
 Base.@s_str
 Base.@raw_str
 Base.@b_str
+Base.takestring!
 Base.Docs.@html_str
 Base.Docs.@text_str
 Base.isvalid(::Any)

src/genericmemory.c

@@ -197,7 +197,6 @@ JL_DLLEXPORT jl_value_t *jl_genericmemory_to_string(jl_genericmemory_t *m, size_
     }
     int how = jl_genericmemory_how(m);
     size_t mlength = m->length;
-    m->length = 0;
     if (how != 0) {
         jl_value_t *o = jl_genericmemory_data_owner_field(m);
         jl_genericmemory_data_owner_field(m) = NULL;

test/iobuffer.jl

@@ -321,6 +321,36 @@ end
     @test_throws ArgumentError seek(io, 0)
 end
 
+@testset "takestring!" begin
+    buf = IOBuffer()
+    write(buf, "abcø")
+    s = takestring!(buf)
+    @test isempty(takestring!(buf))
+    @test s == "abcø"
+    write(buf, "xyz")
+    @test takestring!(buf) == "xyz"
+    buf = IOBuffer()
+
+    # Test with a nonzero offset in the buffer
+    v = rand(UInt8, 8)
+    for i in 1:8
+        pushfirst!(v, rand(UInt8))
+    end
+    buf = IOBuffer(v)
+    s = String(copy(v))
+    @test takestring!(buf) == s
+
+    # Test with a non-writable IOBuffer
+    buf = IOBuffer(b"abcdef")
+    read(buf, UInt8)
+    @test takestring!(buf) == "abcdef"
+
+    buf = new_unseekable_buffer()
+    write(buf, "abcde")
+    read(buf, UInt16)
+    @test takestring!(buf) == "cde"
+end
+
 @testset "Read/write readonly IOBuffer" begin
     io = IOBuffer("hamster\nguinea pig\nturtle")
     @test position(io) == 0

test/strings/basic.jl

@@ -49,6 +49,24 @@ using Random
     end
 end
 
+@testset "takestring!" begin
+    v = [0x61, 0x62, 0x63]
+    old_mem = v.ref.mem
+    @test takestring!(v) == "abc"
+    @test isempty(v)
+    @test v.ref.mem !== old_mem # memory is changed
+    for v in [
+        UInt8[],
+        [0x01, 0x02, 0x03],
+        collect(codeunits("æøå"))
+    ]
+        cp = copy(v)
+        s = takestring!(v)
+        @test isempty(v)
+        @test codeunits(s) == cp
+    end
+end
+
 @testset "{starts,ends}with" begin
     @test startswith("abcd", 'a')
     @test startswith('a')("abcd")