Skip to content

Commit 6e785c5

Browse files
waruqiwaruqi
committed
update hash docs
1 parent 1300980 commit 6e785c5

File tree

2 files changed

+333
-66
lines changed
  • docs
    • api/scripts/builtin-modules
    • zh/api/scripts/builtin-modules

2 files changed

+333
-66
lines changed

‎docs/api/scripts/builtin-modules/hash.md‎

Lines changed: 163 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ The hash module provides hash value calculation and UUID generation functions. I
55

66
## hash.md5
77

8-
- Calculate the MD5 hash value of a string or file
8+
- Calculate the MD5 hash value of a file or binary data
99

1010
#### Function Prototype
1111

1212
::: tip API
1313
```lua
14-
hash.md5(input: <string>)
14+
hash.md5(input: <string|bytes>)
1515
```
1616
:::
1717

@@ -20,35 +20,59 @@ hash.md5(input: <string>)
2020

2121
| Parameter | Description |
2222
|-----------|-------------|
23-
| input | String or file path |
23+
| input | File path (string) or binary data (bytes) |
24+
25+
::: warning Important Notes
26+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
27+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
28+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash32`, `hash.strhash64`, or `hash.strhash128` interfaces
29+
- **Common mistake**: If the file doesn't exist, the function will incorrectly treat the file path as string data to calculate the hash value, and it won't report an error, resulting in incorrect results
30+
:::
2431

2532
#### Usage
2633

34+
Calculates the MD5 hash value of the specified file or binary data and returns a hexadecimal format hash string.
35+
36+
**Calculate file hash value:**
37+
2738
```lua
28-
local hashval = hash.md5("hello")
29-
local hashval = hash.md5("/path/to/file")
39+
-- Calculate MD5 hash value of a file
40+
local checksum = hash.md5("/path/to/file.txt")
41+
print("MD5: " .. checksum)
3042
```
3143

32-
Calculates the MD5 hash value of the specified string or file and returns a hexadecimal format hash string. Supports both string and file path as input.
33-
34-
Commonly used for calculating file content checksums:
44+
**Calculate binary data hash value:**
3545

3646
```lua
37-
-- Read file content and calculate MD5
38-
local content = io.readfile("file.txt")
39-
local checksum = hash.md5(content)
47+
import("core.base.bytes")
48+
49+
-- Calculate MD5 hash value of binary data
50+
local data = bytes("hello")
51+
local checksum = hash.md5(data)
4052
print("MD5: " .. checksum)
4153
```
4254

55+
**Incorrect usage (don't do this):**
56+
57+
```lua
58+
-- ❌ Wrong: If "hello" is not a file path, it will incorrectly calculate the hash of the file path string
59+
local checksum = hash.md5("hello")
60+
61+
-- ✅ Correct: Use strhash interface to calculate string hash value
62+
local checksum = hash.strhash32("hello")
63+
-- Or use bytes wrapper
64+
local checksum = hash.md5(bytes("hello"))
65+
```
66+
4367
## hash.sha1
4468

45-
- Calculate the SHA1 hash value of a string or file
69+
- Calculate the SHA1 hash value of a file or binary data
4670

4771
#### Function Prototype
4872

4973
::: tip API
5074
```lua
51-
hash.sha1(input: <string>)
75+
hash.sha1(input: <string|bytes>)
5276
```
5377
:::
5478

@@ -57,26 +81,43 @@ hash.sha1(input: <string>)
5781

5882
| Parameter | Description |
5983
|-----------|-------------|
60-
| input | String or file path |
84+
| input | File path (string) or binary data (bytes) |
85+
86+
::: warning Important Notes
87+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
88+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
89+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash32`, `hash.strhash64`, or `hash.strhash128` interfaces
90+
:::
6191

6292
#### Usage
6393

