add docs

Author: lixizan

README.md

@@ -10,6 +10,11 @@
 
 [4]: https://codecov.io/gh/lxzan/memorycache
 
+### Description
+Minimalist in-memory KV storage, powered by hashmap and minimal heap, with no special optimizations for GC.
+It has O(1) read efficiency, O(logN) write efficiency.
+Cache deprecation policy: obsolete or overflowed keys are flushed, with a 30s (default) check.
+
 ### Usage
 ```go
 package main

index.go

@@ -16,6 +16,7 @@ type MemoryCache struct {
 }
 
 // New 创建缓存数据库实例
+// Creating a Cached Database Instance
 func New(options ...Option) *MemoryCache {
 	var config = &types.Config{}
 	options = append(options, withInitialize())
@@ -63,6 +64,7 @@ func (c *MemoryCache) getExp(d time.Duration) int64 {
 }
 
 // Set 设置键值和过期时间. exp<=0表示永不过期.
+// Set the key value and expiration time. exp<=0 means never expire.
 func (c *MemoryCache) Set(key string, value any, exp time.Duration) (replaced bool) {
 	var b = c.getBucket(key)
 	b.Lock()
@@ -88,7 +90,7 @@ func (c *MemoryCache) Set(key string, value any, exp time.Duration) (replaced bo
 	return false
 }
 
-// Get 获取
+// Get
 func (c *MemoryCache) Get(key string) (any, bool) {
 	var b = c.getBucket(key)
 	b.Lock()
@@ -101,6 +103,7 @@ func (c *MemoryCache) Get(key string) (any, bool) {
 }
 
 // GetAndRefresh 获取. 如果存在, 刷新过期时间.
+// Get a value. If it exists, refreshes the expiration time.
 func (c *MemoryCache) GetAndRefresh(key string, exp time.Duration) (any, bool) {
 	var b = c.getBucket(key)
 	b.Lock()
@@ -116,7 +119,7 @@ func (c *MemoryCache) GetAndRefresh(key string, exp time.Duration) (any, bool) {
 	return v, true
 }
 
-// Delete 删除一个键
+// Delete
 func (c *MemoryCache) Delete(key string) (deleted bool) {
 	var b = c.getBucket(key)
 	b.Lock()
@@ -132,7 +135,8 @@ func (c *MemoryCache) Delete(key string) (deleted bool) {
 	return true
 }
 
-// Keys 获取前缀匹配的key, 星号匹配所有
+// Keys 获取前缀匹配的key. 可以通过星号获取所有的key.
+// Get prefix matching key,  You can get all the keys with an asterisk.
 func (c *MemoryCache) Keys(prefix string) []string {
 	var arr = make([]string, 0)
 	var now = time.Now().UnixMilli()
@@ -148,15 +152,21 @@ func (c *MemoryCache) Keys(prefix string) []string {
 	return arr
 }
 
-// Len 获取有效元素(未过期)数量
-func (c *MemoryCache) Len() int {
+// Len 获取元素数量
+// Get the number of elements
+// @check: 是否检查过期时间 (whether to check expiration time)
+func (c *MemoryCache) Len(check bool) int {
 	var num = 0
 	var now = time.Now().UnixMilli()
 	for _, b := range c.storage {
 		b.Lock()
-		for _, v := range b.Heap.Data {
-			if !v.Expired(now) {
-				num++
+		if !check {
+			num += b.Heap.Len()
+		} else {
+			for _, v := range b.Heap.Data {
+				if !v.Expired(now) {
+					num++
+				}
 			}
 		}
 		b.Unlock()

index_test.go

@@ -46,7 +46,7 @@ func TestNew(t *testing.T) {
 		db.Set("d", 1, 40*time.Millisecond)
 
 		time.Sleep(50 * time.Millisecond)
-		as.Equal(0, db.Len())
+		as.Equal(0, db.Len(true))
 	})
 }
 
@@ -150,7 +150,7 @@ func TestMemoryCache_Delete(t *testing.T) {
 		deleted = mc.Delete(key)
 		assert.False(t, deleted)
 	}
-	assert.Equal(t, mc.Len(), count-100)
+	assert.Equal(t, mc.Len(true), count-100)
 }
 
 func TestMaxCap(t *testing.T) {
@@ -164,5 +164,5 @@ func TestMaxCap(t *testing.T) {
 		mc.Set(key, 1, -1)
 	}
 	time.Sleep(200 * time.Millisecond)
-	assert.Equal(t, mc.Len(), 100)
+	assert.Equal(t, mc.Len(false), 100)
 }