bitfield: minor documentation and function tweaks (#10549)

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.

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
 		}

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
 		}
 	}