再次修改文档

yyle88 · Nov 26, 2024 · 5ad6d0d · 5ad6d0d
1 parent 1beaad4
commit 5ad6d0d
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -19,9 +19,9 @@ It makes using `sync.Map` easier and safer by letting you define the types for k
 
 Using `SyncMap` has several advantages:
 
-- **Generic Type**: When you define the key and value types, you can avoid type mismatches.
-- **Clearer Code**: No need for type assertions, making your code easier to write.
-- **Simple Usage**: Works just same as `sync.Map`, so there’s no steep learning curve.
+- **Generic Type**: Helps avoid type mismatches during runtime.
+- **Clearer Code**: No need for type assertions from `interface{}`.
+- **Simple Usage**: Works just same as `sync.Map`, same methods.
 
 ## Installation
 
@@ -33,7 +33,7 @@ go get github.com/yyle88/syncmap
 
 Here’s a simple example showing how you can use `SyncMap` to safely store and retrieve structured data.
 
-### Example: Storing and Retrieving Data
+### Example 1: Storing and Retrieving Data
 
 ```go
 package main
@@ -62,18 +62,19 @@ func main() {
 }
 ```
 
-### How This Example Helps
+#### Explanation
 
-1. **Defines Clear Types**: The key is a `string`, and the value is a `User`. Without using `interface{}` to store value.
-2. **Simplifies Data Access**: No need for manual type assertions when loading data. No need `user = v.(*User)` logic.
-3. **Works Same with `sync.Map`**: If you have used `sync.Map` before, the functions like `Store` and `Load` are same.
+1. **Defines Clear Types**: The key is a `string`, and the value is a `User` struct pointer, avoiding the use of `interface{}` for values.
+2. **Simplifies Data Access**: No need for manual type assertions like `user = v.(*User)` when retrieving data.
+3. **Works Same with `sync.Map`**: Functions like `Store` and `Load` are exactly the same as in `sync.Map`, so you don't need to learn new methods.
+
+### Example 2: Storing, Deleting, and Iterating Over Data
 
 ```go
 package main
 
 import (
 	"fmt"
-
 	"github.com/yyle88/syncmap"
 )
 
@@ -84,8 +85,10 @@ type Person struct {
 }
 
 func main() {
+	// Create a SyncMap with int keys and *Person values
 	mp := syncmap.NewMap[int, *Person]()
 
+	// Add some persons to the map
 	mp.Store(1, &Person{
 		Name:     "Kratos",
 		HomePage: "https://go-kratos.dev/",
@@ -99,30 +102,38 @@ func main() {
 		Age:  18,
 	})
 
+	// Delete the entry with key 3
 	mp.Delete(3)
 
+	// Iterate over all items in the map
 	mp.Range(func(key int, value *Person) bool {
 		fmt.Println(key, value.Name, value.Age, value.HomePage)
 		return true
 	})
 }
 ```
 
+#### Explanation
+
+1. **Store and Delete**: This example shows how to add multiple entries and delete one using the `Delete` method.
+2. **Iterate Over Data**: The `Range` method is used to iterate over all the key-value pairs in the map, which simplifies traversing the map compared to manually managing `sync.Map`'s iteration.
+3. **Simplified Operations**: Just like with the previous example, no type assertions are required, and the usage is straightforward.
+
 ---
 
 ## SyncMap API
 
 `SyncMap` provides the following functions:
 
-| Function                  | Description                                                   |
-|---------------------------|---------------------------------------------------------------|
-| `Store(key, value)`       | Adds or updates a key-value.                             |
-| `Load(key)`               | Retrieves the value.                                |
-| `LoadOrStore(key, value)` | Returns the value if it exists; otherwise, adds the new key-value. |
-| `Delete(key)`             | Removes a key-value pair from the map.                        |
-| `Range(func)`             | Iterates over all key-value pairs in the map.                 |
+| Function                  | Description                                                      |
+|---------------------------|------------------------------------------------------------------|
+| `Store(key, value)`       | Adds or updates a key-value.                                     |
+| `Load(key)`               | Retrieves the value.                                             |
+| `LoadOrStore(key, value)` | Returns the value if it exists; otherwise, adds a new key-value. |
+| `Delete(key)`             | Removes the key-value pair from the map.                         |
+| `Range(func)`             | Iterates over all key-value pairs in the map.                    |
 
-Same with `sync.Map`
+Same as `sync.Map`.
 
 ---
 

diff --git a/README.zh.md b/README.zh.md
@@ -13,7 +13,7 @@
 使用 `SyncMap` 有以下几个优点：
 
 - **泛型类型**：通过定义键和值的类型，避免了因类型不匹配导致的运行时错误。
