0
# Data Conversion
1

2
Bi-directional conversion utilities for transforming data between different formats commonly used in blockchain applications, including hex strings, Uint8Arrays, numbers, and various text encodings.
3

4
## Capabilities
5

6
### Hex String Conversion
7

8
Convert between hex strings and other data types with proper validation and formatting.
9

10
```typescript { .api }
11
/**
12
 * Converts hex string to Uint8Array
13
 * @param value - Hex string (with or without 0x prefix)
14
 * @param bitLength - Expected bit length for validation
15
 */
16
function hexToU8a(value?: string | null, bitLength?: number): Uint8Array;
17

18
/**
19
 * Converts hex string to BigInt
20
 * @param value - Hex string
21
 */
22
function hexToBigInt(value: string): bigint;
23

24
/**
25
 * Converts hex string to BN (big number)
26
 * @param value - Hex string
27
 */
28
function hexToBn(value: string): BN;
29

30
/**
31
 * Converts hex string to regular number
32
 * @param value - Hex string
33
 */
34
function hexToNumber(value: string): number;
35

36
/**
37
 * Converts hex string to UTF-8 string
38
 * @param value - Hex string representing UTF-8 encoded text
39
 */
40
function hexToString(value: string): string;
41
```
42

43
### Uint8Array Conversion
44

45
Convert Uint8Arrays to various data formats and back.
46

47
```typescript { .api }
48
/**
49
 * Converts Uint8Array to hex string
50
 * @param value - Uint8Array to convert
51
 * @param bitLength - Expected bit length (-1 for no padding)
52
 * @param isPrefixed - Whether to include 0x prefix
53
 */
54
function u8aToHex(value?: Uint8Array | null, bitLength?: number, isPrefixed?: boolean): HexString;
55

56
/**
57
 * Converts Uint8Array to BigInt
58
 * @param value - Uint8Array in little-endian format
59
 */
60
function u8aToBigInt(value: Uint8Array): bigint;
61

62
/**
63
 * Converts Uint8Array to BN
64
 * @param value - Uint8Array
65
 * @param options - Conversion options (isLe, isNegative)
66
 */
67
function u8aToBn(value: Uint8Array, options?: ToBnOptions): BN;
68

69
/**
70
 * Converts Uint8Array to regular number
71
 * @param value - Uint8Array
72
 * @param options - Conversion options
73
 */
74
function u8aToNumber(value: Uint8Array, options?: NumberOptions): number;
75

76
/**
77
 * Converts Uint8Array to UTF-8 string
78
 * @param value - Uint8Array containing UTF-8 encoded text
79
 */
80
function u8aToString(value: Uint8Array): string;
81

82
/**
83
 * Converts Uint8Array to Buffer (Node.js)
84
 * @param value - Uint8Array to convert
85
 */
86
function u8aToBuffer(value: Uint8Array): Buffer;
87

88
/**
89
 * Converts Uint8Array to floating point number
90
 * @param value - Uint8Array (4 or 8 bytes)
91
 * @param options - Conversion options
92
 */
93
function u8aToFloat(value: Uint8Array, options?: NumberOptions): number;
94
```
95

96
### String Conversion
97

98
Convert strings to various binary formats and back.
99

100
```typescript { .api }
101
/**
102
 * Converts UTF-8 string to Uint8Array
103
 * @param value - String to convert
104
 */
105
function stringToU8a(value: string): Uint8Array;
106

107
/**
108
 * Converts UTF-8 string to hex string
109
 * @param value - String to convert
110
 */
111
function stringToHex(value: string): HexString;
112
```
113

114
### Number Conversion
115

116
Convert numbers to binary formats.
117

118
```typescript { .api }
119
/**
120
 * Converts number to hex string
121
 * @param value - Number to convert
122
 * @param bitLength - Expected bit length for padding
123
 */
124
function numberToHex(value: number, bitLength?: number): HexString;
125

126
/**
127
 * Converts number to Uint8Array
128
 * @param value - Number to convert
129
 * @param bitLength - Expected bit length in bits
130
 */
131
function numberToU8a(value: number, bitLength?: number): Uint8Array;
132

133
/**
134
 * Converts floating point number to Uint8Array
135
 * @param value - Float number to convert
136
 * @param bitLength - 32 for float32, 64 for float64
137
 */
138
function floatToU8a(value: number, bitLength?: 32 | 64): Uint8Array;
139
```
140

141
### BigInt Conversion
142

143
Convert BigInt values to various formats.
144

