add bitmap

Makefile

@@ -9,4 +9,4 @@ test: # 進行測試
 fmt: # 格式優化
 	$(GOFMT) -w $(GOFILES)
 	goimports -w  ./
-
+	golangci-lint run

go.mod

@@ -1,11 +1,3 @@
 module code.30cm.net/digimon/library-go
 
 go 1.22.3
-
-require github.com/stretchr/testify v1.9.0
-
-require (
-	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
-)

go.work

@@ -7,4 +7,5 @@ use (
 	./errs
 	.
 	./utils/invited_code
+	./utils/bitmap
 )

utils/bitmap/bitmap.go

@@ -0,0 +1,152 @@
+package usecase
+
+// Bitmap 基礎結構
+// Bitmap 是一個位圖結構，使用 byte slice 來表示大量的位（bit）。
+// 每個 byte 由 8 個位組成，因此可以高效地管理大量的開關狀態（true/false）。
+// Bitmap 的優點在於它能節省空間，尤其是在需要大量布爾值的場合。
+// 缺點是，如果需要動態擴充 Bitmap 的大小，會導致效率下降，因為需要重新分配和移動內存。
+// 因此，最好在初始化時就規劃好所需的位數大小，避免在之後頻繁擴充。
+
+type Bitmap []byte
+
+// MakeBitmapWithBitSize 通過指定的 bit 數創建一個新的 Bitmap。
+// 參數 nBits 表示所需的位（bit）數。
+// 如果指定的位數少於 64，則默認將 Bitmap 初始化為 64 位（這是最低的限制）。
+// 此外，位數（nBits）會被自動調整為 8 的倍數，以適配 byte 的長度（每 8 位為一個 byte）。
+// 返回值是一個 Bitmap（byte slice），其大小根據位數確定。
+func MakeBitmapWithBitSize(nBits int) Bitmap {
+	// 如果指定的位數少於 64，則設置為 64 位（8 個 byte）
+	if nBits < 64 {
+		nBits = 64
+	}
+	// 計算需要的 byte 數，確保每 8 位為一個 byte，並調整 nBits 以達到 8 的倍數
+	return MustBitMap((nBits + 7) / 8)
+}
+
+// MustBitMap 根據指定的 byte 數創建一個 Bitmap（byte slice）。
+// 參數 nBytes 表示所需的 byte 數。
+// 返回值是一個長度為 nBytes 的 Bitmap。
+func MustBitMap(nBytes int) Bitmap {
+	// 使用 make 函數創建一個 byte slice，大小為 nBytes。
+	return make([]byte, nBytes)
+}
+
+// SetTrue 設置指定位置的 bit 為 true（1）。
+// 參數 bitPos 是需要設置的位的位置（以 0 為基準的位索引）。
+// 這個操作會找到該 bit 所在的 byte，然後通過位運算將該位置的 bit 設置為 1。
+func (b Bitmap) SetTrue(bitPos uint32) {
+	// |= 是一種位運算的複合賦值運算符，表示將左邊的變數與右邊的值進行 位或運算（bitwise OR），並將結果賦值
+	b[bitPos/8] |= 1 << (bitPos % 8)
+}
+
+// SetFalse 設置指定位置的 bit 為 false（0）。
+// 參數 bitPos 是需要設置的位的位置（以 0 為基準的位索引）。
+// 這個操作會找到該 bit 所在的 byte，然後通過位運算將該位置的 bit 設置為 0。
+func (b Bitmap) SetFalse(bitPos uint32) {
+	// 取出對應 byte，使用位與和取反運算將對應的 bit 設置為 0
+	// 假設我們有以下情況：
+
+	// •	b[1]（即 b[bitPos/8]）是 10101111（十進制 175）。
+	// •	bitPos = 10，也就是我們想清除第 10 位的值。
+	//
+	// 操作步驟：
+	//
+	// 1.	bitPos/8 = 1：所以我們要修改 b[1] 這個 byte。
+	// 2.	bitPos % 8 = 2：表示我們要清除的位是這個 byte 中的第 3 位（從右數起第 3 位）。
+	// 3.	1 << (bitPos % 8) = 1 << 2 = 00000100：生成位掩碼 00000100。
+	// 4.	取反：^(1 << 2) = ^00000100 = 11111011，這樣的掩碼表示除了第 3 位，其他位都是 1。
+	// 5.	位與運算：10101111 & 11111011 = 10101011，結果將第 3 位清除，其餘位保持不變。即，b[1] 變成了 10101011（十進制 171）。
+	// &= 是一種 位與運算的複合賦值運算符，表示將左邊的變數與右邊的值進行 位與運算（bitwise AND），然後將結果賦值給左邊的變數。
+	b[bitPos/8] &= ^(1 << (bitPos % 8))
+}
+
+// IsTrue 檢查指定位置的 bit 是否為 true（1）。
+// 參數 bitPos 是要檢查的位的位置（以 0 為基準的位索引）。
+// 如果該 bit 是 1，則返回 true；否則返回 false。
+func (b Bitmap) IsTrue(bitPos uint32) bool {
+	/*
+			這一行程式碼 b[bitPos/8]&(1<<(bitPos%8)) != 0 是用來檢查 指定位（bit） 是否為 true（1），
+		    它的核心是位運算。讓我們逐步拆解並解釋這一行程式碼：
+
+			1. 背景知識：
+
+				•	位運算 是在二進制層面操作數字。每個 byte 有 8 個位（bit），所以位圖結構是以 byte 來表示位的集合。
+				•	b 是一個 Bitmap 結構，也就是 []byte，即 byte 的切片。
+				•	bitPos 是一個 uint32 類型的變數，表示我們想要檢查的位（bit）在整個位圖中的索引（位置）。
+			3. 完整流程舉例：
+			假設：
+				•	b = []byte{0b10101010, 0b01010101} （即二進制表示的兩個 byte，分別是 10101010 和 01010101）。
+				•	bitPos = 10（我們要檢查第 10 位是否為 1）。
+			操作順序：
+
+				1.	計算 bitPos/8 = 10/8 = 1，所以我們要檢查的是第二個 byte：0b01010101。
+				2.	計算 bitPos%8 = 10%8 = 2，所以我們要檢查的是該 byte 中的第 3 位（從右數起第 3 位）。
+				3.	位移：1 << 2 = 00000100。
+				4.	位與：0b01010101 & 0b00000100 = 0b00000100（因為該 byte 的第 3 位是 1，結果不等於 0）。
+				5.	判斷結果：結果不等於 0，因此第 10 位是 1（true）。
+
+			4. 總結：
+
+				•	b[bitPos/8]&(1<<(bitPos%8)) != 0 是一個經典的位操作，用來檢查位圖中某一個位是否為 1。
+				•	bitPos/8 找到對應的 byte，bitPos % 8 找到該位在這個 byte 中的具體位置。
+				•	最後的位與運算和比較用來確定該位的狀態是 true（1）還是 false（0）。
+	*/
+	return b[bitPos/8]&(1<<(bitPos%8)) != 0
+}
+
+// Reset 重置 Bitmap，使所有的 bit 都設置為 false（0）。
+// 這個操作會將整個 Bitmap 的所有 byte 都設置為 0，從而達到重置的效果。
+func (b Bitmap) Reset() {
+	// 迭代 Bitmap 中的每個 byte，並將其設置為 0
+	for i := range b {
+		b[i] = 0
+	}
+}
+
+// ByteSize 返回 Bitmap 的 byte 長度。
+// 這個函數返回 Bitmap 目前占用的 byte 數量，該值等於 Bitmap 的長度（slice 的長度）。
+func (b Bitmap) ByteSize() int {
+	return len(b)
+}
+
+// BitSize 返回 Bitmap 的位（bit）長度。
+// 這個函數通過將 byte 長度乘以 8 來計算 Bitmap 中的總位數。
+func (b Bitmap) BitSize() int {
+	// 每個 byte 包含 8 個 bit，因此將 byte 長度乘以 8
+	return len(b) * 8
+}
+
+// Resize 重新調整 Bitmap 的大小，將其擴展為指定的 bit 大小。
+// 原來的數據會被保留，新增加的部分位將初始化為 0。
+// 參數 newBitSize 是 Bitmap 需要擴展到的位大小。
+func (b Bitmap) Resize(newBitSize int) Bitmap {
+	newByteSize := (newBitSize + 7) / 8
+	if newByteSize <= len(b) {
+		// 如果新大小比原大小小或相等，不做任何操作，直接返回原 Bitmap
+		return b
+	}
+
+	// 創建新的 Bitmap
+	newBitmap := make([]byte, newByteSize)
+
+	// 將原 Bitmap 複製到新 Bitmap 中
+	copy(newBitmap, b)
+
+	// 返回新的 Bitmap
+	return newBitmap
+}
+
+// UpdateFrom 會將傳入的 Bitmap 的值更新到當前 Bitmap 中。
+// 如果傳入的 Bitmap 大於當前 Bitmap，則當前 Bitmap 會自動擴展並保存新 Bitmap 的數據。
+// 如果傳入的 Bitmap 小於當前 Bitmap，僅更新前面部分的數據。
+func (b Bitmap) UpdateFrom(newBitmap Bitmap) Bitmap {
+	// 如果 newBitmap 比當前 Bitmap 長，則擴展當前 Bitmap 的大小
+	if len(newBitmap) > len(b) {
+		// 創建一個擴展過的 Bitmap
+		expandedBitmap := make([]byte, len(newBitmap))
+		copy(expandedBitmap, b) // 將當前 Bitmap 的數據複製到擴展的 Bitmap 中
+		b = expandedBitmap      // 更新當前 Bitmap 的引用
+	}
+
+	return b
+}

