From 8e53a911c79d4bde481d8bdfaf49a15d7969bfad Mon Sep 17 00:00:00 2001
From: JamesWrigley <james@puiterwijk.org>
Date: Sat, 20 Jul 2024 12:27:49 +0200
Subject: [PATCH] Deprecate `Base.convert(IOStream, ::Message)`

This had two problems:
- It actually returned an `IOBuffer`.
- It made a (potentially) unnecessary copy of the `Message`.
---
 docs/src/_changelog.md |  4 ++++
 src/message.jl         | 27 +++++++++++++++++++++++++--
 test/runtests.jl       |  4 ++--
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/src/_changelog.md b/docs/src/_changelog.md
index 3099c27..3ec2e2c 100644
--- a/docs/src/_changelog.md
+++ b/docs/src/_changelog.md
@@ -14,6 +14,10 @@ Changelog](https://keepachangelog.com).
   1.11 ([#244]).
 - Full [Bindings](@ref) to libzmq ([#232]).
 
+### Deprecated
+- The `Base.convert(IOStream, ::Message)` method has been deprecated due to
+  buggy behaviour, use `IOBuffer(msg)` instead ([#247]).
+
 ### Fixed
 - Fixed [`isfreed()`](@ref), which would previously return the wrong values
   ([#245]).
diff --git a/src/message.jl b/src/message.jl
index 17c5fb7..386399b 100644
--- a/src/message.jl
+++ b/src/message.jl
@@ -23,9 +23,31 @@ function gc_free_fn(data::Ptr{Cvoid}, hint::Ptr{Cvoid})
 end
 
 """
-High-level Message object for sending/receiving ZMQ messages in shared buffers.
+    mutable struct Message <: AbstractArray{UInt8, 1}
+
+High-level `Message` object for sending/receiving ZMQ messages in shared
+buffers. As an `AbstractArray`, it supports common (non-resizeable) array
+behaviour.
+
+# Examples
+```jldoctest
+julia> using ZMQ
+
+julia> m = Message("foo");
+
+julia> Char(m[1])            # Array indexing
+'f': ASCII/Unicode U+0066 (category Ll: Letter, lowercase)
+
+julia> m[end] = Int('g');    # Array assignment
+
+julia> unsafe_string(m)      # Conversion to string (only do this if you know the message is a string)
+"fog"
+
+julia> IOBuffer(m)           # Create a zero-copy IOBuffer
+IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=3, maxsize=Inf, ptr=1, mark=-1)
+```
 """
-mutable struct Message <: AbstractArray{UInt8,1}
+mutable struct Message <: AbstractArray{UInt8, 1}
     # Matching the declaration in the header: char _[64];
     w_padding::_Message
     handle::Ptr{Cvoid} # index into gc_protect, if any
@@ -164,6 +186,7 @@ Base.strides(::Message) = (1,)
 # Build an IOStream from a message
 # Copies the data
 function Base.convert(::Type{IOStream}, zmsg::Message)
+    Base.depwarn("convert(IOStream, ::Message) is deprecated, use `IOBuffer(zmsg)` instead to make a zero-copy IOBuffer from a Message.", :convert)
     s = IOBuffer()
     write(s, zmsg)
     return s
diff --git a/test/runtests.jl b/test/runtests.jl
index e50ba32..1986f37 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -121,8 +121,7 @@ end
 
     ZMQ.send(s2, Message("another test request"))
     msg = ZMQ.recv(s1)
-    o=convert(IOStream, msg)
-    seek(o, 0)
+    o = IOBuffer(msg)
     @test String(take!(o)) == "another test request"
     ZMQ.send(s1) do io
         print(io, "buffer ")
@@ -218,6 +217,7 @@ end
     @test !Bool(m.more)
     @test_throws ErrorException m.more = true
     @test ZMQ.isfreed(m)
+    @test_logs (:warn, r"convert(.+) is deprecated") convert(IOStream, m)
 end
 
 @testset "ZMQ resource management" begin