String(v): some rewording of NEWS and docs

Author: StefanKarpinski

NEWS.md

@@ -434,8 +434,10 @@ Library improvements
   * The function `thisind(s::AbstractString, i::Integer)` returns the largest valid index
     less or equal than `i` in the string `s` or `0` if no such index exists ([#24414]).
 
-  * `String(array)` now accepts an arbitrary `AbstractVector{UInt8}`, and resizes
-    `Vector{UInt8}` inputs to a zero length to prevent incorrect modification ([#26093]).
+  * `String(array)` now accepts an arbitrary `AbstractVector{UInt8}` and "steals" the
+    memory buffer of mutable arrays, leaving the byte vector with an empty buffer which
+    is guaranteed not to be shared with the `String` object; if the byte vector is
+    immutable, it simply shares memory with the string and is not truncated ([#26093]).
 
   * `Irrational` is now a subtype of `AbstractIrrational` ([#24245]).
 

base/strings/string.jl

@@ -18,17 +18,18 @@ const ByteArray = Union{Vector{UInt8},Vector{Int8}}
 """
     String(v::AbstractVector{UInt8})
 
-Create a new `String` from a vector `v` of bytes containing
-UTF-8 encoded characters.
-
-When possible, the data in `v` will be used directly rather than making
-a copy. This is the case for `Vector{UInt8}` arrays returned by [`take!`](@ref)
-on a writable [`IOBuffer`](@ref) or by [`read(io, nb)`](@ref). Else, a copy is made.
-In all cases, one should assume that the function takes "ownership" of the array
-and that its contents should not be subsequently modified. Implementations may choose
-to resize `v` to a zero length to enforce this (which is the case when `v` is a `Vector`).
-
-If you need to subsequently modify `v`, use `String(copy(v))` instead.
+Create a new `String` from a byte vector `v` containing UTF-8 encoded
+characters. If `v` is a mutable vector, it will be truncated and any future
+modification of `v` cannot affect the contents of the resulting `String` object.
+If `v` is an immutable vector it will not be truncated (it cannot be since it is
+immutable). To avoid truncation of mutable `v` use `String(copy(v))`.
+
+When possible, the data in `v` will be used directly when creating the `String`
+object without making a copy. This is guaranteed to be the case for byte vectors
+returned by [`take!`](@ref) on a writable [`IOBuffer`](@ref) and by calls to
+[`read(io, nb)`](@ref). This allows zero-copy conversion of I/O data to strings.
+In other cases mutable vector may be copied, but they are still truncated in
+either case to guarantee consistent behavior.
 """
 String(v::AbstractVector{UInt8}) = String(copyto!(StringVector(length(v)), v))
 String(v::Vector{UInt8}) = ccall(:jl_array_to_string, Ref{String}, (Any,), v)