utils/bitmap/bitmap_benchmark_test.go

@@ -0,0 +1,69 @@
+package usecase
+
+import "testing"
+
+// 基準測試 SetTrue 函數，測試在不同大小的 Bitmap 上設置位元為 true 的效能
+func BenchmarkBitmapSetTrue(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		bitmap.SetTrue(uint32(i % 1000000)) // 設置位元為 true
+	}
+}
+
+// 基準測試 SetFalse 函數，測試在不同大小的 Bitmap 上清除位元為 false 的效能
+func BenchmarkBitmapSetFalse(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		bitmap.SetFalse(uint32(i % 1000000)) // 清除位元為 false
+	}
+}
+
+// 基準測試 IsTrue 函數，測試在不同大小的 Bitmap 上檢查位元狀態的效能
+func BenchmarkBitmapIsTrue(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		_ = bitmap.IsTrue(uint32(i % 1000000)) // 檢查位元是否為 true
+	}
+}
+
+// 基準測試 Reset 函數，測試重置不同大小的 Bitmap 的效能
+func BenchmarkBitmapReset(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		bitmap.Reset() // 重置 Bitmap
+	}
+}
+
+// 基準測試 BitSize 函數，測試返回位圖的 bit 長度的效能
+func BenchmarkBitmapBitSize(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		_ = bitmap.BitSize() // 測試返回位圖的 bit 長度
+	}
+}
+
+// 基準測試 ByteSize 函數，測試返回位圖的 byte 長度的效能
+func BenchmarkBitmapByteSize(b *testing.B) {
+	// 以 10^6 位元作為基準測試的 Bitmap 大小
+	bitmap := MakeBitmapWithBitSize(1000000)
+	b.ResetTimer() // 重設計時器，排除初始化的時間
+
+	for i := 0; i < b.N; i++ {
+		_ = bitmap.ByteSize() // 測試返回位圖的 byte 長度
+	}
+}