94+
Calculates the SHA1 hash value of the specified file or binary data and returns a hexadecimal format hash string.
95+
96+
**Calculate file hash value:**
97+
6498
```lua
65-
local hashval = hash.sha1("hello")
66-
local hashval = hash.sha1("/path/to/file")
99+
-- Calculate SHA1 hash value of a file
100+
local checksum = hash.sha1("/path/to/file.txt")
67101
```
68102

69-
Calculates the SHA1 hash value of the specified string or file and returns a hexadecimal format hash string.
103+
**Calculate binary data hash value:**
104+
105+
```lua
106+
import("core.base.bytes")
107+
108+
-- Calculate SHA1 hash value of binary data
109+
local checksum = hash.sha1(bytes("hello"))
110+
```
70111

71112
## hash.sha256
72113

73-
- Calculate the SHA256 hash value of a string or file
114+
- Calculate the SHA256 hash value of a file or binary data
74115

75116
#### Function Prototype
76117

77118
::: tip API
78119
```lua
79-
hash.sha256(input: <string>)
120+
hash.sha256(input: <string|bytes>)
80121
```
81122
:::
82123

@@ -85,19 +126,22 @@ hash.sha256(input: <string>)
85126

86127
| Parameter | Description |
87128
|-----------|-------------|
88-
| input | String or file path |
129+
| input | File path (string) or binary data (bytes) |
89130

90-
#### Usage
131+
::: warning Important Notes
132+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
133+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
134+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash32`, `hash.strhash64`, or `hash.strhash128` interfaces
135+
:::
91136

92-
```lua
93-
local hashval = hash.sha256("hello")
94-
local hashval = hash.sha256("/path/to/file")
95-
```
137+
#### Usage
96138

97-
Calculates the SHA256 hash value of the specified string or file and returns a hexadecimal format hash string.
139+
Calculates the SHA256 hash value of the specified file or binary data and returns a hexadecimal format hash string.
98140

99141
SHA256 is more secure than MD5 and is commonly used for package integrity verification:
100142

143+
**Calculate file hash value:**
144+
101145
```lua
102146
-- Verify downloaded package file
103147
local packagefile = "package.tar.gz"
@@ -107,6 +151,15 @@ if checksum ~= expected_hash then
107151
end
108152
```
109153

154+
**Calculate binary data hash value:**
155+
156+
```lua
157+
import("core.base.bytes")
158+
159+
-- Calculate SHA256 hash value of binary data
160+
local checksum = hash.sha256(bytes("hello"))
161+
```
162+
110163
## hash.uuid
111164

112165
- Generate a UUID based on a name
@@ -145,13 +198,13 @@ local config_id = hash.uuid("debug-x64-windows")
145198

146199
## hash.xxhash32
147200

148-
- Calculate the 32-bit xxHash hash value of a string or file
201+
- Calculate the 32-bit xxHash hash value of a file or binary data
149202

150203
#### Function Prototype
151204

152205
::: tip API
153206
```lua
154-
hash.xxhash32(input: <string>)
207+
hash.xxhash32(input: <string|bytes>)
155208
```
156209
:::
157210

@@ -160,21 +213,43 @@ hash.xxhash32(input: <string>)
160213

161214
| Parameter | Description |
162215
|-----------|-------------|
163-
| input | String or file path |
216+
| input | File path (string) or binary data (bytes) |
217+
218+
::: warning Important Notes
219+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
220+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
221+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash32` interface
222+
:::
164223

165224
#### Usage
166225

167226
Calculates hash value using the xxHash32 algorithm. xxHash is an extremely fast non-cryptographic hash algorithm suitable for hash tables, checksums, and other scenarios.
168227

228+
**Calculate file hash value:**
229+
230+
```lua
231+
-- Calculate xxHash32 hash value of a file
232+
local checksum = hash.xxhash32("/path/to/file.txt")
233+
```
234+
235+
**Calculate binary data hash value:**
236+
237+
```lua
238+
import("core.base.bytes")
239+
240+
-- Calculate xxHash32 hash value of binary data
241+
local checksum = hash.xxhash32(bytes("hello"))
242+
```
243+
169244
## hash.xxhash64
170245

