From 7e78d86f98bc571f7712a86620fe0ba2c79dedc6 Mon Sep 17 00:00:00 2001
From: Daniel Lemire <daniel@lemire.me>
Date: Tue, 27 Jun 2023 11:12:18 -0400
Subject: [PATCH] better documentation

---
 README.md | 15 +++++++++++++++
 bitset.go | 14 ++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 4b82fd1..848234e 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,21 @@ You can later deserialize the result as follows:
 The `ReadFrom` function attempts to read the data into the existing
 BitSet instance, to minimize memory allocations.
 
+
+*Performance tip*: 
+When reading and writing to a file or a network connection, you may get better performance by 
+wrapping your streams with `bufio` instances.
+
+E.g., 
+```Go
+	f, err := os.Create("myfile")
+	w := bufio.NewWriter(f)
+```
+```Go
+	f, err := os.Open("myfile")
+	r := bufio.NewReader(f)
+```
+
 ## Memory Usage
 
 The memory usage of a bitset using `N` bits is at least `N/8` bytes. The number of bits in a bitset is at least as large as one plus the greatest bit index you have accessed. Thus it is possible to run out of memory while using a bitset. If you have lots of bits, you might prefer compressed bitsets, like the [Roaring bitmaps](http://roaringbitmap.org) and its [Go implementation](https://github.com/RoaringBitmap/roaring).
diff --git a/bitset.go b/bitset.go
index 237285b..4eb1733 100644
--- a/bitset.go
+++ b/bitset.go
@@ -912,6 +912,13 @@ func (b *BitSet) BinaryStorageSize() int {
 // 1. uint64 length
 // 2. []uint64 set
 // Upon success, the number of bytes written is returned.
+//
+// Performance: if this function is used to write to a disk or network
+// connection, it might be beneficial to wrap the stream in a bufio.Writer.
+// E.g.,
+//
+//	      f, err := os.Create("myfile")
+//		       w := bufio.NewWriter(f)
 func (b *BitSet) WriteTo(stream io.Writer) (int64, error) {
 	buf := make([]byte, wordBytes)
 	length := uint64(b.length)
@@ -943,6 +950,13 @@ func (b *BitSet) WriteTo(stream io.Writer) (int64, error) {
 // it is extended. In case of error, the BitSet is either
 // left unchanged or made empty if the error occurs too late
 // to preserve the content.
+//
+// Performance: if this function is used to read from a disk or network
+// connection, it might be beneficial to wrap the stream in a bufio.Reader.
+// E.g.,
+//
+//	f, err := os.Open("myfile")
+//	r := bufio.NewReader(f)
 func (b *BitSet) ReadFrom(stream io.Reader) (int64, error) {
 	buf := make([]byte, wordBytes)