145
```typescript { .api }
146
/**
147
 * Converts BigInt to hex string
148
 * @param value - BigInt to convert
149
 * @param bitLength - Expected bit length for padding
150
 */
151
function nToHex(value: bigint, bitLength?: number): HexString;
152

153
/**
154
 * Converts BigInt to Uint8Array
155
 * @param value - BigInt to convert
156
 * @param bitLength - Expected bit length in bits
157
 */
158
function nToU8a(value: bigint, bitLength?: number): Uint8Array;
159

160
/**
161
 * Converts number to BigInt
162
 * @param value - Number to convert
163
 */
164
function nToBigInt(value: number | bigint | string): bigint;
165
```
166

167
### BN Conversion
168

169
Convert BN (big number) values to various formats.
170

171
```typescript { .api }
172
/**
173
 * Converts BN to hex string
174
 * @param value - BN to convert
175
 * @param bitLength - Expected bit length for padding
176
 */
177
function bnToHex(value: BN, bitLength?: number): HexString;
178

179
/**
180
 * Converts BN to Uint8Array
181
 * @param value - BN to convert
182
 * @param options - Conversion options
183
 */
184
function bnToU8a(value: BN, options?: ToBnOptions): Uint8Array;
185

186
/**
187
 * Converts value to BN
188
 * @param value - Value to convert (number, string, bigint, Uint8Array, BN)
189
 */
190
function bnToBn(value: BN | number | string | bigint | Uint8Array): BN;
191

192
/**
193
 * Creates BN from hex string
194
 * @param value - Hex string
195
 */
196
function bnFromHex(value: string): BN;
197
```
198

199
### Buffer Conversion
200

201
Convert Buffer objects to Uint8Array (Node.js compatibility).
202

203
```typescript { .api }
204
/**
205
 * Converts Buffer to Uint8Array
206
 * @param buffer - Buffer to convert
207
 */
208
function bufferToU8a(buffer: Buffer): Uint8Array;
209
```
210

211
### Utility Conversion
212

213
Ensure values are in the correct format.
214

215
```typescript { .api }
216
/**
217
 * Ensures value is a Uint8Array, converting if necessary
218
 * @param value - Value to convert (string, number array, or Uint8Array)
219
 */
220
function u8aToU8a(value?: U8aLike | null): Uint8Array;
221
```
222

223
## Usage Examples
224

225
**Basic Hex Conversion:**
226

227
```typescript
228
import { hexToU8a, u8aToHex } from "@polkadot/util";
229

230
// Convert hex string to bytes
231
const bytes = hexToU8a("0x48656c6c6f"); // [72, 101, 108, 108, 111]
232

233
// Convert bytes back to hex
234
const hex = u8aToHex(bytes); // "0x48656c6c6f"
235

236
// Convert without 0x prefix
237
const hexUnprefixed = u8aToHex(bytes, -1, false); // "48656c6c6f"
238
```
239

240
**String Encoding:**
241

242
```typescript
243
import { stringToU8a, u8aToString, stringToHex } from "@polkadot/util";
244

245
const message = "Hello, World!";
246

247
// String to bytes
248
const bytes = stringToU8a(message);
249

250
// Bytes back to string
251
const decoded = u8aToString(bytes); // "Hello, World!"
252

253
// String directly to hex
254
const hex = stringToHex(message); // "0x48656c6c6f2c20576f726c6421"
255
```
256

257
**Number Conversion:**
258

259
```typescript
260
import { numberToHex, numberToU8a, u8aToNumber } from "@polkadot/util";
261

262
const num = 255;
263

264
// Number to hex with padding
265
const hex = numberToHex(num, 16); // "0x00ff"
266

267
// Number to bytes
268
const bytes = numberToU8a(num, 16); // [255, 0] (little-endian)
269

270
// Bytes back to number
271
const decoded = u8aToNumber(bytes); // 255
272
```
273

274
**BigInt and BN Conversion:**
275

276
```typescript
277
import { 
278
  nToBigInt, nToHex, nToU8a,
279
  bnToBn, bnToHex, bnToU8a 
280
} from "@polkadot/util";
281

282
// BigInt conversion
283
const bigInt = nToBigInt("12345678901234567890");
284
const hex = nToHex(bigInt); // "0xab54a98ceb1f0ad2"
285
const bytes = nToU8a(bigInt);
286

287
// BN conversion
288
const bn = bnToBn("12345678901234567890");
289
const bnHex = bnToHex(bn); // "0xab54a98ceb1f0ad2"
290
const bnBytes = bnToU8a(bn);
291
```
292

293
## Types
294

295
```typescript { .api }
296
type HexString = `0x${string}`;
297
type U8aLike = number[] | Uint8Array | string;
298

299
interface ToBnOptions {
300
  isLe?: boolean;
301
  isNegative?: boolean;
302
}
303

304
interface NumberOptions extends ToBnOptions {
305
  bitLength?: number;
306
}
307
```