utils/bitmap/bitmap_test.go

@@ -0,0 +1,137 @@
+package usecase
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBitmap_SetTrueAndIsTrue(t *testing.T) {
+	tests := []struct {
+		name     string
+		bitPos   uint32
+		expected bool
+	}{
+		{"Set bit 0 to true", 0, true},
+		{"Set bit 1 to true", 1, true},
+		{"Set bit 63 to true", 63, true},
+		{"Set bit 64 to true", 64, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			bitmap := MakeBitmapWithBitSize(128) // 初始化一個 128 位的 Bitmap
+			bitmap.SetTrue(tt.bitPos)
+			result := bitmap.IsTrue(tt.bitPos)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestBitmap_SetFalse(t *testing.T) {
+	tests := []struct {
+		name     string
+		bitPos   uint32
+		expected bool
+	}{
+		{"Set bit 0 to false", 0, false},
+		{"Set bit 1 to false", 1, false},
+		{"Set bit 63 to false", 63, false},
+		{"Set bit 64 to false", 64, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			bitmap := MakeBitmapWithBitSize(128) // 初始化一個 128 位的 Bitmap
+			bitmap.SetTrue(tt.bitPos)            // 先設置該 bit 為 true
+			bitmap.SetFalse(tt.bitPos)           // 然後設置該 bit 為 false
+			result := bitmap.IsTrue(tt.bitPos)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestBitmap_Reset(t *testing.T) {
+	bitmap := MakeBitmapWithBitSize(128) // 初始化一個 128 位的 Bitmap
+	bitmap.SetTrue(0)
+	bitmap.SetTrue(64)
+
+	// 確認 bit 0 和 bit 64 是 true
+	assert.True(t, bitmap.IsTrue(0))
+	assert.True(t, bitmap.IsTrue(64))
+
+	bitmap.Reset() // 重置位圖
+
+	// 確認所有的位都已經重置為 false
+	assert.False(t, bitmap.IsTrue(0))
+	assert.False(t, bitmap.IsTrue(64))
+}
+
+func TestBitmap_ByteSize(t *testing.T) {
+	bitmap := MakeBitmapWithBitSize(64)   // 初始化一個 64 位的 Bitmap
+	assert.Equal(t, 8, bitmap.ByteSize()) // 64 位應該佔用 8 個 byte
+}
+
+func TestBitmap_BitSize(t *testing.T) {
+	bitmap := MakeBitmapWithBitSize(128)   // 初始化一個 128 位的 Bitmap
+	assert.Equal(t, 128, bitmap.BitSize()) // 128 位應該有 128 個 bit
+}
+
+func TestBitmap_Resize(t *testing.T) {
+	tests := []struct {
+		name        string
+		initialSize int
+		newBitSize  int
+		expectedLen int
+	}{
+		{"Resize to larger size", 64, 128, 16},
+		{"Resize to smaller size", 128, 64, 16}, // 大小應保持不變
+		{"Resize to equal size", 64, 64, 8},     // 大小應保持不變
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 初始化一個 Bitmap
+			bitmap := MakeBitmapWithBitSize(tt.initialSize)
+
+			// 調用 Resize
+			resizedBitmap := bitmap.Resize(tt.newBitSize)
+
+			// 檢查結果的 byte 大小
+			assert.Equal(t, tt.expectedLen, len(resizedBitmap))
+		})
+	}
+}
+
+func TestBitmap_UpdateFrom(t *testing.T) {
+	tests := []struct {
+		name           string
+		initialSize    int
+		newBitmapSize  int
+		expectedBitPos uint32
+		expectedResult bool
+	}{
+		{"Update to larger bitmap", 64, 128, 50, true},
+		{"Update to smaller bitmap", 128, 64, 50, true},   // 新的 Bitmap 將只更新前面部分
+		{"Update to equal size bitmap", 64, 64, 20, true}, // 將相同大小的 Bitmap 進行合併
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// 初始化一個初始大小的 Bitmap
+			bitmap := MakeBitmapWithBitSize(tt.initialSize)
+			bitmap.SetTrue(tt.expectedBitPos)
+
+			// 初始化一個新的 Bitmap
+			newBitmap := MakeBitmapWithBitSize(tt.newBitmapSize)
+			newBitmap.SetTrue(tt.expectedBitPos)
+
+			// 更新 Bitmap
+			updatedBitmap := bitmap.UpdateFrom(newBitmap)
+
+			// 檢查預期的位是否為 true
+			result := updatedBitmap.IsTrue(tt.expectedBitPos)
+			assert.Equal(t, tt.expectedResult, result)
+		})
+	}
+}

utils/bitmap/go.mod

@@ -0,0 +1,11 @@
+module code.30cm.net/digimon/library-go/utils/bitmap
+
+go 1.22.3
+
+require github.com/stretchr/testify v1.9.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

utils/bitmap/usecase.go

@@ -0,0 +1,16 @@
+package usecase
+
+type BitMapUseCase interface {
+	// SetTrue 設定該 Bit 狀態為 true
+	SetTrue(bitPos uint32)
+	// SetFalse 設定該Bit 狀態為 false
+	SetFalse(bitPos uint32)
+	// IsTrue 確認是否為真
+	IsTrue(bitPos uint32) bool
+	// Reset 重設 BitMap
+	Reset()
+	// ByteSize 最大 Byte 數
+	ByteSize() int
+	// BitSize 最大 Byte * 8
+	BitSize() int
+}

utils/invited_code/convert_test.go

@@ -1,8 +1,9 @@
 package invited_code
 
 import (
-	"github.com/stretchr/testify/assert"
 	"testing"
+
+	"github.com/stretchr/testify/assert"
 )
 
 // 測試 ConvertUseCase 的功能