0
# String Encoding
1

2
Comprehensive string encoding and decoding functions supporting UTF-8, hex, base64, and all multibase formats. Provides seamless conversion between strings and Uint8Arrays with extensive encoding support.
3

4
## Capabilities
5

6
### String to Uint8Array Conversion
7

8
Converts strings to Uint8Arrays using specified encoding. Supports UTF-8 and all multibase encoding formats.
9

10
```typescript { .api }
11
/**
12
 * Create a Uint8Array from the passed string
13
 * Supports utf8, utf-8, hex, and any encoding supported by the multiformats module.
14
 * Also ascii which is similar to node's 'binary' encoding.
15
 * @param string - String to convert
16
 * @param encoding - Encoding format (default: 'utf8')
17
 * @returns Uint8Array representation of the string
18
 * @throws Error if encoding is unsupported
19
 */
20
function fromString(string: string, encoding?: SupportedEncodings): Uint8Array;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { fromString } from "uint8arrays/from-string";
27

28
// Default UTF-8 encoding
29
const utf8Bytes = fromString("Hello World");
30
console.log(utf8Bytes); // Uint8Array(11) [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]
31

32
// Hex encoding
33
const hexBytes = fromString("48656c6c6f", "hex");
34
console.log(hexBytes); // Uint8Array(5) [72, 101, 108, 108, 111] ("Hello")
35

36
// Base64 encoding
37
const base64Bytes = fromString("SGVsbG8gV29ybGQ=", "base64");
38
console.log(base64Bytes); // "Hello World" as bytes
39

40
// Base16 (hex with multibase)
41
const base16Bytes = fromString("48656c6c6f", "base16");
42

43
// ASCII encoding (binary-like)
44
const asciiBytes = fromString("ABC", "ascii");
45
console.log(asciiBytes); // Uint8Array(3) [65, 66, 67]
46

47
// Unicode strings
48
const unicodeBytes = fromString("🚀 Hello", "utf8");
49
console.log(unicodeBytes); // Properly encoded UTF-8 bytes
50

51
// Base58 encoding
52
const base58Bytes = fromString("StV1DL6CwTryKyV", "base58btc");
53
```
54

55
### Uint8Array to String Conversion
56

57
Converts Uint8Arrays to strings using specified encoding. Supports the same comprehensive set of encodings as fromString.
58

59
```typescript { .api }
60
/**
61
 * Turns a Uint8Array into a string.
62
 * Supports utf8, utf-8 and any encoding supported by the multibase module.
63
 * Also ascii which is similar to node's 'binary' encoding.
64
 * @param array - Uint8Array to convert
65
 * @param encoding - Encoding format (default: 'utf8')
66
 * @returns String representation of the array
67
 * @throws Error if encoding is unsupported
68
 */
69
function toString(array: Uint8Array, encoding?: SupportedEncodings): string;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { toString } from "uint8arrays/to-string";
76

77
// UTF-8 decoding (default)
78
const bytes = new Uint8Array([72, 101, 108, 108, 111]);
79
const text = toString(bytes);
80
console.log(text); // "Hello"
81

82
// Hex encoding
83
const hexString = toString(bytes, "hex");
84
console.log(hexString); // "48656c6c6f"
85

86
// Base64 encoding  
87
const base64String = toString(bytes, "base64");
88
console.log(base64String); // "SGVsbG8="
89

90
// ASCII decoding
91
const asciiBytes = new Uint8Array([65, 66, 67]);
92
const asciiText = toString(asciiBytes, "ascii");
93
console.log(asciiText); // "ABC"
94

95
// Unicode handling
96
const unicodeBytes = new Uint8Array([240, 159, 154, 128, 32, 72, 101, 108, 108, 111]);
97
const unicodeText = toString(unicodeBytes, "utf8");
98
console.log(unicodeText); // "🚀 Hello"
99

100
// Different base encodings
101
const base16String = toString(bytes, "base16");
102
const base32String = toString(bytes, "base32");
103
const base58String = toString(bytes, "base58btc");
104
```
105

