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

@@ -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]).

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

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