-
Notifications
You must be signed in to change notification settings - Fork 23.3k
Expand file tree
/
Copy pathindex.md
More file actions
81 lines (56 loc) · 2.74 KB
/
Copy pathindex.md
File metadata and controls
81 lines (56 loc) · 2.74 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
---
title: String() constructor
short-title: String()
slug: Web/JavaScript/Reference/Global_Objects/String/String
page-type: javascript-constructor
browser-compat: javascript.builtins.String.String
sidebar: jsref
---
The **`String()`** constructor creates {{jsxref("String")}} objects. When called as a function, it returns primitive values of type String.
## Syntax
```js-nolint
new String(thing)
String(thing)
```
> [!NOTE]
> `String()` can be called with or without [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new), but with different effects. See [Return value](#return_value).
### Parameters
- `thing`
- : Anything to be converted to a string.
### Return value
When `String()` is called as a function (without [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new)), it returns `value` [coerced to a string primitive](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). Specially, [Symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) values are converted to `"Symbol(description)"`, where `description` is the [description](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/description) of the Symbol, instead of throwing.
When `String()` is called as a constructor (with `new`), it coerces `value` to a string primitive (without special symbol handling) and returns a wrapping {{jsxref("String")}} object, which is **not** a primitive.
> [!WARNING]
> You should rarely find yourself using `String` as a constructor.
## Examples
### String constructor and String function
String function and String constructor produce different results:
```js
const a = new String("Hello world"); // a === "Hello world" is false
const b = String("Hello world"); // b === "Hello world" is true
a instanceof String; // is true
b instanceof String; // is false
typeof a; // "object"
typeof b; // "string"
```
Here, the function produces a string (the {{Glossary("primitive")}} type) as promised.
However, the constructor produces an instance of the type String (an object wrapper) and
that's why you rarely want to use the String constructor at all.
### Using String() to stringify a symbol
`String()` is the only case where a symbol can be converted to a string without throwing, because it's very explicit.
```js example-bad
const sym = Symbol("example");
`${sym}`; // TypeError: Cannot convert a Symbol value to a string
"" + sym; // TypeError: Cannot convert a Symbol value to a string
"".concat(sym); // TypeError: Cannot convert a Symbol value to a string
```
```js example-good
const sym = Symbol("example");
String(sym); // "Symbol(example)"
```
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- [Numbers and strings](/en-US/docs/Web/JavaScript/Guide/Numbers_and_strings) guide