From 514766cceca3e50e7860610f9871175fe7d40799 Mon Sep 17 00:00:00 2001 From: Frank Rehberger Date: Tue, 3 Oct 2017 22:13:49 +0200 Subject: [PATCH] Document that UdpSocket::recv and recv_from do not read from the buffer (#657) --- src/udp.rs | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/udp.rs b/src/udp.rs index e43bc0b9e..a71bd2191 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -80,8 +80,17 @@ impl UdpSocket { self.sys.send_to(buf, target).map_non_block() } - /// Receives data from the socket. On success, returns the number of bytes - /// read and the address from whence the data came. + /// Receives data from the socket and stores data in the supplied buffer `buf`. On success, + /// returns the number of bytes read and the address from whence the data came. + /// + /// The function must be called with valid byte array `buf` of sufficient size to + /// hold the message bytes. If a message is too long to fit in the supplied buffer, + /// excess bytes may be discarded. + /// + /// The function does not read from `buf`, but is overwriting previous content of `buf`. + /// + /// Assuming the function has read `n` bytes, slicing `&buf[..n]` provides + /// efficient access with iterators and boundary checks. pub fn recv_from(&self, buf: &mut [u8]) -> io::Result> { self.sys.recv_from(buf).map_non_block() @@ -94,8 +103,17 @@ impl UdpSocket { self.sys.send(buf).map_non_block() } - /// Receives data from the socket previously bound with connect(). On success, returns - /// the number of bytes read and the address from whence the data came. + /// Receives data from the socket previously bound with connect() and stores data in + /// the supplied buffer `buf`. On success, returns the number of bytes read. + /// + /// The function must be called with valid byte array `buf` of sufficient size to + /// hold the message bytes. If a message is too long to fit in the supplied buffer, + /// excess bytes may be discarded. + /// + /// The function does not read from `buf`, but is overwriting previous content of `buf`. + /// + /// Assuming the function has read `n` bytes, slicing `&buf[..n]` provides + /// efficient access with iterators and boundary checks. pub fn recv(&self, buf: &mut [u8]) -> io::Result> { self.sys.recv(buf).map_non_block()