0
# Core Functionality
1

2
Core number creation, parsing, manipulation, and mathematical operations with built-in precision handling for JavaScript floating-point arithmetic issues.
3

4
## Capabilities
5

6
### Numeral Constructor
7

8
Creates a numeral instance from various input types including numbers, strings, and existing numeral instances.
9

10
```javascript { .api }
11
/**
12
 * Create a numeral instance from various input types
13
 * @param input - Number, string, or existing numeral instance to convert
14
 * @returns New Numeral instance
15
 */
16
function numeral(input: number | string | Numeral | null | undefined): Numeral;
17
```
18

19
**Input Handling:**
20
- Numbers: Direct conversion `numeral(1234.56)`
21
- Strings: Automatic parsing with format detection `numeral('1,234.56')`
22
- Formatted strings: Automatic unformatting `numeral('$1,234.56')`
23
- Numeral instances: Extracts the numeric value `numeral(existingNumeral)`
24
- Zero/null/undefined: Handled according to global zero/null format settings
25

26
**Usage Examples:**
27

28
```javascript
29
const numeral = require('numeral');
30

31
// From numbers
32
const num1 = numeral(1234.56);
33
console.log(num1.value()); // 1234.56
34

35
// From strings
36
const num2 = numeral('1,234.56');
37
console.log(num2.value()); // 1234.56
38

39
// From formatted strings
40
const num3 = numeral('$1,234.56');
41
console.log(num3.value()); // 1234.56
42

43
// From existing numerals
44
const num4 = numeral(num1);
45
console.log(num4.value()); // 1234.56
46

47
// Edge cases
48
console.log(numeral(null).value()); // null
49
console.log(numeral(0).value()); // 0
50
console.log(numeral('not a number').value()); // null
51
```
52

53
### Instance Methods
54

55
#### Value Access and Modification
56

57
```javascript { .api }
58
/**
59
 * Get the numeric value of the numeral instance
60
 * @returns The numeric value or null
61
 */
62
value(): number | null;
63

64
/**
65
 * Get the original input value used to create this instance
66
 * @returns The original input value
67
 */
68
input(): any;
69

70
/**
71
 * Set a new numeric value for this instance
72
 * @param value - New numeric value to set
73
 * @returns This instance for chaining
74
 */
75
set(value: number): Numeral;
76

77
/**
78
 * Create a copy of this numeral instance
79
 * @returns New Numeral instance with the same value
80
 */
81
clone(): Numeral;
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
const num = numeral(1234.56);
88

89
// Get value and input
90
console.log(num.value()); // 1234.56
91
console.log(num.input()); // 1234.56
92

93
// Set new value
94
num.set(9876.54);
95
console.log(num.value()); // 9876.54
96

97
// Clone instance
98
const copy = num.clone();
99
console.log(copy.value()); // 9876.54
100
```
101

102
#### Mathematical Operations
103

104
All mathematical operations handle JavaScript floating-point precision issues automatically and return the instance for method chaining.
105

106
```javascript { .api }
107
/**
108
 * Add a value to the current number with precision handling
109
 * @param value - Number to add
110
 * @returns This instance for chaining
111
 */
112
add(value: number): Numeral;
113

114
/**
115
 * Subtract a value from the current number with precision handling
116
 * @param value - Number to subtract  
117
 * @returns This instance for chaining
118
 */
119
subtract(value: number): Numeral;
120

121
/**
122
 * Multiply the current number by a value with precision handling
123
 * @param value - Number to multiply by
124
 * @returns This instance for chaining
125
 */
126
multiply(value: number): Numeral;
127

128
/**
129
 * Divide the current number by a value with precision handling
130
 * @param value - Number to divide by
131
 * @returns This instance for chaining
132
 */
133
divide(value: number): Numeral;
134

135
/**
136
 * Calculate the absolute difference between current number and a value
137
 * @param value - Number to calculate difference with
138
 * @returns Absolute difference as a regular number (not chainable)
139
 */
140
difference(value: number): number;
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
const numeral = require('numeral');
147

148
// Chained operations
149
const result = numeral(100)
150
    .add(50)          // 150
151
    .multiply(2)      // 300
152
    .subtract(25)     // 275
153
    .divide(5);       // 55
154
console.log(result.value()); // 55
155

156
// Individual operations
157
const num = numeral(10.5);
158
num.add(5.7);
159
console.log(num.value()); // 16.2 (precision handled correctly)
160

161
// Difference calculation
162
const diff = numeral(100).difference(75);
163
console.log(diff); // 25
164
```
165

166
#### Formatting
167

168
```javascript { .api }
169
/**
170
 * Format the number using a format string and optional rounding function
171
 * @param inputString - Format string (optional, uses default if not provided)
172
 * @param roundingFunction - Custom rounding function (optional, uses Math.round)
173
 * @returns Formatted string representation
174
 */
175
format(inputString?: string, roundingFunction?: Function): string;
176
```
177

178
**Basic Format Patterns:**
179
- `'0'` - Integer: `1234` → `"1234"`
180
- `'0.0'` - One decimal: `1234.56` → `"1234.6"`
181
- `'0,0'` - Thousands separator: `1234` → `"1,234"`
182
- `'0,0.00'` - Thousands + two decimals: `1234.56` → `"1,234.56"`
183

184
**Usage Examples:**
185

