@pbkware/dot-net-date-number-formatting 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +143 -0
- package/dist/code/datetime-formatter.js +604 -0
- package/dist/code/datetime-formatter.js.map +1 -0
- package/dist/code/datetime-style.js +101 -0
- package/dist/code/datetime-style.js.map +1 -0
- package/dist/code/index.js +6 -0
- package/dist/code/index.js.map +1 -0
- package/dist/code/locale-settings.js +404 -0
- package/dist/code/locale-settings.js.map +1 -0
- package/dist/code/number-formatter.js +916 -0
- package/dist/code/number-formatter.js.map +1 -0
- package/dist/code/number-style.js +211 -0
- package/dist/code/number-style.js.map +1 -0
- package/dist/types/dot-net-date-number-formatting-untrimmed.d.ts +795 -0
- package/dist/types/public-api.d.ts +714 -0
- package/dist/types/tsdoc-metadata.json +11 -0
- package/package.json +63 -0
- package/src/code/datetime-formatter.ts +718 -0
- package/src/code/datetime-style.ts +128 -0
- package/src/code/index.ts +5 -0
- package/src/code/locale-settings.ts +453 -0
- package/src/code/number-formatter.ts +1108 -0
- package/src/code/number-style.ts +247 -0
|
@@ -0,0 +1,714 @@
|
|
|
1
|
+
import { Result } from '@pbkware/js-utils';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Formatter for dates and times using .NET-compatible format strings.
|
|
5
|
+
*
|
|
6
|
+
* Supports both standard format strings (d, D, f, F, g, G, M, O, s, t, T, u, Y) and
|
|
7
|
+
* custom format strings with specific date/time components (yyyy, MM, dd, HH, mm, ss, etc.).
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```typescript
|
|
11
|
+
* const formatter = new DotNetDateTimeFormatter();
|
|
12
|
+
* formatter.localeSettings = DotNetLocaleSettings.createInvariant();
|
|
13
|
+
*
|
|
14
|
+
* // Standard format strings
|
|
15
|
+
* formatter.trySetFormat('d'); // Short date
|
|
16
|
+
* console.log(formatter.toString(new Date(2024, 6, 5))); // "7/5/2024"
|
|
17
|
+
*
|
|
18
|
+
* formatter.trySetFormat('F'); // Full date/time
|
|
19
|
+
* console.log(formatter.toString(new Date(2024, 6, 5, 14, 30, 0)));
|
|
20
|
+
* // "Friday, July 5, 2024 2:30:00 PM"
|
|
21
|
+
*
|
|
22
|
+
* // Custom format strings
|
|
23
|
+
* formatter.trySetFormat('yyyy-MM-dd');
|
|
24
|
+
* console.log(formatter.toString(new Date(2024, 6, 5))); // "2024-07-05"
|
|
25
|
+
*
|
|
26
|
+
* formatter.trySetFormat("dddd, MMMM d 'at' h:mm tt");
|
|
27
|
+
* console.log(formatter.toString(new Date(2024, 6, 5, 14, 30, 0)));
|
|
28
|
+
* // "Friday, July 5 at 2:30 PM"
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* @public
|
|
32
|
+
* @category DateTime Formatting
|
|
33
|
+
*/
|
|
34
|
+
export declare class DotNetDateTimeFormatter {
|
|
35
|
+
/**
|
|
36
|
+
* Set of date/time style flags that are not currently supported by this implementation.
|
|
37
|
+
* Operations using these styles will fail.
|
|
38
|
+
*/
|
|
39
|
+
static readonly unsupportedStyles: Set<DotNetDateTimeStyleId>;
|
|
40
|
+
private format;
|
|
41
|
+
/**
|
|
42
|
+
* The set of {@link DotNetDateTimeStyleId} flags that control date/time parsing behavior.
|
|
43
|
+
* Currently only used for future parsing functionality.
|
|
44
|
+
*/
|
|
45
|
+
styles: DotNetDateTimeStyleSet;
|
|
46
|
+
/**
|
|
47
|
+
* The locale settings that determine date/time separators and formatting conventions.
|
|
48
|
+
*/
|
|
49
|
+
localeSettings: DotNetLocaleSettings;
|
|
50
|
+
private formatIsStandard;
|
|
51
|
+
private elements;
|
|
52
|
+
/**
|
|
53
|
+
* Contains the error message from the last failed operation.
|
|
54
|
+
* Check this property if {@link DotNetDateTimeFormatter.trySetFormat} returns an error.
|
|
55
|
+
*/
|
|
56
|
+
parseErrorText: string;
|
|
57
|
+
/**
|
|
58
|
+
* Sets the format string to use for formatting dates and times.
|
|
59
|
+
*
|
|
60
|
+
* The format string is tokenized to confirm validity and to optimize formatting/parsing operations.
|
|
61
|
+
*
|
|
62
|
+
* @param value - A standard format string (single character like 'd', 'F', 'o') or
|
|
63
|
+
* custom format string (e.g., "yyyy-MM-dd HH:mm:ss").
|
|
64
|
+
* @returns A Result indicating success or containing an error message if the format string is invalid.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* ```typescript
|
|
68
|
+
* // Standard format
|
|
69
|
+
* formatter.trySetFormat('d'); // Short date
|
|
70
|
+
*
|
|
71
|
+
* // Custom format
|
|
72
|
+
* formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
|
|
73
|
+
*
|
|
74
|
+
* // Check for errors
|
|
75
|
+
* const result = formatter.trySetFormat('');
|
|
76
|
+
* if (result.isErr()) {
|
|
77
|
+
* console.error(result.error); // "Format text cannot be empty"
|
|
78
|
+
* }
|
|
79
|
+
* ```
|
|
80
|
+
*/
|
|
81
|
+
trySetFormat(value: string): Result<void>;
|
|
82
|
+
/**
|
|
83
|
+
* Formats a Date using the current format string.
|
|
84
|
+
*
|
|
85
|
+
* @param value - The Date to format.
|
|
86
|
+
* @returns The formatted date/time string.
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* ```typescript
|
|
90
|
+
* const date = new Date(2024, 6, 5, 14, 30, 45);
|
|
91
|
+
*
|
|
92
|
+
* formatter.trySetFormat('d');
|
|
93
|
+
* console.log(formatter.toString(date)); // "7/5/2024"
|
|
94
|
+
*
|
|
95
|
+
* formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
|
|
96
|
+
* console.log(formatter.toString(date)); // "2024-07-05 14:30:45"
|
|
97
|
+
* ```
|
|
98
|
+
*/
|
|
99
|
+
toString(value: Date): string;
|
|
100
|
+
tryFromString(strValue: string): Result<Date>;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Individual style flags that control date/time parsing behavior.
|
|
105
|
+
*
|
|
106
|
+
* These flags can be combined to create custom parsing rules.
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```typescript
|
|
110
|
+
* // Combine individual flags
|
|
111
|
+
* formatter.styles = new Set([
|
|
112
|
+
* DotNetDateTimeStyleId.AllowLeadingWhite,
|
|
113
|
+
* DotNetDateTimeStyleId.AllowTrailingWhite
|
|
114
|
+
* ]);
|
|
115
|
+
* ```
|
|
116
|
+
*
|
|
117
|
+
* @public
|
|
118
|
+
* @category DateTime Styles
|
|
119
|
+
*/
|
|
120
|
+
export declare enum DotNetDateTimeStyleId {
|
|
121
|
+
/** Allow leading whitespace characters. */
|
|
122
|
+
AllowLeadingWhite = "AllowLeadingWhite",
|
|
123
|
+
/** Allow trailing whitespace characters. */
|
|
124
|
+
AllowTrailingWhite = "AllowTrailingWhite",
|
|
125
|
+
/** Allow whitespace within the date/time string. */
|
|
126
|
+
AllowInnerWhite = "AllowInnerWhite",
|
|
127
|
+
/** Do not use current date for missing date components. */
|
|
128
|
+
NoCurrentDateDefault = "NoCurrentDateDefault",
|
|
129
|
+
/** Adjust date/time to UTC (not implemented). */
|
|
130
|
+
AdjustToUniversal = "AdjustToUniversal",
|
|
131
|
+
/** Assume local time zone if not specified (not implemented). */
|
|
132
|
+
AssumeLocal = "AssumeLocal",
|
|
133
|
+
/** Assume UTC time zone if not specified (not implemented). */
|
|
134
|
+
AssumeUniversal = "AssumeUniversal",
|
|
135
|
+
/** Preserve DateTimeKind when parsing (not implemented). */
|
|
136
|
+
RoundTripKind = "RoundTripKind"
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/* Excluded from this release type: DotNetDateTimeStyles */
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A set of {@link DotNetDateTimeStyleId} flags.
|
|
143
|
+
*
|
|
144
|
+
* @public
|
|
145
|
+
* @category DateTime Styles
|
|
146
|
+
*/
|
|
147
|
+
export declare type DotNetDateTimeStyleSet = Set<DotNetDateTimeStyleId>;
|
|
148
|
+
|
|
149
|
+
/* Excluded from this release type: DotNetDateTimeStylesInfo */
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Formatter for decimal numbers with high precision using .NET-compatible format strings.
|
|
153
|
+
*
|
|
154
|
+
* Similar to {@link DotNetFloatFormatter} but with different default precision behavior.
|
|
155
|
+
* When no format is specified, trailing zeros after the decimal point are automatically trimmed.
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```typescript
|
|
159
|
+
* const formatter = new DotNetDecimalFormatter();
|
|
160
|
+
* formatter.localeSettings = DotNetLocaleSettings.createInvariant();
|
|
161
|
+
*
|
|
162
|
+
* // High precision formatting
|
|
163
|
+
* formatter.trySetFormat('F6');
|
|
164
|
+
* console.log(formatter.toString(123.456)); // "123.456000"
|
|
165
|
+
*
|
|
166
|
+
* // Default behavior (trims trailing zeros)
|
|
167
|
+
* console.log(formatter.toString(123.400)); // "123.4"
|
|
168
|
+
* ```
|
|
169
|
+
*
|
|
170
|
+
* @public
|
|
171
|
+
* @category Numeric Formatting
|
|
172
|
+
*/
|
|
173
|
+
export declare class DotNetDecimalFormatter extends DotNetNumberFormatter {
|
|
174
|
+
/**
|
|
175
|
+
* Formats a number using the current format string.
|
|
176
|
+
* When no format is specified, trailing zeros are trimmed.
|
|
177
|
+
*
|
|
178
|
+
* @param value - The number to format.
|
|
179
|
+
* @returns The formatted number string.
|
|
180
|
+
*/
|
|
181
|
+
toString(value: number): string;
|
|
182
|
+
/**
|
|
183
|
+
* Attempts to parse a number from a string using the current parsing styles.
|
|
184
|
+
*
|
|
185
|
+
* @param strValue - The string to parse.
|
|
186
|
+
* @returns A Result containing the parsed number if successful, or an error if parsing fails.
|
|
187
|
+
*/
|
|
188
|
+
tryFromString(strValue: string): Result<number>;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Formatter for floating-point numbers using .NET-compatible format strings.
|
|
193
|
+
*
|
|
194
|
+
* Supports all standard numeric format strings (C, D, E, F, G, N, P, R, X, B) and
|
|
195
|
+
* custom format strings with digit placeholders, separators, and sections.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* ```typescript
|
|
199
|
+
* const formatter = new DotNetFloatFormatter();
|
|
200
|
+
* formatter.localeSettings = DotNetLocaleSettings.createInvariant();
|
|
201
|
+
*
|
|
202
|
+
* // Currency format
|
|
203
|
+
* formatter.trySetFormat('C2');
|
|
204
|
+
* console.log(formatter.toString(1234.56)); // "$1,234.56"
|
|
205
|
+
*
|
|
206
|
+
* // Percentage format
|
|
207
|
+
* formatter.trySetFormat('P1');
|
|
208
|
+
* console.log(formatter.toString(0.1234)); // "12.3%"
|
|
209
|
+
*
|
|
210
|
+
* // Custom format with sections
|
|
211
|
+
* formatter.trySetFormat('#,##0.00;(#,##0.00)');
|
|
212
|
+
* console.log(formatter.toString(-1234.56)); // "(1,234.56)"
|
|
213
|
+
*
|
|
214
|
+
* // Parsing
|
|
215
|
+
* formatter.styles = DotNetNumberStyles.number;
|
|
216
|
+
* const result = formatter.tryFromString('1,234.56');
|
|
217
|
+
* if (result.isOk()) {
|
|
218
|
+
* console.log(result.value); // 1234.56
|
|
219
|
+
* }
|
|
220
|
+
* ```
|
|
221
|
+
*
|
|
222
|
+
* @public
|
|
223
|
+
* @category Numeric Formatting
|
|
224
|
+
*/
|
|
225
|
+
export declare class DotNetFloatFormatter extends DotNetNumberFormatter {
|
|
226
|
+
/**
|
|
227
|
+
* Formats a number using the current format string.
|
|
228
|
+
*
|
|
229
|
+
* @param value - The number to format.
|
|
230
|
+
* @returns The formatted number string.
|
|
231
|
+
*/
|
|
232
|
+
toString(value: number): string;
|
|
233
|
+
/**
|
|
234
|
+
* Attempts to parse a number from a string using the current parsing styles.
|
|
235
|
+
*
|
|
236
|
+
* @param strValue - The string to parse.
|
|
237
|
+
* @returns A Result containing the parsed number if successful, or an error if parsing fails.
|
|
238
|
+
*
|
|
239
|
+
* @example
|
|
240
|
+
* ```typescript
|
|
241
|
+
* formatter.styles = DotNetNumberStyles.number;
|
|
242
|
+
* const result = formatter.tryFromString(' 1,234.56 ');
|
|
243
|
+
* if (result.isOk()) {
|
|
244
|
+
* console.log(result.value); // 1234.56
|
|
245
|
+
* }
|
|
246
|
+
* ```
|
|
247
|
+
*/
|
|
248
|
+
tryFromString(strValue: string): Result<number>;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* Formatter for integer values (bigint) using .NET-compatible format strings.
|
|
253
|
+
*
|
|
254
|
+
* Supports formatting integers with standard format strings like D (decimal), X (hexadecimal),
|
|
255
|
+
* B (binary), and custom format strings.
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* ```typescript
|
|
259
|
+
* const formatter = new DotNetIntegerFormatter();
|
|
260
|
+
* formatter.localeSettings = DotNetLocaleSettings.createInvariant();
|
|
261
|
+
*
|
|
262
|
+
* // Decimal with padding
|
|
263
|
+
* formatter.trySetFormat('D8');
|
|
264
|
+
* console.log(formatter.toString(123n)); // "00000123"
|
|
265
|
+
*
|
|
266
|
+
* // Hexadecimal
|
|
267
|
+
* formatter.trySetFormat('X');
|
|
268
|
+
* console.log(formatter.toString(255n)); // "FF"
|
|
269
|
+
*
|
|
270
|
+
* // Parsing
|
|
271
|
+
* formatter.styles = DotNetNumberStyles.integer;
|
|
272
|
+
* const result = formatter.tryFromString('-12345');
|
|
273
|
+
* if (result.isOk()) {
|
|
274
|
+
* console.log(result.value); // -12345n
|
|
275
|
+
* }
|
|
276
|
+
* ```
|
|
277
|
+
*
|
|
278
|
+
* @public
|
|
279
|
+
* @category Numeric Formatting
|
|
280
|
+
*/
|
|
281
|
+
export declare class DotNetIntegerFormatter extends DotNetNumberFormatter {
|
|
282
|
+
/**
|
|
283
|
+
* Formats a bigint value using the current format string.
|
|
284
|
+
*
|
|
285
|
+
* @param value - The bigint value to format.
|
|
286
|
+
* @returns The formatted number string.
|
|
287
|
+
*/
|
|
288
|
+
toString(value: bigint): string;
|
|
289
|
+
/**
|
|
290
|
+
* Attempts to parse a bigint value from a string using the current parsing styles.
|
|
291
|
+
*
|
|
292
|
+
* @param strValue - The string to parse.
|
|
293
|
+
* @returns A Result containing the parsed bigint if successful, or an error if parsing fails.
|
|
294
|
+
*
|
|
295
|
+
* @example
|
|
296
|
+
* ```typescript
|
|
297
|
+
* formatter.styles = DotNetNumberStyles.integer;
|
|
298
|
+
* const result = formatter.tryFromString(' -123 ');
|
|
299
|
+
* if (result.isOk()) {
|
|
300
|
+
* console.log(result.value); // -123n
|
|
301
|
+
* }
|
|
302
|
+
* ```
|
|
303
|
+
*/
|
|
304
|
+
tryFromString(strValue: string): Result<bigint>;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Represents locale-specific formatting settings for dates, times, and numbers.
|
|
309
|
+
*
|
|
310
|
+
* Provides culture-specific separators and formatting options that determine how
|
|
311
|
+
* numbers, currencies, dates, and times are formatted and parsed.
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* ```typescript
|
|
315
|
+
* // Use invariant culture (en-US)
|
|
316
|
+
* const invariant = DotNetLocaleSettings.createInvariant();
|
|
317
|
+
*
|
|
318
|
+
* // Use specific locale
|
|
319
|
+
* const french = DotNetLocaleSettings.create('fr-FR');
|
|
320
|
+
* console.log(french.decimalSeparator); // ","
|
|
321
|
+
* console.log(french.thousandSeparator); // " "
|
|
322
|
+
*
|
|
323
|
+
* // Use current system locale
|
|
324
|
+
* const current = DotNetLocaleSettings.current;
|
|
325
|
+
* ```
|
|
326
|
+
*
|
|
327
|
+
* @public
|
|
328
|
+
* @category Locale Settings
|
|
329
|
+
*/
|
|
330
|
+
export declare class DotNetLocaleSettings {
|
|
331
|
+
/**
|
|
332
|
+
* Singleton instance for invariant culture (en-US).
|
|
333
|
+
* Provides consistent formatting across all systems.
|
|
334
|
+
*/
|
|
335
|
+
static readonly invariant: DotNetLocaleSettings;
|
|
336
|
+
/**
|
|
337
|
+
* Singleton instance for current system locale.
|
|
338
|
+
* Uses the locale settings from the runtime environment.
|
|
339
|
+
*/
|
|
340
|
+
static readonly current: DotNetLocaleSettings;
|
|
341
|
+
/** The locale identifier (same as name). */
|
|
342
|
+
readonly id: string;
|
|
343
|
+
/** The locale name (e.g., "en-US", "fr-FR"). */
|
|
344
|
+
readonly name: string;
|
|
345
|
+
/** Character used for decimal point (e.g., "." or ","). */
|
|
346
|
+
readonly decimalSeparator: string;
|
|
347
|
+
/** Character used for thousands grouping (e.g., "," or "." or " "). */
|
|
348
|
+
readonly thousandSeparator: string;
|
|
349
|
+
/** Currency symbol for this locale (e.g., "$", "€", "£"). */
|
|
350
|
+
readonly currencyString: string;
|
|
351
|
+
/** Character used between date components (e.g., "/", "-", "."). */
|
|
352
|
+
readonly dateSeparator: string;
|
|
353
|
+
/** Character used between time components (typically ":"). */
|
|
354
|
+
readonly timeSeparator: string;
|
|
355
|
+
/** Pre-configured number formatter for floating-point values. */
|
|
356
|
+
readonly defaultFloat: Intl.NumberFormat;
|
|
357
|
+
/** Pre-configured number formatter for high-precision decimal values. */
|
|
358
|
+
readonly defaultDecimal: Intl.NumberFormat;
|
|
359
|
+
/** Pre-configured number formatter for currency values. */
|
|
360
|
+
readonly defaultCurrency: Intl.NumberFormat;
|
|
361
|
+
/**
|
|
362
|
+
* Creates a new DotNetLocaleSettings instance.
|
|
363
|
+
*
|
|
364
|
+
* @param localeName - Optional locale name (e.g., "en-US", "fr-FR").
|
|
365
|
+
* If undefined, uses the system's current locale.
|
|
366
|
+
*
|
|
367
|
+
* @example
|
|
368
|
+
* ```typescript
|
|
369
|
+
* // System locale
|
|
370
|
+
* const settings = new DotNetLocaleSettings(undefined);
|
|
371
|
+
*
|
|
372
|
+
* // Specific locale
|
|
373
|
+
* const french = new DotNetLocaleSettings('fr-FR');
|
|
374
|
+
* ```
|
|
375
|
+
*/
|
|
376
|
+
constructor(localeName?: string);
|
|
377
|
+
/**
|
|
378
|
+
* Creates a DotNetLocaleSettings instance for the specified locale.
|
|
379
|
+
*
|
|
380
|
+
* @param localeName - The locale name (e.g., "en-US", "fr-FR", "de-DE").
|
|
381
|
+
* @returns A new DotNetLocaleSettings instance configured for the specified locale.
|
|
382
|
+
*
|
|
383
|
+
* @example
|
|
384
|
+
* ```typescript
|
|
385
|
+
* const usSettings = DotNetLocaleSettings.create('en-US');
|
|
386
|
+
* const frSettings = DotNetLocaleSettings.create('fr-FR');
|
|
387
|
+
* ```
|
|
388
|
+
*/
|
|
389
|
+
static create(localeName: string): DotNetLocaleSettings;
|
|
390
|
+
/**
|
|
391
|
+
* Creates a DotNetLocaleSettings instance for the invariant culture (en-US).
|
|
392
|
+
* The invariant culture provides consistent formatting across all systems.
|
|
393
|
+
*
|
|
394
|
+
* @returns A new DotNetLocaleSettings instance configured for invariant culture.
|
|
395
|
+
*
|
|
396
|
+
* @example
|
|
397
|
+
* ```typescript
|
|
398
|
+
* const settings = DotNetLocaleSettings.createInvariant();
|
|
399
|
+
* console.log(settings.decimalSeparator); // "."
|
|
400
|
+
* console.log(settings.thousandSeparator); // ","
|
|
401
|
+
* ```
|
|
402
|
+
*/
|
|
403
|
+
static createInvariant(): DotNetLocaleSettings;
|
|
404
|
+
/**
|
|
405
|
+
* Converts a number or bigint to a string using locale-specific formatting.
|
|
406
|
+
*
|
|
407
|
+
* @param value - The number or bigint to format.
|
|
408
|
+
* @param options - Optional Intl.NumberFormatOptions for custom formatting.
|
|
409
|
+
* @returns The formatted number string.
|
|
410
|
+
*
|
|
411
|
+
* @example
|
|
412
|
+
* ```typescript
|
|
413
|
+
* const settings = DotNetLocaleSettings.create('en-US');
|
|
414
|
+
* settings.numberToStr(1234.56); // "1,234.56"
|
|
415
|
+
* settings.numberToStr(1234.56, { minimumFractionDigits: 2 }); // "1,234.56"
|
|
416
|
+
* ```
|
|
417
|
+
*/
|
|
418
|
+
numberToStr(value: number | bigint, options?: Intl.NumberFormatOptions): string;
|
|
419
|
+
/**
|
|
420
|
+
* Converts a Date to a string using locale-specific formatting.
|
|
421
|
+
*
|
|
422
|
+
* @param value - The Date to format.
|
|
423
|
+
* @param options - Optional Intl.DateTimeFormatOptions for custom formatting.
|
|
424
|
+
* @returns The formatted date string.
|
|
425
|
+
*
|
|
426
|
+
* @example
|
|
427
|
+
* ```typescript
|
|
428
|
+
* const settings = DotNetLocaleSettings.create('en-US');
|
|
429
|
+
* settings.dateToStr(new Date(2024, 6, 5), { dateStyle: 'short' }); // "7/5/2024"
|
|
430
|
+
* ```
|
|
431
|
+
*/
|
|
432
|
+
dateToStr(value: Date, options?: Intl.DateTimeFormatOptions): string;
|
|
433
|
+
/**
|
|
434
|
+
* Converts a boolean to a string.
|
|
435
|
+
*
|
|
436
|
+
* @param value - The boolean value.
|
|
437
|
+
* @returns "true" or "false".
|
|
438
|
+
*
|
|
439
|
+
* @example
|
|
440
|
+
* ```typescript
|
|
441
|
+
* settings.boolToStr(true); // "true"
|
|
442
|
+
* settings.boolToStr(false); // "false"
|
|
443
|
+
* ```
|
|
444
|
+
*/
|
|
445
|
+
boolToStr(value: boolean): string;
|
|
446
|
+
/**
|
|
447
|
+
* Attempts to parse a boolean value from a string.
|
|
448
|
+
*
|
|
449
|
+
* @param value - The string to parse. Accepts: "true", "1", "yes" (case-insensitive) for true,
|
|
450
|
+
* and "false", "0", "no" for false.
|
|
451
|
+
* @returns A Result containing the boolean value if successful, or an error if parsing fails.
|
|
452
|
+
*
|
|
453
|
+
* @example
|
|
454
|
+
* ```typescript
|
|
455
|
+
* settings.tryStrToBool('yes'); // Ok(true)
|
|
456
|
+
* settings.tryStrToBool('false'); // Ok(false)
|
|
457
|
+
* settings.tryStrToBool('invalid'); // Err("Invalid boolean string")
|
|
458
|
+
* ```
|
|
459
|
+
*/
|
|
460
|
+
tryStrToBool(value: string): Result<boolean>;
|
|
461
|
+
/**
|
|
462
|
+
* Attempts to parse an integer from a string.
|
|
463
|
+
*
|
|
464
|
+
* @param value - The string to parse. Must contain only digits and an optional leading +/- sign.
|
|
465
|
+
* @returns A Result containing the parsed integer if successful, or an error if parsing fails.
|
|
466
|
+
*
|
|
467
|
+
* @example
|
|
468
|
+
* ```typescript
|
|
469
|
+
* settings.tryStrToInt('123'); // Ok(123)
|
|
470
|
+
* settings.tryStrToInt('-456'); // Ok(-456)
|
|
471
|
+
* settings.tryStrToInt('12.34'); // Err("Invalid integer string")
|
|
472
|
+
* ```
|
|
473
|
+
*/
|
|
474
|
+
tryStrToInt(value: string): Result<number>;
|
|
475
|
+
/**
|
|
476
|
+
* Attempts to parse a BigInt from a string.
|
|
477
|
+
*
|
|
478
|
+
* @param value - The string to parse. Must contain only digits and an optional leading +/- sign.
|
|
479
|
+
* @returns A Result containing the parsed BigInt if successful, or an error if parsing fails.
|
|
480
|
+
*
|
|
481
|
+
* @example
|
|
482
|
+
* ```typescript
|
|
483
|
+
* settings.tryStrToBigInt('12345678901234567890'); // Ok(12345678901234567890n)
|
|
484
|
+
* settings.tryStrToBigInt('-999'); // Ok(-999n)
|
|
485
|
+
* ```
|
|
486
|
+
*/
|
|
487
|
+
tryStrToBigInt(value: string): Result<bigint>;
|
|
488
|
+
/**
|
|
489
|
+
* Attempts to parse a number from a string using locale-specific formatting.
|
|
490
|
+
* Handles currency symbols, thousands separators, and locale-specific decimal separators.
|
|
491
|
+
*
|
|
492
|
+
* @param value - The string to parse.
|
|
493
|
+
* @returns A Result containing the parsed number if successful, or an error if parsing fails.
|
|
494
|
+
*
|
|
495
|
+
* @example
|
|
496
|
+
* ```typescript
|
|
497
|
+
* const usSettings = DotNetLocaleSettings.create('en-US');
|
|
498
|
+
* usSettings.tryStrToNumber('1,234.56'); // Ok(1234.56)
|
|
499
|
+
* usSettings.tryStrToNumber('$1,234.56'); // Ok(1234.56)
|
|
500
|
+
*
|
|
501
|
+
* const frSettings = DotNetLocaleSettings.create('fr-FR');
|
|
502
|
+
* frSettings.tryStrToNumber('1 234,56'); // Ok(1234.56)
|
|
503
|
+
* ```
|
|
504
|
+
*/
|
|
505
|
+
tryStrToNumber(value: string): Result<number>;
|
|
506
|
+
/**
|
|
507
|
+
* Attempts to parse a Date from a string.
|
|
508
|
+
*
|
|
509
|
+
* @param value - The string to parse. Accepts various date formats understood by JavaScript Date constructor.
|
|
510
|
+
* @returns A Result containing the parsed Date if successful, or an error if parsing fails.
|
|
511
|
+
*
|
|
512
|
+
* @example
|
|
513
|
+
* ```typescript
|
|
514
|
+
* settings.tryStrToDate('2024-07-05'); // Ok(Date)
|
|
515
|
+
* settings.tryStrToDate('July 5, 2024'); // Ok(Date)
|
|
516
|
+
* settings.tryStrToDate('invalid'); // Err("Invalid date string")
|
|
517
|
+
* ```
|
|
518
|
+
*/
|
|
519
|
+
tryStrToDate(value: string): Result<Date>;
|
|
520
|
+
/**
|
|
521
|
+
* Convert a single character to uppercase using culture-specific rules.
|
|
522
|
+
* Handles special cases like Turkish 'i' → 'İ' vs standard 'i' → 'I'.
|
|
523
|
+
*
|
|
524
|
+
* @param char - The character to convert to uppercase.
|
|
525
|
+
* @returns The uppercased character.
|
|
526
|
+
*
|
|
527
|
+
* @example
|
|
528
|
+
* ```typescript
|
|
529
|
+
* const usSettings = DotNetLocaleSettings.create('en-US');
|
|
530
|
+
* usSettings.toUpperChar('i'); // "I"
|
|
531
|
+
*
|
|
532
|
+
* const trSettings = DotNetLocaleSettings.create('tr-TR');
|
|
533
|
+
* trSettings.toUpperChar('i'); // "İ" (Turkish dotted I)
|
|
534
|
+
* ```
|
|
535
|
+
*/
|
|
536
|
+
toUpperChar(char: string): string;
|
|
537
|
+
/**
|
|
538
|
+
* Convert a single character to lowercase using culture-specific rules.
|
|
539
|
+
* Handles special cases like Turkish 'I' → 'ı' vs Turkish 'İ' → 'i'.
|
|
540
|
+
*
|
|
541
|
+
* @param char - The character to convert to lowercase.
|
|
542
|
+
* @returns The lowercased character.
|
|
543
|
+
*
|
|
544
|
+
* @example
|
|
545
|
+
* ```typescript
|
|
546
|
+
* const usSettings = DotNetLocaleSettings.create('en-US');
|
|
547
|
+
* usSettings.toLowerChar('I'); // "i"
|
|
548
|
+
*
|
|
549
|
+
* const trSettings = DotNetLocaleSettings.create('tr-TR');
|
|
550
|
+
* trSettings.toLowerChar('I'); // "ı" (Turkish dotless i)
|
|
551
|
+
* trSettings.toLowerChar('İ'); // "i" (Turkish dotted i)
|
|
552
|
+
* ```
|
|
553
|
+
*/
|
|
554
|
+
toLowerChar(char: string): string;
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
/**
|
|
558
|
+
* Base class for formatting and parsing numbers using .NET-compatible format strings.
|
|
559
|
+
*
|
|
560
|
+
* Supports both standard format strings (C, D, E, F, G, N, P, R, X, B) and custom format strings
|
|
561
|
+
* with fine-grained control over digit placeholders, separators, and sections.
|
|
562
|
+
*
|
|
563
|
+
* @remarks
|
|
564
|
+
* This is a base class - use {@link DotNetIntegerFormatter}, {@link DotNetFloatFormatter},
|
|
565
|
+
* or {@link DotNetDecimalFormatter} for specific number types.
|
|
566
|
+
*
|
|
567
|
+
* @example
|
|
568
|
+
* ```typescript
|
|
569
|
+
* // Use derived classes instead
|
|
570
|
+
* const formatter = new DotNetFloatFormatter();
|
|
571
|
+
* formatter.localeSettings = DotNetLocaleSettings.createInvariant();
|
|
572
|
+
* formatter.trySetFormat('C2');
|
|
573
|
+
* console.log(formatter.toString(1234.56)); // "$1,234.56"
|
|
574
|
+
* ```
|
|
575
|
+
*
|
|
576
|
+
* @public
|
|
577
|
+
* @category Numeric Formatting
|
|
578
|
+
*/
|
|
579
|
+
export declare class DotNetNumberFormatter {
|
|
580
|
+
protected format: string;
|
|
581
|
+
private formatIsStandard;
|
|
582
|
+
private precision;
|
|
583
|
+
private sections;
|
|
584
|
+
/**
|
|
585
|
+
* The set of {@link DotNetNumberStyleId} flags that control which number formats are allowed during parsing.
|
|
586
|
+
*
|
|
587
|
+
* @example
|
|
588
|
+
* ```typescript
|
|
589
|
+
* // Use predefined styles
|
|
590
|
+
* formatter.styles = DotNetNumberStyles.number;
|
|
591
|
+
*
|
|
592
|
+
* // Or combine individual flags
|
|
593
|
+
* formatter.styles = new Set([
|
|
594
|
+
* DotNetNumberStyleId.AllowLeadingSign,
|
|
595
|
+
* DotNetNumberStyleId.AllowDecimalPoint
|
|
596
|
+
* ]);
|
|
597
|
+
* ```
|
|
598
|
+
*/
|
|
599
|
+
styles: DotNetNumberStyleSet;
|
|
600
|
+
/**
|
|
601
|
+
* The locale settings that determine decimal/thousands separators and other culture-specific formatting.
|
|
602
|
+
*/
|
|
603
|
+
localeSettings: DotNetLocaleSettings;
|
|
604
|
+
/**
|
|
605
|
+
* Contains the error message from the last failed operation.
|
|
606
|
+
* Check this property if {@link DotNetNumberFormatter.trySetFormat} or parsing methods return an error.
|
|
607
|
+
*/
|
|
608
|
+
parseErrorText: string;
|
|
609
|
+
protected setParseErrorText(value: string): false;
|
|
610
|
+
/**
|
|
611
|
+
* Sets the format string to use for formatting numbers.
|
|
612
|
+
*
|
|
613
|
+
* The format string is tokenized to confirm validity and to optimize formatting/parsing operations.
|
|
614
|
+
*
|
|
615
|
+
* @param value - A standard format string (e.g., "C", "N2", "E3") or custom format string (e.g., "#,##0.00").
|
|
616
|
+
* @returns A Result indicating success or containing an error message if the format string is invalid.
|
|
617
|
+
*
|
|
618
|
+
* @example
|
|
619
|
+
* ```typescript
|
|
620
|
+
* // Standard format
|
|
621
|
+
* formatter.trySetFormat('C2'); // Currency with 2 decimal places
|
|
622
|
+
*
|
|
623
|
+
* // Custom format
|
|
624
|
+
* formatter.trySetFormat('#,##0.00'); // Number with thousands separator
|
|
625
|
+
*
|
|
626
|
+
* // Check for errors
|
|
627
|
+
* const result = formatter.trySetFormat('INVALID');
|
|
628
|
+
* if (result.isErr()) {
|
|
629
|
+
* console.error(result.error);
|
|
630
|
+
* }
|
|
631
|
+
* ```
|
|
632
|
+
*/
|
|
633
|
+
trySetFormat(value: string): Result<void>;
|
|
634
|
+
private parseCustomFormat;
|
|
635
|
+
private analyzeSection;
|
|
636
|
+
protected formatNumber(value: number | bigint, allowDecimal?: boolean): string;
|
|
637
|
+
private formatStandard;
|
|
638
|
+
private formatCurrency;
|
|
639
|
+
private formatDecimal;
|
|
640
|
+
private formatExponential;
|
|
641
|
+
private formatFixedPoint;
|
|
642
|
+
private formatGeneral;
|
|
643
|
+
private formatNumber_;
|
|
644
|
+
private formatPercent;
|
|
645
|
+
private formatHex;
|
|
646
|
+
private formatBinary;
|
|
647
|
+
private formatCustom;
|
|
648
|
+
private formatWithSection;
|
|
649
|
+
private formatCustomExponential;
|
|
650
|
+
protected trimTrailingPadZeros(value: string): string;
|
|
651
|
+
hasExponentChar(value: string): boolean;
|
|
652
|
+
hasDecimalChar(value: string): boolean;
|
|
653
|
+
hasDigitChar(value: string): boolean;
|
|
654
|
+
static tryHexToInt64(hex: string): Result<bigint>;
|
|
655
|
+
protected unstyleNumberString(value: string): Result<{
|
|
656
|
+
unstyled: string;
|
|
657
|
+
negated: boolean;
|
|
658
|
+
}>;
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/**
|
|
662
|
+
* Individual style flags that control which number formats are allowed during parsing.
|
|
663
|
+
*
|
|
664
|
+
* These flags can be combined to create custom parsing behavior.
|
|
665
|
+
*
|
|
666
|
+
* @example
|
|
667
|
+
* ```typescript
|
|
668
|
+
* // Combine individual flags
|
|
669
|
+
* formatter.styles = new Set([
|
|
670
|
+
* DotNetNumberStyleId.AllowLeadingSign,
|
|
671
|
+
* DotNetNumberStyleId.AllowDecimalPoint,
|
|
672
|
+
* DotNetNumberStyleId.AllowThousands
|
|
673
|
+
* ]);
|
|
674
|
+
* ```
|
|
675
|
+
*
|
|
676
|
+
* @public
|
|
677
|
+
* @category Number Styles
|
|
678
|
+
*/
|
|
679
|
+
export declare enum DotNetNumberStyleId {
|
|
680
|
+
/** Allow currency symbol in the number string. */
|
|
681
|
+
AllowCurrencySymbol = "AllowCurrencySymbol",
|
|
682
|
+
/** Allow decimal point in the number string. */
|
|
683
|
+
AllowDecimalPoint = "AllowDecimalPoint",
|
|
684
|
+
/** Allow exponential notation (e.g., 1.23e+10). */
|
|
685
|
+
AllowExponent = "AllowExponent",
|
|
686
|
+
/** Parse the number as hexadecimal. */
|
|
687
|
+
AllowHexSpecifier = "AllowHexSpecifier",
|
|
688
|
+
/** Allow a leading plus (+) or minus (-) sign. */
|
|
689
|
+
AllowLeadingSign = "AllowLeadingSign",
|
|
690
|
+
/** Allow leading whitespace characters. */
|
|
691
|
+
AllowLeadingWhite = "AllowLeadingWhite",
|
|
692
|
+
/** Allow parentheses to indicate negative numbers. */
|
|
693
|
+
AllowParentheses = "AllowParentheses",
|
|
694
|
+
/** Allow thousands separator characters. */
|
|
695
|
+
AllowThousands = "AllowThousands",
|
|
696
|
+
/** Allow a trailing plus (+) or minus (-) sign. */
|
|
697
|
+
AllowTrailingSign = "AllowTrailingSign",
|
|
698
|
+
/** Allow trailing whitespace characters. */
|
|
699
|
+
AllowTrailingWhite = "AllowTrailingWhite"
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
/* Excluded from this release type: DotNetNumberStyles */
|
|
703
|
+
|
|
704
|
+
/**
|
|
705
|
+
* A set of {@link DotNetNumberStyleId} flags.
|
|
706
|
+
*
|
|
707
|
+
* @public
|
|
708
|
+
* @category Number Styles
|
|
709
|
+
*/
|
|
710
|
+
export declare type DotNetNumberStyleSet = Set<DotNetNumberStyleId>;
|
|
711
|
+
|
|
712
|
+
/* Excluded from this release type: DotNetNumberStylesInfo */
|
|
713
|
+
|
|
714
|
+
export { }
|