0
# Data Type Conversion
1
2
Comprehensive conversion utilities for transforming data between hex, bytes, numbers, strings, and Ethereum units. These functions handle the various data format conversions needed when working with blockchain data.
3
4
## Capabilities
5
6
### General Conversion Functions
7
8
#### Auto-Conversion to Hex
9
10
Automatically converts any value to hex representation with optional type detection.
11
12
```typescript { .api }
13
/**
14
* Auto-converts any value to hex representation
15
* @param value - Value to convert (Numbers, Bytes, Address, boolean, object)
16
* @param returnType - If true, returns both hex and detected type
17
* @returns Hex string or object with hex and type information
18
*/
19
function toHex(value: Numbers | Bytes | Address | boolean | object, returnType?: boolean): HexString | ValueTypes;
20
```
21
22
#### Number Conversion
23
24
Converts values to number or bigint representation.
25
26
```typescript { .api }
27
/**
28
* Converts value to number or bigint representation
29
* @param value - Numbers type to convert
30
* @returns number for small values, bigint for large values
31
*/
32
function toNumber(value: Numbers): number | bigint;
33
34
/**
35
* Auto-converts value to bigint representation
36
* @param value - Any value to convert
37
* @returns bigint representation
38
*/
39
function toBigInt(value: unknown): bigint;
40
```
41
42
#### Boolean Conversion
43
44
Converts various types to boolean values.
45
46
```typescript { .api }
47
/**
48
* Converts various types to boolean
49
* @param value - Value to convert to boolean
50
* @returns boolean representation
51
*/
52
function toBool(value: boolean | string | number | unknown): boolean;
53
```
54
55
### Byte and Hex Conversion
56
57
#### Bytes to Different Formats
58
59
```typescript { .api }
60
/**
61
* Converts bytes to Uint8Array representation
62
* @param data - Bytes data to convert
63
* @returns Uint8Array representation
64
*/
65
function bytesToUint8Array(data: Bytes): Uint8Array;
66
67
/**
68
* Converts byte array to hex string
69
* @param bytes - Bytes to convert
70
* @returns Hex string representation
71
*/
72
function bytesToHex(bytes: Bytes): HexString;
73
```
74
75
#### Hex to Other Formats
76
77
```typescript { .api }
78
/**
79
* Converts hex string to byte array
80
* @param bytes - Hex string to convert
81
* @returns Uint8Array representation
82
*/
83
function hexToBytes(bytes: HexString): Uint8Array;
84
85
/**
86
* Converts hex string to number representation
87
* @param value - Hex string to convert
88
* @returns number or bigint depending on size
89
*/
90
function hexToNumber(value: HexString): bigint | number;
91
92
/**
93
* Converts hex to decimal string representation
94
* @param data - Hex string to convert
95
* @returns Decimal string representation
96
*/
97
function hexToNumberString(data: HexString): string;
98
```
99
100
### Number and Hex Conversion
101
102
```typescript { .api }
103
/**
104
* Converts value to hex representation with optional padding
105
* @param value - Numbers type to convert
106
* @param hexstrict - If true, ensures proper hex formatting
107
* @returns Hex string representation
108
*/
109
function numberToHex(value: Numbers, hexstrict?: boolean): HexString;
110
```
111
112
### String and Text Conversion
113
114
#### UTF-8 Conversion
115
116
```typescript { .api }
117
/**
118
* Converts UTF-8 string to hex
119
* @param str - UTF-8 string to convert
120
* @returns Hex string representation
121
*/
122
function utf8ToHex(str: string): HexString;
123
124
/**
125
* Converts UTF-8 string to bytes
126
* @param str - UTF-8 string to convert
127
* @returns Uint8Array representation
128
*/
129
function utf8ToBytes(str: string): Uint8Array;
130
131
/**
132
* Converts hex to UTF-8 string
133
* @param str - Hex string to convert
134
* @returns UTF-8 string representation
135
*/
136
function hexToUtf8(str: HexString): string;
137
138
/**
139
* Converts hex or Uint8Array to UTF-8 (overloaded)
140
* @param input - Hex string or Uint8Array to convert
141
* @returns UTF-8 string representation
142
*/
143
function toUtf8(input: HexString | Uint8Array): string;
144
```
145
146
#### ASCII Conversion
147
148
```typescript { .api }
149
/**
150
* Converts ASCII string to hex
151
* @param str - ASCII string to convert
152
* @returns Hex string representation
153
*/
154
function asciiToHex(str: string): HexString;
155
156
/**
157
* Converts hex to ASCII string
158
* @param str - Hex string to convert
159
* @returns ASCII string representation
160
*/
161
function hexToAscii(str: HexString): string;
162
```
163
164
### Ethereum Unit Conversion
165
166
#### Wei and Ether Conversion
167
168
```typescript { .api }
169
/**
170
* Converts wei to other ether units
171
* @param number - Wei amount to convert
172
* @param unit - Target unit (ether, gwei, etc.) or unit multiplier
173
* @returns String representation of converted amount
174
*/
175
function fromWei(number: Numbers, unit: EtherUnits | number): string;
176
177
/**
178
* Converts ether units to wei
179
* @param number - Amount in specified unit to convert
180
* @param unit - Source unit (ether, gwei, etc.) or unit multiplier
181
* @returns String representation of wei amount
182
*/
183
function toWei(number: Numbers, unit: EtherUnits | number): string;
184
```
185
186
### Address Utilities
187
188
```typescript { .api }
189
/**
190
* Converts address to checksum format
191
* @param address - Address to convert
192
* @returns Checksummed address string
193
*/
194
function toChecksumAddress(address: Address): string;
195
```
196
197
## Function Aliases
198
199
Many conversion functions have aliases for backwards compatibility:
200
201
```typescript { .api }
202
// Hex/Number aliases
203
const toDecimal = hexToNumber;
204
const fromDecimal = numberToHex;
205
206
// UTF-8 aliases
207
const fromUtf8 = utf8ToHex;
208
const stringToHex = utf8ToHex;
209
const hexToString = hexToUtf8;
210
211
// ASCII aliases
212
const fromAscii = asciiToHex;
213
const toAscii = hexToAscii;
214
```
215
216
## Usage Examples
217
218
```typescript
219
import {
220
toHex, toNumber, fromWei, toWei,
221
utf8ToHex, hexToUtf8, toChecksumAddress
222
} from "web3-utils";
223
224
// General conversion
225
const hexValue = toHex(1234); // "0x4d2"
226
const hexBoolean = toHex(true); // "0x01"
227
const number = toNumber("0x4d2"); // 1234
228
229
// Wei/Ether conversion
230
const ethAmount = fromWei("1000000000000000000", "ether"); // "1"
231
const gweiAmount = fromWei("1000000000", "gwei"); // "1"
232
const weiAmount = toWei("1.5", "ether"); // "1500000000000000000"
233
234
// String conversion
235
const hexString = utf8ToHex("Hello World"); // "0x48656c6c6f20576f726c64"
236
const originalString = hexToUtf8(hexString); // "Hello World"
237
238
// Address formatting
239
const addr = "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed";
240
const checksumAddr = toChecksumAddress(addr);
241
// "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAeD"
242
```
243
244
## Types and Constants
245
246
```typescript { .api }
247
// Ethereum unit mapping
248
const ethUnitMap: Record<string, bigint>;
249
250
// Union type of available ether units
251
type EtherUnits = keyof typeof ethUnitMap;
252
// "wei" | "kwei" | "mwei" | "gwei" | "szabo" | "finney" | "ether"
253
```