From: Robin Lee <cheeselee@fedoraproject.org>
Date: Thu, 13 Aug 2020 06:42:52 +0000 (+0800)
Subject: common: document the current semantics of bl::append(std::istream)
X-Git-Tag: v16.1.0~1419^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F36623%2Fhead;p=ceph.git

common: document the current semantics of bl::append(std::istream)

bl::append(std::istream) comes with a surprise implementation. People may think
it would just slurp the indentical binary data from the stream. Document the
trap to let people don't mis-use it.

Signed-off-by: Robin Lee <cheeselee@fedoraproject.org>
---

diff --git a/src/include/buffer.h b/src/include/buffer.h
index 725dd399095f..4df15cd4aae6 100644
--- a/src/include/buffer.h
+++ b/src/include/buffer.h
@@ -1132,6 +1132,11 @@ struct error_code;
     void append(ptr&& bp);
     void append(const ptr& bp, unsigned off, unsigned len);
     void append(const list& bl);
+    /// append each non-empty line from the stream and add '\n',
+    /// so a '\n' will be added even the stream does not end with EOL.
+    ///
+    /// For example, if the stream contains "ABC\n\nDEF", "ABC\nDEF\n" is
+    /// actually appended.
     void append(std::istream& in);
     contiguous_filler append_hole(unsigned len);
     void append_zero(unsigned len);