171-
- Calculate the 64-bit xxHash hash value of a string or file
246+
- Calculate the 64-bit xxHash hash value of a file or binary data
172247

173248
#### Function Prototype
174249

175250
::: tip API
176251
```lua
177-
hash.xxhash64(input: <string>)
252+
hash.xxhash64(input: <string|bytes>)
178253
```
179254
:::
180255

@@ -183,26 +258,55 @@ hash.xxhash64(input: <string>)
183258

184259
| Parameter | Description |
185260
|-----------|-------------|
186-
| input | String or file path |
261+
| input | File path (string) or binary data (bytes) |
262+
263+
::: warning Important Notes
264+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
265+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
266+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash64` interface
267+
:::
187268

188269
#### Usage
189270

190-
Calculates hash value using the xxHash64 algorithm. Fast and suitable for quick verification:
271+
Calculates hash value using the xxHash64 algorithm. Fast and suitable for quick verification.
272+
273+
**Calculate file hash value:**
274+
275+
```lua
276+
-- Calculate xxHash64 hash value of a file
277+
local checksum = hash.xxhash64("/path/to/file.txt")
278+
```
279+
280+
**Calculate binary data hash value:**
191281

192282
```lua
193-
-- Generate fast hash key for compilation parameters
283+
import("core.base.bytes")
284+
285+
-- Calculate xxHash64 hash value of binary data
286+
local checksum = hash.xxhash64(bytes("hello"))
287+
```
288+
289+
**Incorrect usage (don't do this):**
290+
291+
```lua
292+
-- ❌ Wrong: Don't pass string data directly
194293
local key = hash.xxhash64(table.concat(params, "|"))
294+
295+
-- ✅ Correct: Use strhash64 interface to calculate string hash value
296+
local key = hash.strhash64(table.concat(params, "|"))
297+
-- Or use bytes wrapper
298+
local key = hash.xxhash64(bytes(table.concat(params, "|")))
195299
```
196300

197301
## hash.xxhash128
198302

199-
- Calculate the 128-bit xxHash hash value of a string or file
303+
- Calculate the 128-bit xxHash hash value of a file or binary data
200304

201305
#### Function Prototype
202306

203307
::: tip API
204308
```lua
205-
hash.xxhash128(input: <string>)
309+
hash.xxhash128(input: <string|bytes>)
206310
```
207311
:::
208312

@@ -211,12 +315,34 @@ hash.xxhash128(input: <string>)
211315

212316
| Parameter | Description |
213317
|-----------|-------------|
214-
| input | String or file path |
318+
| input | File path (string) or binary data (bytes) |
319+
320+
::: warning Important Notes
321+
- **String parameter is only for file paths**: If a string is passed, the function will calculate the hash value of that file
322+
- **Binary data must use bytes parameter**: To calculate the hash value of binary data, you must wrap the data with the `bytes()` function
323+
- **String data hashing**: To calculate the hash value of string data, please use `hash.strhash128` interface
324+
:::
215325

216326
#### Usage
217327

218328
Calculates hash value using the xxHash128 algorithm, providing longer hash values to reduce collisions.
219329

330+
**Calculate file hash value:**
331+
332+
```lua
333+
-- Calculate xxHash128 hash value of a file
334+
local checksum = hash.xxhash128("/path/to/file.txt")
335+
```
336+
337+
**Calculate binary data hash value:**
338+
339+
```lua
340+
import("core.base.bytes")
341+
342+
-- Calculate xxHash128 hash value of binary data
343+
local checksum = hash.xxhash128(bytes("hello"))
344+
```
345+
220346
## hash.strhash32
221347

222348
- Generate a 32-bit hash value from a string

0 commit comments

Comments
 (0)