From c0b53048f5a4a6a181d275c47e0862a70e015df4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi?= <33205215+remimimimi@users.noreply.github.com>
Date: Thu, 24 Jun 2021 07:27:04 +0300
Subject: [PATCH] bitfield: minor documentation and function tweaks (#10549)

---
 vlib/bitfield/README.md       | 11 +++++++++++
 vlib/bitfield/bitfield.v      | 16 +++++++++++++++-
 vlib/bitfield/bitfield_test.v |  4 ++--
 3 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 vlib/bitfield/README.md

diff --git a/vlib/bitfield/README.md b/vlib/bitfield/README.md
new file mode 100644
index 0000000000..8b82c4cc8a
--- /dev/null
+++ b/vlib/bitfield/README.md
@@ -0,0 +1,11 @@
+# Quickstart
+
+`bitfield` is a module for
+manipulating arrays of bits, i.e. series of zeroes and ones spread across an
+array of storage units (unsigned 32-bit integers).
+
+## BitField structure
+
+Bit arrays are stored in data structures called 'BitField'. The structure is
+'opaque', i.e. its internals are not available to the end user. This module
+provides API (functions and methods) for accessing and modifying bit arrays.
diff --git a/vlib/bitfield/bitfield.v b/vlib/bitfield/bitfield.v
index c666daa014..9ed4e2bdd5 100644
--- a/vlib/bitfield/bitfield.v
+++ b/vlib/bitfield/bitfield.v
@@ -340,6 +340,8 @@ pub fn (instance BitField) clone() BitField {
 
 // cmp compares two bit arrays bit by bit and returns 'true' if they are
 // identical by length and contents and 'false' otherwise.
+[deprecated: 'use a == b instead']
+[deprecated_after: '2021-06-29']
 pub fn (instance BitField) cmp(input BitField) bool {
 	if instance.size != input.size {
 		return false
@@ -352,6 +354,18 @@ pub fn (instance BitField) cmp(input BitField) bool {
 	return true
 }
 
+pub fn (a BitField) == (b BitField) bool {
+	if a.size != b.size {
+		return false
+	}
+	for i in 0 .. zbitnslots(a.size) {
+		if a.field[i] != b.field[i] {
+			return false
+		}
+	}
+	return true
+}
+
 // pop_count returns the number of set bits (ones) in the array.
 pub fn (instance BitField) pop_count() int {
 	size := instance.size
@@ -391,7 +405,7 @@ pub fn (haystack BitField) pos(needle BitField) int {
 	}
 	for i := 0; i <= diff; i++ {
 		needle_candidate := haystack.slice(i, needle_size + i)
-		if needle_candidate.cmp(needle) {
+		if needle_candidate == needle {
 			// needle matches a sub-array of haystack; return starting position of the sub-array
 			return i
 		}
diff --git a/vlib/bitfield/bitfield_test.v b/vlib/bitfield/bitfield_test.v
index 0506264aa4..ae61d386be 100644
--- a/vlib/bitfield/bitfield_test.v
+++ b/vlib/bitfield/bitfield_test.v
@@ -68,7 +68,7 @@ fn test_clone_cmp() {
 	}
 	output := input.clone()
 	assert output.get_size() == len
-	assert input.cmp(output) == true
+	assert input == output
 }
 
 fn test_slice_join() {
@@ -86,7 +86,7 @@ fn test_slice_join() {
 		chunk2 := input.slice(point, input.get_size())
 		// concatenate them back into one and compare to the original
 		output := bitfield.join(chunk1, chunk2)
-		if !input.cmp(output) {
+		if input != output {
 			result = 0
 		}
 	}