186
```javascript
187
const num = numeral(1234.567);
188

189
// Basic formatting
190
console.log(num.format('0')); // "1235" (rounded)
191
console.log(num.format('0.0')); // "1234.6"
192
console.log(num.format('0,0')); // "1,235"
193
console.log(num.format('0,0.00')); // "1,234.57"
194

195
// Custom rounding
196
console.log(num.format('0.0', Math.floor)); // "1234.5"
197
console.log(num.format('0.0', Math.ceil)); // "1234.6"
198

199
// Default format (if set)
200
numeral.defaultFormat('0,0.00');
201
console.log(num.format()); // "1,234.57"
202
```
203

204
## Static Methods
205

206
### Instance Identification
207

208
```javascript { .api }
209
/**
210
 * Check if an object is a numeral instance
211
 * @param obj - Object to check
212
 * @returns True if object is a Numeral instance
213
 */
214
numeral.isNumeral(obj: any): boolean;
215
```
216

217
### Version Information
218

219
```javascript { .api }
220
/**
221
 * Library version string
222
 */
223
numeral.version: string; // "2.0.6"
224
```
225

226
### Input Validation
227

228
```javascript { .api }
229
/**
230
 * Validate if a string can be parsed as a number in the given culture
231
 * @param val - String value to validate
232
 * @param culture - Optional culture/locale code for validation context
233
 * @returns True if the string is a valid number format
234
 */
235
numeral.validate(val: string, culture?: string): boolean;
236
```
237

238
**Usage Examples:**
239

240
```javascript
241
// Instance check
242
const num = numeral(123);
243
console.log(numeral.isNumeral(num)); // true
244
console.log(numeral.isNumeral(123)); // false
245

246
// Version
247
console.log(numeral.version); // "2.0.6"
248

249
// Validation
250
console.log(numeral.validate('1,234.56')); // true
251
console.log(numeral.validate('$1,234.56')); // true  
252
console.log(numeral.validate('not a number')); // false
253
console.log(numeral.validate('1.234,56', 'de')); // true (German format)
254
```
255

256
## Configuration Management
257

258
### Global Settings Reset
259

260
```javascript { .api }
261
/**
262
 * Reset all configuration options to their default values
263
 */
264
numeral.reset(): void;
265
```
266

267
### Default Format Configuration
268

269
```javascript { .api }
270
/**
271
 * Set or get the default format string used when no format is specified
272
 * @param format - Format string to set as default
273
 */
274
numeral.defaultFormat(format: string): void;
275
```
276

277
### Zero and Null Formatting
278

279
```javascript { .api }
280
/**
281
 * Set custom format string for zero values
282
 * @param format - Format string for zero values, or null to use default
283
 */
284
numeral.zeroFormat(format?: string | null): void;
285

286
/**
287
 * Set custom format string for null values  
288
 * @param format - Format string for null values, or null to use default
289
 */
290
numeral.nullFormat(format?: string | null): void;
291
```
292

293
**Usage Examples:**
294

295
```javascript
296
// Set custom zero format
297
numeral.zeroFormat('N/A');
298
console.log(numeral(0).format()); // "N/A"
299

300
// Set custom null format
301
numeral.nullFormat('--');
302
console.log(numeral(null).format()); // "--"
303

304
// Set default format
305
numeral.defaultFormat('0,0.00');
306
console.log(numeral(1234.5).format()); // "1,234.50"
307

308
// Reset all settings
309
numeral.reset();
310
console.log(numeral(0).format()); // "0" (back to default)
311
```
312

313
## Access to Internal Systems
314

315
```javascript { .api }
316
/**
317
 * Access to current configuration options
318
 */
319
numeral.options: ConfigOptions;
320

321
/**
322
 * Access to registered format plugins
323
 */
324
numeral.formats: Record<string, FormatPlugin>;
325

326
/**
327
 * Access to registered locales
328
 */
329
numeral.locales: Record<string, LocaleData>;
330

331
/**
332
 * Access to internal utility functions (intended for internal use)
333
 */
334
numeral._: InternalUtilities;
335

336
interface ConfigOptions {
337
  currentLocale: string;
338
  zeroFormat: string | null;
339
  nullFormat: string | null;
340
  defaultFormat: string;
341
  scalePercentBy100: boolean;
342
}
343

344
interface InternalUtilities {
345
  numberToFormat: (value: number, format: string, roundingFunction: Function) => string;
346
  stringToNumber: (string: string) => number | null;
347
  isNaN: (value: any) => boolean;
348
  includes: (string: string, search: string) => boolean;
349
  insert: (string: string, subString: string, start: number) => string;
350
  reduce: (array: any[], callback: Function, initialValue?: any) => any;
351
  multiplier: (x: number) => number;
352
  correctionFactor: (...args: number[]) => number;
353
  toFixed: (value: number, maxDecimals: number, roundingFunction: Function, optionals?: number) => string;
354
}
355
```
356

357
**Usage Examples:**
358

359
```javascript
360
// Check current options
361
console.log(numeral.options.currentLocale); // "en"
362
console.log(numeral.options.defaultFormat); // "0,0"
363

364
// See available formats
365
console.log(Object.keys(numeral.formats)); 
366
// ["bps", "bytes", "currency", "exponential", "ordinal", "percentage", "time"]
367

368
// See available locales  
369
console.log(Object.keys(numeral.locales)); 
370
// ["en", ...] (plus any loaded locales)
371

372
// Internal utilities (not recommended for external use)
373
console.log(typeof numeral._); // "object"
374
console.log(typeof numeral._.numberToFormat); // "function"
375
console.log(typeof numeral._.stringToNumber); // "function"
376
```