0
# Core Encoding API
1

2
Synchronous character encoding conversion functions for converting between strings and buffers with different character encodings.
3

4
## Capabilities
5

6
### Encode Function
7

8
Converts a JavaScript string to an encoded Buffer using the specified character encoding.
9

10
```javascript { .api }
11
/**
12
 * Convert string to encoded buffer
13
 * @param content - String to encode (converted to string if not already)
14
 * @param encoding - Target encoding name (case-insensitive)
15
 * @param options - Optional encoding options
16
 * @returns Encoded buffer
17
 */
18
function encode(content, encoding, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const iconv = require('iconv-lite');
25

26
// Basic encoding
27
const buf = iconv.encode("Hello, 世界", 'utf8');
28
console.log(buf); // <Buffer 48 65 6c 6c 6f 2c 20 e4 b8 96 e7 95 8c>
29

30
// Encoding with BOM
31
const bufWithBOM = iconv.encode("Hello", 'utf16le', { addBOM: true });
32

33
// Windows encoding
34
const winBuf = iconv.encode("Café", 'win1252');
35
```
36

37
### Decode Function
38

39
Converts an encoded Buffer to a JavaScript string using the specified character encoding.
40

41
```javascript { .api }
42
/**
43
 * Convert encoded buffer to string
44
 * @param buffer - Buffer or Uint8Array to decode
45
 * @param encoding - Source encoding name (case-insensitive)
46
 * @param options - Optional decoding options
47
 * @returns Decoded string
48
 */
49
function decode(buffer, encoding, options);
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const iconv = require('iconv-lite');
56

57
// Basic decoding
58
const str = iconv.decode(Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]), 'ascii');
59
console.log(str); // "Hello"
60

61
// Decoding with BOM stripping (default behavior)
62
const utf16Str = iconv.decode(utf16Buffer, 'utf16le');
63

64
// Decoding with BOM preservation
65
const strWithBOM = iconv.decode(utf16Buffer, 'utf16le', { stripBOM: false });
66

67
// Multibyte encoding
68
const chineseStr = iconv.decode(gbkBuffer, 'gbk');
69
```
70

71
### Encoding Exists Function
72

73
Checks if a specific character encoding is supported by the library.
74

75
```javascript { .api }
76
/**
77
 * Check if encoding is supported
78
 * @param encoding - Encoding name to check
79
 * @returns True if encoding is supported, false otherwise
80
 */
81
function encodingExists(encoding);
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
const iconv = require('iconv-lite');
88

89
// Check common encodings
90
console.log(iconv.encodingExists('utf8'));        // true
91
console.log(iconv.encodingExists('iso-8859-1'));  // true
92
console.log(iconv.encodingExists('invalid'));     // false
93

94
// Case-insensitive check
95
console.log(iconv.encodingExists('UTF-8'));       // true
96
console.log(iconv.encodingExists('utf8'));        // true
97
```
98

99
### Legacy Aliases
100

101
Legacy function names provided for backward compatibility.
102

103
```javascript { .api }
104
/**
105
 * Legacy alias for encode()
106
 * @deprecated Use encode() instead
107
 */
108
function toEncoding(str, encoding, options);
109

110
/**
111
 * Legacy alias for decode()
112
 * @deprecated Use decode() instead
113
 */
114
function fromEncoding(buf, encoding, options);
115
```
116

117
## Options
118

119
```javascript { .api }
120
/**
121
 * Options for encode/decode functions
122
 */
123
const Options = {
124
  /** Strip BOM (Byte Order Mark) from decoded output (default: true for decode) */
125
  stripBOM,
126
  /** Add BOM to encoded output (default: false) */
127
  addBOM,
128
  /** Default encoding fallback */
129
  defaultEncoding
130
};
131
```
132

133
## Error Handling
134

135
- **Invalid encoding**: Throws `Error` with message "Encoding not recognized: 'ENCODING'"
136
- **Encoding errors**: Replaced with default characters:
137
  - Unicode errors: "�" (U+FFFD)
138
  - Single-byte errors: "?"
139
- **Type conversion**: Non-strings are converted to strings, non-buffers/strings for decode trigger deprecation warning
140

141
## Character Replacement
142

143
When characters cannot be represented in the target encoding, they are replaced with encoding-specific default characters accessible via:
144

145
```javascript { .api }
146
/** Default character for Unicode encoding errors */
147
const defaultCharUnicode; // "�"
148

149
/** Default character for single-byte encoding errors */
150
const defaultCharSingleByte; // "?"
151
```