106
## Supported Encodings
107

108
The `SupportedEncodings` type includes all available encoding formats:
109

110
```typescript { .api }
111
type SupportedEncodings = 
112
  | 'utf8'           // UTF-8 text encoding (default)
113
  | 'utf-8'          // Alias for utf8
114
  | 'hex'            // Hexadecimal encoding
115
  | 'latin1'         // Latin-1 encoding
116
  | 'ascii'          // ASCII encoding (binary-like)
117
  | 'binary'         // Alias for ascii
118
  | 'base2'          // Binary base encoding
119
  | 'base8'          // Octal base encoding  
120
  | 'base10'         // Decimal base encoding
121
  | 'base16'         // Hexadecimal (lowercase)
122
  | 'base16upper'    // Hexadecimal (uppercase)
123
  | 'base32'         // Base32 encoding
124
  | 'base32upper'    // Base32 (uppercase)
125
  | 'base32pad'      // Base32 with padding
126
  | 'base32padupper' // Base32 with padding (uppercase)
127
  | 'base32hex'      // Base32 hex alphabet
128
  | 'base32hexupper' // Base32 hex alphabet (uppercase)
129
  | 'base32hexpad'   // Base32 hex with padding
130
  | 'base32hexpadupper' // Base32 hex with padding (uppercase)
131
  | 'base32z'        // Base32 z-base encoding
132
  | 'base36'         // Base36 encoding
133
  | 'base36upper'    // Base36 (uppercase)
134
  | 'base58btc'      // Base58 Bitcoin alphabet
135
  | 'base58flickr'   // Base58 Flickr alphabet
136
  | 'base64'         // Base64 encoding
137
  | 'base64pad'      // Base64 with padding
138
  | 'base64url'      // Base64 URL-safe encoding
139
  | 'base64urlpad';  // Base64 URL-safe with padding
140
```
141

142
## Common Use Cases
143

144
### Data Serialization
145

146
```typescript
147
import { fromString, toString } from "uint8arrays";
148

149
// JSON data to bytes and back
150
const jsonData = JSON.stringify({ name: "Alice", age: 30 });
151
const jsonBytes = fromString(jsonData, "utf8");
152
const recovered = toString(jsonBytes, "utf8");
153
const parsed = JSON.parse(recovered);
154
```
155

156
### Cryptographic Applications
157

158
```typescript
159
// Hex-encoded hash digests
160
const hashHex = "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3";
161
const hashBytes = fromString(hashHex, "hex");
162

163
// Base64-encoded keys
164
const keyBase64 = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...";
165
const keyBytes = fromString(keyBase64, "base64");
166
```
167

168
### Network Protocols
169

170
```typescript
171
// URL-safe base64 for tokens
172
const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
173
const tokenBytes = fromString(token, "base64url");
174

175
// Multibase for content addressing  
176
const cid = "QmYjtig7VJQ6XsnUjqqJvj7QaMcCAwtrgNdahSiFofrE7o";
177
const cidBytes = fromString(cid, "base58btc");
178
```
179

180
## Platform Optimizations
181

182
- **Node.js**: Uses optimized Buffer encoding methods when available
183
- **Browser**: Uses TextEncoder/TextDecoder for UTF-8, falls back to polyfills
184
- **Multiformats**: Leverages multiformats library for advanced base encodings
185
- **Performance**: Automatic selection of fastest encoding method per platform
186

187
## Error Handling
188

189
Both functions provide clear error handling:
190

191
- **Unsupported Encoding**: Throws Error with descriptive message
192
- **Invalid Input**: Handles malformed strings gracefully where possible
193
- **Unicode**: Proper handling of invalid UTF-8 sequences
194
- **Empty Input**: Handles empty strings and arrays correctly
195

196
```typescript
197
// Error examples
198
try {
199
  fromString("hello", "unsupported" as any);
200
} catch (error) {
201
  console.log(error.message); // 'Unsupported encoding "unsupported"'
202
}
203
```