Skip to content

Commit 2393750

Browse files
Orthodox-64kgryte
Orthodox-64
and
kgryte
authored
feat: add symbol/to-primitive
PR-URL: #8494 Closes: #8481 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
1 parent 6d3dd75 commit 2393750

File tree

9 files changed

+534
-0
lines changed

9 files changed

+534
-0
lines changed

‎lib/node_modules/@stdlib/symbol/to-primitive/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# ToPrimitiveSymbol
22+
23+
> [Symbol][mdn-symbol] which specifies a method for converting an object to a primitive value.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
41+
```
42+
43+
#### ToPrimitiveSymbol
44+
45+
[Symbol][mdn-symbol] which specifies a method for converting an object to a primitive value.
46+
47+
```javascript
48+
var s = typeof ToPrimitiveSymbol;
49+
// e.g., returns 'symbol'
50+
```
51+
52+
</section>
53+
54+
<!-- /.usage -->
55+
56+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
57+
58+
<section class="notes">
59+
60+
## Notes
61+
62+
- The [symbol][mdn-symbol] is only supported in environments which support [symbols][mdn-symbol]. In non-supporting environments, the value is `null`.
63+
64+
- When an object needs to be converted to a primitive value, JavaScript runtimes look for a `[ToPrimitiveSymbol]()` method on the object. If the method exists, JavaScript runtimes call the method with a `hint` string argument (one of `'number'`, `'string'`, or `'default'`) indicating the preferred type of the primitive value to be returned.
65+
66+
- If the hint is `'number'`, the method should return a number.
67+
- If the hint is `'string'`, the method should return a string.
68+
- If the hint is `'default'`, the method can return either a number or a string.
69+
70+
- If an object does not have a `[ToPrimitiveSymbol]()` method, JavaScript runtimes use the default type conversion algorithm by calling `valueOf()` and/or `toString()` methods.
71+
72+
</section>
73+
74+
<!-- /.notes -->
75+
76+
<!-- Package usage examples. -->
77+
78+
<section class="examples">
79+
80+
## Examples
81+
82+
<!-- eslint-disable no-invalid-this -->
83+
84+
<!-- eslint no-undef: "error" -->
85+
86+
```javascript
87+
var defineProperty = require( '@stdlib/utils/define-property' );
88+
var Number = require( '@stdlib/number/ctor' );
89+
var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
90+
91+
function CustomObject( value ) {
92+
if ( !(this instanceof CustomObject) ) {
93+
return new CustomObject( value );
94+
}
95+
this._value = value;
96+
return this;
97+
}
98+
99+
function toPrimitive( hint ) {
100+
var value = this._value;
101+
if ( hint === 'string' ) {
102+
return 'CustomObject: ' + value;
103+
}
104+
if ( hint === 'number' ) {
105+
return value;
106+
}
107+
// Default hint:
108+
return value;
109+
}
110+
111+
defineProperty( CustomObject.prototype, ToPrimitiveSymbol, {
112+
'configurable': false,
113+
'enumerable': false,
114+
'writable': false,
115+
'value': toPrimitive
116+
});
117+
118+
var obj = new CustomObject( 42 );
119+
120+
console.log( String( obj ) );
121+
// => 'CustomObject: 42'
122+
123+
console.log( Number( obj ) );
124+
// => 42
125+
126+
console.log( obj + 10 );
127+
// => 52
128+
```
129+
130+
</section>
131+
132+
<!-- /.examples -->
133+
134+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
135+
136+
<section class="references">
137+
138+
</section>
139+
140+
<!-- /.references -->
141+
142+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
143+
144+
<section class="related">
145+
146+
</section>
147+
148+
<!-- /.related -->
149+
150+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
151+
152+
<section class="links">
153+
154+
[mdn-symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
155+
156+
</section>
157+
158+
<!-- /.links -->

‎lib/node_modules/@stdlib/symbol/to-primitive/docs/repl.txt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
2+
{{alias}}
3+
Symbol which specifies a method for converting an object to a primitive
4+
value.
5+
6+
The symbol is only supported in ES6/ES2015+ environments. For non-supporting
7+
environments, the value is `null`.
8+
9+
Examples
10+
--------
11+
> var s = {{alias}}
12+
e.g., <symbol>
13+
14+
See Also
15+
--------
16+

‎lib/node_modules/@stdlib/symbol/to-primitive/docs/types/index.d.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 4.1
20+
21+
// EXPORTS //
22+
23+
/**
24+
* Symbol which specifies a method for converting an object to a primitive value.
25+
*
26+
* ## Notes
27+
*
28+
* - The symbol is only supported in ES6/ES2015+ environments. For non-supporting environments, the value is `null`.
29+
*/
30+
export = Symbol.toPrimitive;

‎lib/node_modules/@stdlib/symbol/to-primitive/docs/types/test.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
/* eslint-disable @typescript-eslint/no-unused-expressions */
20+
21+
import ToPrimitive = require( './index' );
22+
23+
24+
// TESTS //
25+
26+
// The exported value is the `toPrimitive` symbol...
27+
{
28+
ToPrimitive;
29+
}

‎lib/node_modules/@stdlib/symbol/to-primitive/examples/index.js‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var Number = require( '@stdlib/number/ctor' );
22+
var defineProperty = require( '@stdlib/utils/define-property' );
23+
var ToPrimitiveSymbol = require( './../lib' );
24+
25+
function CustomObject( value ) {
26+
if ( !(this instanceof CustomObject) ) {
27+
return new CustomObject( value );
28+
}
29+
this._value = value;
30+
return this;
31+
}
32+
33+
/**
34+
* Converts object to a primitive value.
35+
*
36+
* @private
37+
* @param {string} hint - type hint
38+
* @returns {*} primitive value
39+
*/
40+
function toPrimitive( hint ) {
41+
var value = this._value; // eslint-disable-line no-invalid-this
42+
if ( hint === 'string' ) {
43+
return 'CustomObject: ' + value;
44+
}
45+
if ( hint === 'number' ) {
46+
return value;
47+
}
48+
// Default hint:
49+
return value;
50+
}
51+
52+
defineProperty( CustomObject.prototype, ToPrimitiveSymbol, {
53+
'configurable': false,
54+
'enumerable': false,
55+
'writable': false,
56+
'value': toPrimitive
57+
});
58+
59+
var obj = new CustomObject( 42 );
60+
61+
console.log( String( obj ) );
62+
// => 'CustomObject: 42'
63+
64+
console.log( Number( obj ) );
65+
// => 42
66+
67+
console.log( obj + 10 );
68+
// => 52

‎lib/node_modules/@stdlib/symbol/to-primitive/lib/index.js‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
/**
22+
* Symbol which specifies a method for converting an object to a primitive value.
23+
*
24+
* @module @stdlib/symbol/to-primitive
25+
*
26+
* @example
27+
* var Number = require( '@stdlib/number/ctor' );
28+
* var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
29+
*
30+
* function valueOf( hint ) {
31+
* if ( hint === 'string' ) {
32+
* return 'CustomObject';
33+
* }
34+
* if ( hint === 'number' ) {
35+
* return 123;
36+
* }
37+
* return null;
38+
* }
39+
*
40+
* var obj = {};
41+
* obj[ ToPrimitiveSymbol ] = valueOf;
42+
*
43+
* var str = String( obj );
44+
* // returns 'CustomObject'
45+
*
46+
* var num = Number( obj );
47+
* // returns 123
48+
*/
49+
50+
// MODULES //
51+
52+
var main = require( './main.js' );
53+
54+
55+
// EXPORTS //
56+
57+
module.exports = main;

0 commit comments

Comments
 (0)