0
# lodash.tonumber
1

2
The lodash method `_.toNumber` exported as a standalone Node.js module. This utility provides robust number conversion with support for various input types including strings, booleans, symbols, and objects, with special handling for binary, octal, and hexadecimal string representations.
3

4
## Package Information
5

6
- **Package Name**: lodash.tonumber
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.tonumber`
10

11
## Core Imports
12

13
```javascript
14
const toNumber = require('lodash.tonumber');
15
```
16

17
For ES6 modules (with transpilation):
18

19
```javascript
20
import toNumber from 'lodash.tonumber';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const toNumber = require('lodash.tonumber');
27

28
// Convert various types to numbers
29
console.log(toNumber(3.2));        // => 3.2
30
console.log(toNumber('3.2'));      // => 3.2
31
console.log(toNumber(Number.MIN_VALUE)); // => 5e-324
32
console.log(toNumber(Infinity));   // => Infinity
33

34
// Binary and octal string conversion
35
console.log(toNumber('0b101'));    // => 5
36
console.log(toNumber('0o7'));      // => 7
37

38
// Handles edge cases
39
console.log(toNumber(''));         // => 0
40
console.log(toNumber('  42  '));   // => 42 (trims whitespace)
41
console.log(toNumber(null));       // => 0
42
console.log(toNumber(undefined));  // => NaN
43
console.log(toNumber(Symbol()));   // => NaN
44
```
45

46
## Capabilities
47

48
### Number Conversion
49

50
Converts any value to a number with comprehensive type coercion and parsing.
51

52
```javascript { .api }
53
/**
54
 * Converts `value` to a number.
55
 *
56
 * @param {*} value The value to process.
57
 * @returns {number} Returns the number.
58
 */
59
function toNumber(value);
60
```
61

62
**Type Conversion Behavior:**
63

64
- **Numbers**: Returns the value unchanged
65
- **Strings**: 
66
  - Parses decimal numbers (e.g., "3.14" → 3.14)
67
  - Supports binary strings with "0b" prefix (e.g., "0b101" → 5)
68
  - Supports octal strings with "0o" prefix (e.g., "0o7" → 7)
69
  - Automatically trims leading/trailing whitespace
70
  - Returns NaN for invalid hexadecimal strings with signs
71
- **Booleans**: true → 1, false → 0
72
- **null**: Returns 0
73
- **undefined**: Returns NaN
74
- **Symbols**: Always returns NaN
75
- **Objects**: 
76
  - Calls valueOf() method if available
77
  - Falls back to string conversion if valueOf() returns an object
78
  - Applies string parsing rules to the result
79

80
**Usage Examples:**
81

82
```javascript
83
const toNumber = require('lodash.tonumber');
84

85
// Numeric inputs
86
toNumber(3.2);           // => 3.2
87
toNumber(Number.MAX_VALUE); // => 1.7976931348623157e+308
88
toNumber(-42);           // => -42
89

90
// String inputs
91
toNumber('123');         // => 123
92
toNumber('123.45');      // => 123.45
93
toNumber('0b1010');      // => 10 (binary)
94
toNumber('0o755');       // => 493 (octal)
95
toNumber('0xFF');        // => 255 (hexadecimal)
96
toNumber('-0xFF');       // => NaN (signed hex not supported)
97
toNumber('  42  ');      // => 42 (whitespace trimmed)
98
toNumber('');            // => 0 (empty string)
99
toNumber('abc');         // => NaN (invalid)
100

101
// Boolean inputs
102
toNumber(true);          // => 1
103
toNumber(false);         // => 0
104

105
// Special values
106
toNumber(null);          // => 0
107
toNumber(undefined);     // => NaN
108
toNumber(Symbol('test')); // => NaN
109

110
// Object inputs with valueOf
111
const obj = {
112
  valueOf() { return '42'; }
113
};
114
toNumber(obj);           // => 42
115

116
// Object inputs without valueOf
117
toNumber({});            // => NaN
118
toNumber([]);            // => 0
119
toNumber([42]);          // => 42
120
toNumber([1, 2]);        // => NaN
121
```
122

123
**Error Handling:**
124

125
The function never throws errors but returns `NaN` for values that cannot be converted to valid numbers:
126

127
- Invalid string formats
128
- Signed hexadecimal strings (e.g., "-0xFF", "+0xFF")
129
- Symbol values
130
- Objects that cannot be coerced to numbers
131
- Complex data structures
132

133
**Performance Considerations:**
134

135
- Direct number inputs have optimal performance (immediate return)
136
- String parsing involves regex validation for different number formats
137
- Object coercion may involve method calls (valueOf, toString)
138
- The function uses native `parseInt` for binary and octal conversion