• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Punycode
2<!-- YAML
3deprecated: v7.0.0
4-->
5
6<!--introduced_in=v0.10.0-->
7
8> Stability: 0 - Deprecated
9
10<!-- source_link=lib/punycode.js -->
11
12**The version of the punycode module bundled in Node.js is being deprecated**.
13In a future major version of Node.js this module will be removed. Users
14currently depending on the `punycode` module should switch to using the
15userland-provided [Punycode.js][] module instead.
16
17The `punycode` module is a bundled version of the [Punycode.js][] module. It
18can be accessed using:
19
20```js
21const punycode = require('punycode');
22```
23
24[Punycode][] is a character encoding scheme defined by RFC 3492 that is
25primarily intended for use in Internationalized Domain Names. Because host
26names in URLs are limited to ASCII characters only, Domain Names that contain
27non-ASCII characters must be converted into ASCII using the Punycode scheme.
28For instance, the Japanese character that translates into the English word,
29`'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent
30to `'example.com'`) is represented by Punycode as the ASCII string
31`'xn--fsq.com'`.
32
33The `punycode` module provides a simple implementation of the Punycode standard.
34
35The `punycode` module is a third-party dependency used by Node.js and
36made available to developers as a convenience. Fixes or other modifications to
37the module must be directed to the [Punycode.js][] project.
38
39## `punycode.decode(string)`
40<!-- YAML
41added: v0.5.1
42-->
43
44* `string` {string}
45
46The `punycode.decode()` method converts a [Punycode][] string of ASCII-only
47characters to the equivalent string of Unicode codepoints.
48
49```js
50punycode.decode('maana-pta'); // 'mañana'
51punycode.decode('--dqo34k'); // '☃-⌘'
52```
53
54## `punycode.encode(string)`
55<!-- YAML
56added: v0.5.1
57-->
58
59* `string` {string}
60
61The `punycode.encode()` method converts a string of Unicode codepoints to a
62[Punycode][] string of ASCII-only characters.
63
64```js
65punycode.encode('mañana'); // 'maana-pta'
66punycode.encode('☃-⌘'); // '--dqo34k'
67```
68
69## `punycode.toASCII(domain)`
70<!-- YAML
71added: v0.6.1
72-->
73
74* `domain` {string}
75
76The `punycode.toASCII()` method converts a Unicode string representing an
77Internationalized Domain Name to [Punycode][]. Only the non-ASCII parts of the
78domain name will be converted. Calling `punycode.toASCII()` on a string that
79already only contains ASCII characters will have no effect.
80
81```js
82// encode domain names
83punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
84punycode.toASCII('☃-⌘.com');   // 'xn----dqo34k.com'
85punycode.toASCII('example.com'); // 'example.com'
86```
87
88## `punycode.toUnicode(domain)`
89<!-- YAML
90added: v0.6.1
91-->
92
93* `domain` {string}
94
95The `punycode.toUnicode()` method converts a string representing a domain name
96containing [Punycode][] encoded characters into Unicode. Only the [Punycode][]
97encoded parts of the domain name are be converted.
98
99```js
100// decode domain names
101punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com'
102punycode.toUnicode('xn----dqo34k.com');  // '☃-⌘.com'
103punycode.toUnicode('example.com');       // 'example.com'
104```
105
106## `punycode.ucs2`
107<!-- YAML
108added: v0.7.0
109-->
110
111### `punycode.ucs2.decode(string)`
112<!-- YAML
113added: v0.7.0
114-->
115
116* `string` {string}
117
118The `punycode.ucs2.decode()` method returns an array containing the numeric
119codepoint values of each Unicode symbol in the string.
120
121```js
122punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63]
123// surrogate pair for U+1D306 tetragram for centre:
124punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306]
125```
126
127### `punycode.ucs2.encode(codePoints)`
128<!-- YAML
129added: v0.7.0
130-->
131
132* `codePoints` {integer[]}
133
134The `punycode.ucs2.encode()` method returns a string based on an array of
135numeric code point values.
136
137```js
138punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc'
139punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06'
140```
141
142## `punycode.version`
143<!-- YAML
144added: v0.6.1
145-->
146
147* {string}
148
149Returns a string identifying the current [Punycode.js][] version number.
150
151[Punycode]: https://tools.ietf.org/html/rfc3492
152[Punycode.js]: https://github.com/bestiejs/punycode.js
153