document that unsafe_string accepts Cstring (#56907)

Document that `unsafe_string` allows its argument to be a `Cstring`.

There is also another method that accepts `Cwstring`, which transcodes
from a NUL-terminated `wchar_t` array (assumed to be either UTF-32 or
UTF-16 depending on the width of `wchar_t`). Should that be documented
in the same docstring or in a different docstring?

---------

Co-authored-by: Max Horn <[email protected]>
Co-authored-by: Viral B. Shah <[email protected]>

Author: 3 people

base/strings/cstring.jl

@@ -301,14 +301,27 @@ function transcode(::Type{UInt8}, src::AbstractVector{UInt16})
     return dst
 end
 
+"""
+    unsafe_string(p::Ptr{T}, [length::Integer]) where {T<:Union{UInt16,UInt32,Cwchar_t}}
+    unsafe_string(p::Cwstring)
+
+Transcode a string from the address of a C-style (NUL-terminated) string encoded as UTF-16
+(`T=UInt16`), UTF-32 (`T=UInt32`), or the system-dependent `wchar_t` (`T=Cwchar_t` or `Cwstring`),
+returning a `String` (UTF-8 encoding), similar to [`transcode`](@ref) but reading directly
+from a pointer.  (The pointer can be safely freed afterwards.) If `length` is specified
+(the length of the data in encoding units), the string does not have to be NUL-terminated.
+
+This function is labeled "unsafe" because it will crash if `p` is not
+a valid memory address to data of the requested length (or NUL-terminated data).
+"""
 function unsafe_string(p::Ptr{T}, length::Integer) where {T<:Union{UInt16,UInt32,Cwchar_t}}
     transcode(String, unsafe_wrap(Array, p, length; own=false))
 end
-function unsafe_string(cw::Cwstring)
-    p = convert(Ptr{Cwchar_t}, cw)
+function unsafe_string(p::Ptr{T}) where {T<:Union{UInt16,UInt32,Cwchar_t}}
     n = 1
     while unsafe_load(p, n) != 0
         n += 1
     end
     return unsafe_string(p, n - 1)
 end
+unsafe_string(cw::Cwstring) = unsafe_string(convert(Ptr{Cwchar_t}, cw))

base/strings/string.jl

@@ -109,6 +109,7 @@ takestring!(v::Vector{UInt8}) = String(v)
 
 """
     unsafe_string(p::Ptr{UInt8}, [length::Integer])
+    unsafe_string(p::Cstring)
 
 Copy a string from the address of a C-style (NUL-terminated) string encoded as UTF-8.
 (The pointer can be safely freed afterwards.) If `length` is specified