documonster 0.20.1 → 0.20.2
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/README.md +1 -1
- package/README_zh.md +1 -1
- package/dist/esm/modules/excel/core/cell.js +5 -6
- package/dist/esm/modules/excel/core/pivot-table.js +17 -9
- package/dist/esm/modules/excel/stream/xlsb-worksheet-reader.js +4 -6
- package/dist/esm/modules/excel/utils/cell-format-parse.js +112 -174
- package/dist/esm/modules/excel/utils/cell-format.js +42 -946
- package/dist/esm/modules/formula/functions/text.js +23 -631
- package/dist/esm/modules/pdf/excel-bridge.js +5 -5
- package/dist/esm/utils/number-format-render.js +814 -0
- package/dist/esm/utils/number-format.js +477 -0
- package/dist/esm/utils/utils.base.js +3 -70
- package/dist/iife/documonster.archive.iife.min.js +1 -1
- package/dist/iife/documonster.csv.iife.min.js +1 -1
- package/dist/iife/documonster.draw.iife.min.js +1 -1
- package/dist/iife/documonster.excel.iife.min.js +50 -50
- package/dist/iife/documonster.formula.iife.min.js +1 -1
- package/dist/iife/documonster.markdown.iife.min.js +1 -1
- package/dist/iife/documonster.mermaid.iife.min.js +1 -1
- package/dist/iife/documonster.pdf.iife.min.js +18 -18
- package/dist/iife/documonster.stream.iife.min.js +1 -1
- package/dist/iife/documonster.word.iife.min.js +60 -60
- package/dist/iife/documonster.xml.iife.min.js +1 -1
- package/dist/types/modules/excel/core/cell.d.ts +11 -0
- package/dist/types/modules/excel/core/pivot-table.d.ts +7 -0
- package/dist/types/modules/excel/utils/cell-format-parse.d.ts +13 -9
- package/dist/types/modules/excel/utils/cell-format.d.ts +21 -33
- package/dist/types/modules/excel/utils/text-metrics.d.ts +1 -0
- package/dist/types/utils/number-format-render.d.ts +47 -0
- package/dist/types/utils/number-format.d.ts +215 -0
- package/dist/types/utils/utils.base.d.ts +1 -9
- package/package.json +1 -1
|
@@ -196,6 +196,15 @@ export declare function cellType(c: CellData): ValueType;
|
|
|
196
196
|
export declare function cellEffectiveType(c: CellData): ValueType;
|
|
197
197
|
export declare function cellToCsvString(c: CellData): string;
|
|
198
198
|
export declare function cellGetValue(c: CellData): CellValueType;
|
|
199
|
+
/**
|
|
200
|
+
* The workbook's date system, from a cell.
|
|
201
|
+
*
|
|
202
|
+
* Needed at *assignment* time, not just at write time, because a time-of-day is anchored on the calendar date
|
|
203
|
+
* that is serial 0 — and that date differs between the two epochs. Reached through the row's worksheet, which is
|
|
204
|
+
* the only link a `CellData` has; a cell not yet attached to a workbook falls back to the 1900 system, which is
|
|
205
|
+
* also what the writers default to.
|
|
206
|
+
*/
|
|
207
|
+
export declare function cellDate1904(cell: CellData): boolean;
|
|
199
208
|
export declare function cellSetValue(c: CellData, v: CellValueInputType): void;
|
|
200
209
|
/**
|
|
201
210
|
* Set a date cell from plain calendar fields, saying which kind of date cell it is.
|
|
@@ -302,6 +311,8 @@ export interface CellView {
|
|
|
302
311
|
readonly value: CellValueType;
|
|
303
312
|
readonly numFmt: string | NumFmt | undefined;
|
|
304
313
|
readonly text: string;
|
|
314
|
+
/** The workbook's date system, which turning a `Date` value back into the serial it displays needs. */
|
|
315
|
+
readonly date1904: boolean;
|
|
305
316
|
readonly effectiveType: ValueType;
|
|
306
317
|
/**
|
|
307
318
|
* The cell's font — the object it *shares* with every other cell its row or column
|
|
@@ -31,6 +31,13 @@ export interface PivotTableSource {
|
|
|
31
31
|
getSheetValues(): unknown[][];
|
|
32
32
|
/** Dimensions of the source data (plain range record). */
|
|
33
33
|
dimensions: RangeData;
|
|
34
|
+
/**
|
|
35
|
+
* The number format of a source cell, by the same 1-indexed row and column as `getColumn`.
|
|
36
|
+
*
|
|
37
|
+
* Row and column values are bare values, so this is the only route to a cell's format — and the format is what
|
|
38
|
+
* makes `45306` a date rather than a quantity. A source without it can still mark a column of `Date` values.
|
|
39
|
+
*/
|
|
40
|
+
getNumberFormat?(rowNumber: number, columnNumber: number): string | undefined;
|
|
34
41
|
}
|
|
35
42
|
/**
|
|
36
43
|
* A value field specification with optional per-field metric override.
|
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
* fraction-of-day number, driven entirely by the *target cell's own* `numFmt`
|
|
4
4
|
* — not by guessing the shape of the input string.
|
|
5
5
|
*
|
|
6
|
-
* This is the inverse of
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* This is the inverse of `@utils/number-format-render`: instead of turning a
|
|
7
|
+
* value into display text per a format, it turns display text back into a
|
|
8
|
+
* value per that same format. Both read the format through the one tokenizer
|
|
9
|
+
* in `@utils/number-format`, so a literal on one side is a literal on the other.
|
|
10
10
|
*
|
|
11
11
|
* ## How it works (and why it is not a heuristic)
|
|
12
12
|
*
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
* is what makes this robust across arbitrary formats instead of accreting a
|
|
26
26
|
* patch per newly-discovered format shape.
|
|
27
27
|
*/
|
|
28
|
-
type FieldRole = "year2" | "year4" | "month" | "day" | "hour" | "minute" | "second" | "ampm" | "ampmShort" | "elapsedHour" | "elapsedMinute" | "elapsedSecond";
|
|
28
|
+
type FieldRole = "year2" | "year4" | "month" | "day" | "weekday" | "hour" | "minute" | "second" | "secondFraction" | "ampm" | "ampmShort" | "elapsedHour" | "elapsedMinute" | "elapsedSecond";
|
|
29
29
|
interface FieldSegment {
|
|
30
30
|
kind: "field";
|
|
31
31
|
role: FieldRole;
|
|
@@ -38,10 +38,12 @@ interface LiteralSegment {
|
|
|
38
38
|
}
|
|
39
39
|
type Segment = FieldSegment | LiteralSegment;
|
|
40
40
|
/**
|
|
41
|
-
* Compile a format section into ordered field/literal segments.
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
41
|
+
* Compile a format's first section into ordered field/literal segments.
|
|
42
|
+
*
|
|
43
|
+
* The section is read by the shared number-format tokenizer, the same one that renders it and that
|
|
44
|
+
* decides on load whether a serial is a date — so a character is a field here exactly when it is a
|
|
45
|
+
* code there, and `m`/`mm` is a month or a minute by the same positional rule. Consecutive literal
|
|
46
|
+
* characters coalesce into one literal segment.
|
|
45
47
|
*/
|
|
46
48
|
export declare function compileFormat(fmt: string): Segment[];
|
|
47
49
|
export interface ParsedDateTime {
|
|
@@ -51,6 +53,8 @@ export interface ParsedDateTime {
|
|
|
51
53
|
hour?: number;
|
|
52
54
|
minute?: number;
|
|
53
55
|
second?: number;
|
|
56
|
+
/** The digits typed after the seconds' decimal point. */
|
|
57
|
+
secondFraction?: string;
|
|
54
58
|
elapsedSeconds?: number;
|
|
55
59
|
}
|
|
56
60
|
/**
|
|
@@ -1,45 +1,27 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
2
|
+
* Display text for a cell value under its number format.
|
|
3
|
+
*
|
|
4
|
+
* Reading and rendering a number format is not done here: both live at Layer 0 in
|
|
5
|
+
* `@utils/number-format` and `@utils/number-format-render`, shared with the readers' date
|
|
6
|
+
* detection and the `TEXT` worksheet function, so that a character is a literal or a code for all
|
|
7
|
+
* of them at once. This file adds only what is specific to a cell — a `Date` value, a default
|
|
8
|
+
* date format for an unformatted date, and the date-kind classification `Cell.getDateKind` reports.
|
|
6
9
|
*/
|
|
7
10
|
import type { NumFmt } from "../types.js";
|
|
8
11
|
/**
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
|
|
12
|
-
export declare function getFormat(numFmtId: number): string;
|
|
13
|
-
/**
|
|
14
|
-
* Check if format is "General"
|
|
15
|
-
*/
|
|
16
|
-
declare function isGeneral(fmt: string): boolean;
|
|
17
|
-
/**
|
|
18
|
-
* Check if format is a date format
|
|
19
|
-
*/
|
|
20
|
-
declare function isDateFormat(fmt: string): boolean;
|
|
21
|
-
/**
|
|
22
|
-
* Main format function - formats a value according to Excel numFmt
|
|
23
|
-
* @param fmt The Excel number format string (e.g., "0.00%", "#,##0", "yyyy-mm-dd")
|
|
24
|
-
* @param val The value to format
|
|
12
|
+
* Format a value according to an Excel number format, as Excel displays it.
|
|
13
|
+
* @param fmt The Excel number format string (e.g. `"0.00%"`, `"#,##0"`, `"yyyy-mm-dd"`)
|
|
14
|
+
* @param val The value to format; a number is an Excel serial when the format names a date
|
|
25
15
|
*/
|
|
26
16
|
export declare function format(fmt: string, val: number | string | boolean): string;
|
|
27
|
-
export declare const cellFormat: {
|
|
28
|
-
format: typeof format;
|
|
29
|
-
getFormat: typeof getFormat;
|
|
30
|
-
isDateFormat: typeof isDateFormat;
|
|
31
|
-
isGeneral: typeof isGeneral;
|
|
32
|
-
};
|
|
33
17
|
/**
|
|
34
|
-
* Check if format is a pure time format
|
|
35
|
-
*
|
|
36
|
-
* Excludes elapsed time formats like [h]:mm:ss which need the full serial number.
|
|
18
|
+
* Check if format is a pure time format: a clock reading with no date part.
|
|
19
|
+
* Elapsed-time formats such as `[h]:mm:ss` are excluded — they need the whole serial.
|
|
37
20
|
*/
|
|
38
21
|
export declare function isTimeOnlyFormat(fmt: string): boolean;
|
|
39
22
|
/**
|
|
40
|
-
* Check if format
|
|
41
|
-
*
|
|
42
|
-
* formats like [h]:mm:ss (not a date format) and distinguishes month-m from minute-m.
|
|
23
|
+
* Check if format names a calendar date: a year, a day, or an `m` that reads as a month.
|
|
24
|
+
* Elapsed-time formats are not dates.
|
|
43
25
|
*/
|
|
44
26
|
export declare function isDateDisplayFormat(fmt: string): boolean;
|
|
45
27
|
/**
|
|
@@ -61,13 +43,19 @@ export declare function dateFormatKind(fmt: string | undefined): DateFormatKind;
|
|
|
61
43
|
/**
|
|
62
44
|
* Format a value according to the given format string.
|
|
63
45
|
* Handles Date objects with timezone-independent Excel serial conversion.
|
|
46
|
+
*
|
|
47
|
+
* `date1904` is the workbook's date system. A `Date` read from a 1904 workbook has to become the same serial
|
|
48
|
+
* again: a calendar date survives either epoch, because its fields come back out unchanged, but an elapsed
|
|
49
|
+
* format reads the whole serial — and `[h]:mm` showed 36 hours as 35124 when the epoch was dropped here.
|
|
64
50
|
*/
|
|
65
|
-
export declare function formatCellValue(value: Date | number | boolean | string, fmt: string, dateFormat?: string): string;
|
|
51
|
+
export declare function formatCellValue(value: Date | number | boolean | string, fmt: string, dateFormat?: string, date1904?: boolean): string;
|
|
66
52
|
/** Minimal cell shape needed by {@link getCellDisplayText} — avoids importing Cell. */
|
|
67
53
|
interface CellLike {
|
|
68
54
|
value: unknown;
|
|
69
55
|
numFmt: string | NumFmt | undefined;
|
|
70
56
|
text: string;
|
|
57
|
+
/** The workbook's date system; the 1900 system when absent. */
|
|
58
|
+
date1904?: boolean;
|
|
71
59
|
}
|
|
72
60
|
/**
|
|
73
61
|
* Get the formatted display text for a cell value.
|
|
@@ -126,6 +126,7 @@ export interface MeasurableCell {
|
|
|
126
126
|
readonly value: unknown;
|
|
127
127
|
readonly numFmt: string | NumFmt | undefined;
|
|
128
128
|
readonly text: string;
|
|
129
|
+
readonly date1904?: boolean;
|
|
129
130
|
readonly effectiveType: ValueType;
|
|
130
131
|
readonly font: Partial<Font> | undefined;
|
|
131
132
|
readonly alignment: Partial<Alignment> | undefined;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Render a value through an Excel number format.
|
|
3
|
+
*
|
|
4
|
+
* **One renderer for every caller.** A cell's display text and the `TEXT` worksheet function
|
|
5
|
+
* format a number the same way in Excel, but this library used to carry two implementations:
|
|
6
|
+
* `excel/utils/cell-format.ts` for display and a second copy inside the formula engine. They had
|
|
7
|
+
* different rounding, different fraction search, different month/minute rules and different ideas
|
|
8
|
+
* of what a literal is — `TEXT` read `0" hours"` as a date and dropped every literal from a
|
|
9
|
+
* percentage, while the display path placed the minus sign after a currency symbol. The formula
|
|
10
|
+
* engine sits below the Excel module and could not import the display renderer, so the shared one
|
|
11
|
+
* lives here, at Layer 0, where both can reach it.
|
|
12
|
+
*
|
|
13
|
+
* It renders from the tokens of `./number-format`, so the question "is this character a code or a
|
|
14
|
+
* literal" has one answer for rendering, for date detection on load, for date-kind classification
|
|
15
|
+
* and for input parsing.
|
|
16
|
+
*/
|
|
17
|
+
export interface NumberFormatRenderOptions {
|
|
18
|
+
/**
|
|
19
|
+
* The workbook's epoch, which date codes read the serial in. Defaults to the 1900 epoch. A serial made
|
|
20
|
+
* from a `Date` has to be made with the same epoch passed here: calendar fields would survive a mismatch,
|
|
21
|
+
* but an elapsed format reads the whole serial and would be off by 1,462 days.
|
|
22
|
+
*/
|
|
23
|
+
readonly date1904?: boolean;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Format `value` as Excel would display it under `fmt`.
|
|
27
|
+
*
|
|
28
|
+
* Text is shown through the format's text section (the fourth, or a trailing section carrying
|
|
29
|
+
* `@`), or as is when there is none. Booleans are `TRUE`/`FALSE`. An empty format is `General`.
|
|
30
|
+
* A value the format cannot show — a date past 9999 or before 1900, a negative time, a conditional
|
|
31
|
+
* format no section of which matches — is shown as hashes, as Excel shows it in a cell.
|
|
32
|
+
*/
|
|
33
|
+
export declare function renderNumberFormat(fmt: string, value: number | string | boolean, options?: NumberFormatRenderOptions): string;
|
|
34
|
+
/**
|
|
35
|
+
* {@link renderNumberFormat}, but `undefined` for a value the format cannot show — which is where
|
|
36
|
+
* Excel's `TEXT()` returns `#VALUE!` and a cell shows hashes.
|
|
37
|
+
*/
|
|
38
|
+
export declare function tryRenderNumberFormat(fmt: string, value: number | string | boolean, options?: NumberFormatRenderOptions): string | undefined;
|
|
39
|
+
/**
|
|
40
|
+
* Excel's `General`: at most eleven characters, not counting a minus sign, switching to scientific
|
|
41
|
+
* notation with six significant digits when a number cannot fit — `0.333333333`, `1.23457E+11`,
|
|
42
|
+
* `1234567891` for 1234567890.5. The shape of the algorithm is SheetJS's, which its authors calibrated
|
|
43
|
+
* against Excel; the rounding is decimal, at fifteen significant digits, so a half like -501059677.45 rounds
|
|
44
|
+
* away from zero as Excel does rather than as its nearest double would. It agreed with Excel on all 146
|
|
45
|
+
* values measured.
|
|
46
|
+
*/
|
|
47
|
+
export declare function formatGeneral(value: number): string;
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Excel number formats, read once.
|
|
3
|
+
*
|
|
4
|
+
* **Why this exists.** A number format such as `\$0.0,,"M"` or `[h]:mm:ss` is a small language,
|
|
5
|
+
* and this codebase used to read it with a separate scanner per consumer: the XLSX/XLSB readers
|
|
6
|
+
* deciding whether a serial is a date, the display formatter, the date-kind classifier, the
|
|
7
|
+
* pivot cache writer, the `TEXT` function and the input parser. Each one stripped a different
|
|
8
|
+
* subset of the constructs that make a character *literal* — quotes, backslash escapes,
|
|
9
|
+
* `_x` padding, `*x` fill, bracket tags — so each one mistook a different literal for a code.
|
|
10
|
+
* `\$0.0,,\M` turned a five-billion-dollar figure into `Invalid Date` on load because one of them
|
|
11
|
+
* read the escaped `M` as a month; `0_m` was a date to one reader and a number to another.
|
|
12
|
+
*
|
|
13
|
+
* Patching each scanner is how they drifted apart in the first place. So there is now one
|
|
14
|
+
* tokenizer: every consumer asks it what a format says, and a character is a code or a literal
|
|
15
|
+
* for all of them or for none.
|
|
16
|
+
*
|
|
17
|
+
* What it models:
|
|
18
|
+
*
|
|
19
|
+
* - **Sections** split on `;`, except inside quotes, brackets or after a backslash.
|
|
20
|
+
* - **Literals**: `"quoted"`, `\x`, and any character that is not a code.
|
|
21
|
+
* - **Layout**: `_x` (space the width of `x`) and `*x` (repeat `x` to fill).
|
|
22
|
+
* - **Bracket tags**: colours, conditions (`[>=100]`), locale/currency (`[$€-407]`), elapsed time
|
|
23
|
+
* (`[h]`, `[mm]`, `[ss]`) and anything else (`[DBNum1]`), each kept apart so a consumer can act
|
|
24
|
+
* on the one it needs.
|
|
25
|
+
* - **Date and time codes**, with each `m`/`mm` resolved to month or minute where it stands —
|
|
26
|
+
* Excel's rule is positional (minute directly after an hour or directly before a second), so
|
|
27
|
+
* `yyyy-mm-dd hh:mm` holds one of each and no format-wide flag can describe it.
|
|
28
|
+
* - **Number codes**: `0 # ?`, `.`, `,`, `%`, `E+`/`E-`, `/` and `@`, and the word `General`.
|
|
29
|
+
*
|
|
30
|
+
* `e` and `g` (era years in East Asian locales) are deliberately literals: an unquoted word such
|
|
31
|
+
* as `zero` in `0;-0;zero` must stay a word, and no locale this library renders uses them.
|
|
32
|
+
* `b` (Buddhist year) is a code, as it was for the XLSX reader before this module existed.
|
|
33
|
+
*/
|
|
34
|
+
/** English month names, January first: what `mmm`/`mmmm`/`mmmmm` print and what input parsing accepts. */
|
|
35
|
+
export declare const MONTH_NAMES: readonly string[];
|
|
36
|
+
/** English weekday names, Sunday first: what `ddd`/`dddd` print and what input parsing accepts. */
|
|
37
|
+
export declare const DAY_NAMES: readonly string[];
|
|
38
|
+
/** A comparison in a conditional section such as `[>=100]`. */
|
|
39
|
+
export type FormatCompareOp = "=" | "<>" | "<" | "<=" | ">" | ">=";
|
|
40
|
+
/** What a date/time code stands for, after `m` has been resolved to month or minute. */
|
|
41
|
+
export type FormatDatePart = "year" | "buddhistYear" | "month" | "day" | "hour" | "minute" | "second";
|
|
42
|
+
/** One lexical element of a number-format section. */
|
|
43
|
+
export type FormatToken =
|
|
44
|
+
/** Text shown as written: a quoted run, an escaped character, or a character that is not a code. */
|
|
45
|
+
{
|
|
46
|
+
readonly kind: "literal";
|
|
47
|
+
readonly text: string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* An unquoted digit 1–9. It prints as itself, and is kept apart from `literal` because it is also the one
|
|
51
|
+
* place a digit is syntax: the fixed denominator of `# ?/16`. A quoted or escaped digit (`"8"`, `\8`) is a
|
|
52
|
+
* `literal` and never a denominator.
|
|
53
|
+
*/
|
|
54
|
+
| {
|
|
55
|
+
readonly kind: "numeral";
|
|
56
|
+
readonly text: string;
|
|
57
|
+
}
|
|
58
|
+
/** `_x`: a space as wide as `x`. */
|
|
59
|
+
| {
|
|
60
|
+
readonly kind: "pad";
|
|
61
|
+
readonly char: string;
|
|
62
|
+
}
|
|
63
|
+
/** `*x`: `x` repeated to fill the cell. */
|
|
64
|
+
| {
|
|
65
|
+
readonly kind: "fill";
|
|
66
|
+
readonly char: string;
|
|
67
|
+
} | {
|
|
68
|
+
readonly kind: "color";
|
|
69
|
+
readonly name: string;
|
|
70
|
+
} | {
|
|
71
|
+
readonly kind: "condition";
|
|
72
|
+
readonly op: FormatCompareOp;
|
|
73
|
+
readonly value: number;
|
|
74
|
+
}
|
|
75
|
+
/** `[$…]`: a currency symbol and/or locale id. `symbol` is the text before any `-`. */
|
|
76
|
+
| {
|
|
77
|
+
readonly kind: "locale";
|
|
78
|
+
readonly symbol: string;
|
|
79
|
+
}
|
|
80
|
+
/** A bracket tag with no effect on the rendered text, such as `[DBNum1]`. */
|
|
81
|
+
| {
|
|
82
|
+
readonly kind: "bracket";
|
|
83
|
+
readonly text: string;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* `[h]`, `[mm]`, `[ss]`: a total count of units rather than a clock reading. `fraction` is the number of
|
|
87
|
+
* decimal places after `[ss]` (`[ss].00`), and 0 otherwise.
|
|
88
|
+
*/
|
|
89
|
+
| {
|
|
90
|
+
readonly kind: "elapsed";
|
|
91
|
+
readonly unit: "h" | "m" | "s";
|
|
92
|
+
readonly width: number;
|
|
93
|
+
readonly fraction: number;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* A date or time code. `fraction` is the number of decimal places of a seconds code (`ss.000`); the point
|
|
97
|
+
* and its zeros belong to the code, not to the number layout, and 0 means there are none.
|
|
98
|
+
*/
|
|
99
|
+
| {
|
|
100
|
+
readonly kind: "date";
|
|
101
|
+
readonly part: FormatDatePart;
|
|
102
|
+
readonly width: number;
|
|
103
|
+
readonly fraction: number;
|
|
104
|
+
}
|
|
105
|
+
/** `AM/PM` or `A/P`; `lower` when written in lower case, which is how Excel prints it back. */
|
|
106
|
+
| {
|
|
107
|
+
readonly kind: "ampm";
|
|
108
|
+
readonly short: boolean;
|
|
109
|
+
readonly lower: boolean;
|
|
110
|
+
} | {
|
|
111
|
+
readonly kind: "digit";
|
|
112
|
+
readonly char: "0" | "#" | "?";
|
|
113
|
+
} | {
|
|
114
|
+
readonly kind: "decimal";
|
|
115
|
+
} | {
|
|
116
|
+
readonly kind: "thousands";
|
|
117
|
+
} | {
|
|
118
|
+
readonly kind: "percent";
|
|
119
|
+
} | {
|
|
120
|
+
readonly kind: "exponent";
|
|
121
|
+
readonly sign: "+" | "-";
|
|
122
|
+
readonly upper: boolean;
|
|
123
|
+
} | {
|
|
124
|
+
readonly kind: "slash";
|
|
125
|
+
}
|
|
126
|
+
/** `@`: the cell's text. */
|
|
127
|
+
| {
|
|
128
|
+
readonly kind: "text";
|
|
129
|
+
} | {
|
|
130
|
+
readonly kind: "general";
|
|
131
|
+
};
|
|
132
|
+
/** One section of a format, with the facts every consumer asks about computed once. */
|
|
133
|
+
export interface FormatSection {
|
|
134
|
+
/** The section as written. */
|
|
135
|
+
readonly source: string;
|
|
136
|
+
readonly tokens: readonly FormatToken[];
|
|
137
|
+
/** A year, month or day code. */
|
|
138
|
+
readonly hasDate: boolean;
|
|
139
|
+
/** An hour, minute or second code, or an AM/PM marker. */
|
|
140
|
+
readonly hasTime: boolean;
|
|
141
|
+
/** An elapsed-time tag such as `[h]`. */
|
|
142
|
+
readonly hasElapsed: boolean;
|
|
143
|
+
/** The `@` text placeholder. */
|
|
144
|
+
readonly hasText: boolean;
|
|
145
|
+
/** The `General` keyword. */
|
|
146
|
+
readonly hasGeneral: boolean;
|
|
147
|
+
/** The section's condition, if it carries one. */
|
|
148
|
+
readonly condition: {
|
|
149
|
+
readonly op: FormatCompareOp;
|
|
150
|
+
readonly value: number;
|
|
151
|
+
} | undefined;
|
|
152
|
+
}
|
|
153
|
+
/** A whole format: its sections, and which of them formats text. */
|
|
154
|
+
export interface ParsedNumberFormat {
|
|
155
|
+
readonly source: string;
|
|
156
|
+
readonly sections: readonly FormatSection[];
|
|
157
|
+
/**
|
|
158
|
+
* The sections that format numbers, in order. A section carrying `@` is the *text* section and
|
|
159
|
+
* is excluded, which is what makes `0.00;@` a one-section number format rather than one whose
|
|
160
|
+
* negative numbers are rendered as text.
|
|
161
|
+
*/
|
|
162
|
+
readonly numberSections: readonly FormatSection[];
|
|
163
|
+
/** The section that formats a text value, or `undefined` when text is shown as is. */
|
|
164
|
+
readonly textSection: FormatSection | undefined;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Split a format into its `;`-separated sections (positive; negative; zero; text).
|
|
168
|
+
*
|
|
169
|
+
* A `;` inside `"…"`, inside `[…]`, or taken as the argument of `\`, `_` or `*` is part of a section,
|
|
170
|
+
* not a separator — the same rules `tokenizeFormatSection` reads a character by.
|
|
171
|
+
*/
|
|
172
|
+
export declare function splitFormatSections(fmt: string): string[];
|
|
173
|
+
/**
|
|
174
|
+
* Read one section into tokens.
|
|
175
|
+
*
|
|
176
|
+
* Every construct that makes a character literal is recognised here and only here, so no consumer
|
|
177
|
+
* can mistake `\M`, `"M"`, `_M` or `*M` for a month.
|
|
178
|
+
*/
|
|
179
|
+
export declare function tokenizeFormatSection(section: string): FormatToken[];
|
|
180
|
+
/**
|
|
181
|
+
* Parse a whole format. Results are cached: a reader asks about the same handful of formats once
|
|
182
|
+
* per cell.
|
|
183
|
+
*/
|
|
184
|
+
export declare function parseNumberFormat(fmt: string): ParsedNumberFormat;
|
|
185
|
+
/** What a format's first section says about dates and times. */
|
|
186
|
+
export interface NumberFormatFacets {
|
|
187
|
+
/** A year, month or day code. */
|
|
188
|
+
readonly date: boolean;
|
|
189
|
+
/** An hour, minute or second code, or AM/PM. */
|
|
190
|
+
readonly time: boolean;
|
|
191
|
+
/** An elapsed-time tag such as `[h]`. */
|
|
192
|
+
readonly elapsed: boolean;
|
|
193
|
+
/** The `@` text placeholder. */
|
|
194
|
+
readonly text: boolean;
|
|
195
|
+
/** `General`, or no format at all. */
|
|
196
|
+
readonly general: boolean;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* The date and time facts of a format, read from its **first** section — the one that applies to
|
|
200
|
+
* a positive serial, and therefore to every date. `";;;dd"` hides numbers; it is not a date format.
|
|
201
|
+
*/
|
|
202
|
+
export declare function numberFormatFacets(fmt: string | null | undefined): NumberFormatFacets;
|
|
203
|
+
/**
|
|
204
|
+
* Whether a cell carrying this format holds a date: its first section names a calendar or clock code
|
|
205
|
+
* outside every literal, and is not a text format.
|
|
206
|
+
*
|
|
207
|
+
* This is the rule every reader applies when deciding whether a stored serial becomes a `Date`.
|
|
208
|
+
*
|
|
209
|
+
* **An elapsed tag on its own does not count.** `[h]` or `[ss]` is a quantity of time, and a `Date` would
|
|
210
|
+
* misstate it — and could not hold it past a few thousand years. `[h]:mm:ss` still counts, through its
|
|
211
|
+
* clock codes, which is the reading these readers have always given both forms.
|
|
212
|
+
*/
|
|
213
|
+
export declare function isDateFmt(fmt: string | null | undefined): boolean;
|
|
214
|
+
/** Whether a format is `General` — or empty, which Excel treats the same way. */
|
|
215
|
+
export declare function isGeneralFormat(fmt: string | null | undefined): boolean;
|
|
@@ -72,15 +72,7 @@ export declare function encodeOoxmlEscape(text: string): string;
|
|
|
72
72
|
*/
|
|
73
73
|
export declare function encodeOoxmlAttr(text: string): string;
|
|
74
74
|
export declare function validInt(value: string | number): number;
|
|
75
|
-
|
|
76
|
-
* Split an Excel numFmt string by semicolons, respecting quoted strings and brackets.
|
|
77
|
-
*
|
|
78
|
-
* Excel numFmt can have up to 4 sections: `positive ; negative ; zero ; text`.
|
|
79
|
-
* Semicolons inside `"..."` (literal text) or `[...]` (locale/color tags) must NOT
|
|
80
|
-
* be treated as section separators.
|
|
81
|
-
*/
|
|
82
|
-
export declare function splitFormatSections(fmt: string): string[];
|
|
83
|
-
export declare function isDateFmt(fmt: string | null | undefined): boolean;
|
|
75
|
+
export { isDateFmt, splitFormatSections } from "./number-format.js";
|
|
84
76
|
export declare function parseBoolean(value: unknown): boolean;
|
|
85
77
|
export declare function range(start: number, stop: number, step?: number): Generator<number>;
|
|
86
78
|
export declare function toSortedArray<T>(values: Iterable<T>): T[];
|
package/package.json
CHANGED