-- **更简洁的代码**：不需要类型断言，使得代码更容易编写。
+- **更简洁的代码**：不需要类型断言，避免使用 `interface{}` 的复杂操作。
 - **简单易用**：与 `sync.Map` 的使用方式相同，无需学习复杂的新概念。
 
 ## 安装
@@ -26,7 +26,7 @@ go get github.com/yyle88/syncmap
 
 以下是一个简单的示例，展示了如何使用 `SyncMap` 安全地存储和检索结构化数据。
 
-### 示例：存储和检索数据
+### 示例 1：存储和检索数据
 
 ```go
 package main
@@ -42,7 +42,7 @@ type User struct {
 }
 
 func main() {
-	// 创建一个以 string 为键、*User 为值的 SyncMap
+	// 创建一个以 string 为键、User 结构体指针为值的 SyncMap
 	users := syncmap.NewMap[string, *User]()
 
 	// 向 Map 中添加一个用户
@@ -55,18 +55,19 @@ func main() {
 }
 ```
 
-### 示例说明
+#### 说明
 
-1. **明确的类型定义**：键是 `string`，值是 `User` 结构体的指针。避免使用 `interface{}` 类型存储值。
-2. **简化的数据访问**：不需要手动进行类型断言。无需像 `user = v.(*User)` 的操作。
-3. **与 `sync.Map` 使用方式相同**：如果你已经使用过 `sync.Map`，那么 `Store` 和 `Load` 等函数的使用方式是一样的。
+1. **明确的类型定义**：键是 `string`，值是 `User` 结构体的指针，避免了使用 `interface{}` 这个模糊的类型来存储值。
+2. **简化的数据访问**：不需要手动进行类型断言，直接获取数据时无需 `user = v.(*User)` 的操作。
+3. **与 `sync.Map` 使用方式相同**：与传统的 `sync.Map` 使用方式一致，`Store` 和 `Load` 等方法不需要额外学习。
+
+### 示例 2：使用 SyncMap 存储、删除和遍历数据
 
 ```go
 package main
 
 import (
 	"fmt"
-
 	"github.com/yyle88/syncmap"
 )
 
@@ -77,8 +78,10 @@ type Person struct {
 }
 
 func main() {
+	// 创建一个以 int 为键、*Person 为值的 SyncMap
 	mp := syncmap.NewMap[int, *Person]()
 
+	// 向 Map 中添加几个 Person
 	mp.Store(1, &Person{
 		Name:     "Kratos",
 		HomePage: "https://go-kratos.dev/",
@@ -92,28 +95,36 @@ func main() {
 		Age:  18,
 	})
 
+	// 删除键为 3 的元素
 	mp.Delete(3)
 
+	// 遍历 Map 中的所有元素
 	mp.Range(func(key int, value *Person) bool {
 		fmt.Println(key, value.Name, value.Age, value.HomePage)
 		return true
 	})
 }
 ```
 
+#### 说明
+
+1. **存储和删除**：这个示例展示了如何存储多个对象，并通过 `Delete` 方法删除指定的元素。
+2. **遍历操作**：通过 `Range` 方法遍历 `SyncMap` 中所有的键值对，无需手动操作 `sync.Map` 的底层实现。
+3. **简化操作**：相比于传统的 `sync.Map`，这段代码中不需要任何类型断言，操作直观且清晰。
+
 ---
 
 ## SyncMap API
 
 `SyncMap` 提供以下函数：
 
-| 函数                      | 描述                                                         |
-|---------------------------|--------------------------------------------------------------|
-| `Store(key, value)`       | 添加或更新一个键值对。                                       |
-| `Load(key)`               | 获取指定键对应的值。                                         |
-| `LoadOrStore(key, value)` | 如果值已存在则返回该值，否则将指定的键值对添加到 Map 中。   |
-| `Delete(key)`             | 删除指定的键值对。                                           |
-| `Range(func)`             | 遍历 Map 中的所有键值对。                                    |
+| 函数                        | 描述                              |
+|---------------------------|---------------------------------|
+| `Store(key, value)`       | 添加或更新一个键值对。                     |
+| `Load(key)`               | 获取指定键对应的值。                      |
+| `LoadOrStore(key, value)` | 如果值已存在则返回该值，否则将指定的键值对添加到 Map 中。 |
+| `Delete(key)`             | 删除指定的键值对。                       |
+| `Range(func)`             | 遍历 Map 中的所有键值对。                 |
 
 完全与 `sync.Map` 相同。