# ToPrimitiveSymbol
> [Symbol][mdn-symbol] which specifies a method for converting an object to a primitive value.
## Usage
```javascript
var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
```
#### ToPrimitiveSymbol
[Symbol][mdn-symbol] which specifies a method for converting an object to a primitive value.
```javascript
var s = typeof ToPrimitiveSymbol;
// e.g., returns 'symbol'
```
## Notes
- The [symbol][mdn-symbol] is only supported in environments which support [symbols][mdn-symbol]. In non-supporting environments, the value is `null`.
- 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.
- If the hint is `'number'`, the method should return a number.
- If the hint is `'string'`, the method should return a string.
- If the hint is `'default'`, the method can return either a number or a string.
- If an object does not have a `[ToPrimitiveSymbol]()` method, JavaScript runtimes use the default type conversion algorithm by calling `valueOf()` and/or `toString()` methods.
## Examples
```javascript
var defineProperty = require( '@stdlib/utils/define-property' );
var Number = require( '@stdlib/number/ctor' );
var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
function CustomObject( value ) {
if ( !(this instanceof CustomObject) ) {
return new CustomObject( value );
}
this._value = value;
return this;
}
function toPrimitive( hint ) {
var value = this._value;
if ( hint === 'string' ) {
return 'CustomObject: ' + value;
}
if ( hint === 'number' ) {
return value;
}
// Default hint:
return value;
}
defineProperty( CustomObject.prototype, ToPrimitiveSymbol, {
'configurable': false,
'enumerable': false,
'writable': false,
'value': toPrimitive
});
var obj = new CustomObject( 42 );
console.log( String( obj ) );
// => 'CustomObject: 42'
console.log( Number( obj ) );
// => 42
console.log( obj + 10 );
// => 52
```
[mdn-symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol