@sheetxl/formulas 0.8.0-beta.1 → 0.8.0-beta.3

package/types/src/mathTrig/Math.d.ts

@@ -1,433 +1,780 @@
-import { IRange, Scalar, IReferenceRange, AcceptError, AcceptRefError, Repeating, Omittable } from '@sheetxl/primitives';
+import { IRange, Scalar, Volatile, IReferenceRange, AcceptError, Repeating, Omittable, NoLift, NoFilter, ReportType } from '@sheetxl/primitives';
 /**
- * @summary Returns the absolute value of a number, a number without its sign.
+ * Returns the absolute value of a number, a number without its sign.
  * @param number is the real number for which you want the absolute value.
  */
 export declare function ABS(number: number): number;
 /**
- * @summary Returns an aggregate in a list or database.
+ * The calculation AGGREGATE performs.
+ *
+ * @remarks
+ * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`9.9`
+ * is SUM, measured), which an enum's gate does not, so the body keeps the verdict. Also the
+ * overload discriminant of DESIGN-REPEATING §6: 14-19 take a trailing `k`.
+ */
+declare enum AggregateFunction {
+    /**
+     * The average of the values.
+     * @name AVERAGE
+     */
+    Average = 1,
+    /**
+     * How many values are numbers.
+     * @name COUNT
+     */
+    Count = 2,
+    /**
+     * How many values are not empty.
+     * @name COUNTA
+     */
+    CountA = 3,
+    /**
+     * The largest value.
+     * @name MAX
+     */
+    Max = 4,
+    /**
+     * The smallest value.
+     * @name MIN
+     */
+    Min = 5,
+    /**
+     * The product of the values.
+     * @name PRODUCT
+     */
+    Product = 6,
+    /**
+     * The standard deviation of a sample.
+     * @name STDEV.S
+     */
+    StdevS = 7,
+    /**
+     * The standard deviation of a whole population.
+     * @name STDEV.P
+     */
+    StdevP = 8,
+    /**
+     * The sum of the values.
+     * @name SUM
+     */
+    Sum = 9,
+    /**
+     * The variance of a sample.
+     * @name VAR.S
+     */
+    VarS = 10,
+    /**
+     * The variance of a whole population.
+     * @name VAR.P
+     */
+    VarP = 11,
+    /**
+     * The middle value.
+     * @name MEDIAN
+     */
+    Median = 12,
+    /**
+     * The most frequent value.
+     * @name MODE.SNGL
+     */
+    ModeSngl = 13,
+    /**
+     * The k-th largest value.
+     * @name LARGE
+     */
+    Large = 14,
+    /**
+     * The k-th smallest value.
+     * @name SMALL
+     */
+    Small = 15,
+    /**
+     * The k-th percentile, k from 0 to 1 inclusive.
+     * @name PERCENTILE.INC
+     */
+    PercentileInc = 16,
+    /**
+     * The quartile k, from 0 to 4 inclusive.
+     * @name QUARTILE.INC
+     */
+    QuartileInc = 17,
+    /**
+     * The k-th percentile, k from 0 to 1 exclusive.
+     * @name PERCENTILE.EXC
+     */
+    PercentileExc = 18,
+    /**
+     * The quartile k, from 1 to 3 exclusive.
+     * @name QUARTILE.EXC
+     */
+    QuartileExc = 19
+}
+/**
+ * What AGGREGATE leaves out.
+ *
+ * @remarks
+ * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`6.9`
+ * is 6, measured), which an enum's gate does not, so the body keeps the verdict.
+ */
+declare enum AggregateOptions {
+    /**
+     * Ignore nested SUBTOTAL and AGGREGATE functions.
+     * @name Ignore nested SUBTOTAL and AGGREGATE functions
+     */
+    IgnoreNested = 0,
+    /**
+     * Ignore hidden rows, nested SUBTOTAL and AGGREGATE functions.
+     * @name Ignore hidden rows, nested SUBTOTAL and AGGREGATE functions
+     */
+    IgnoreHiddenNested = 1,
+    /**
+     * Ignore error values, nested SUBTOTAL and AGGREGATE functions.
+     * @name Ignore error values, nested SUBTOTAL and AGGREGATE functions
+     */
+    IgnoreErrorsNested = 2,
+    /**
+     * Ignore hidden rows, error values, nested SUBTOTAL and AGGREGATE functions.
+     * @name Ignore hidden rows, error values, nested SUBTOTAL and AGGREGATE functions
+     */
+    IgnoreHiddenErrorsNested = 3,
+    /**
+     * Ignore nothing.
+     * @name Ignore nothing
+     */
+    IgnoreNothing = 4,
+    /**
+     * Ignore hidden rows.
+     * @name Ignore hidden rows
+     */
+    IgnoreHidden = 5,
+    /**
+     * Ignore error values.
+     * @name Ignore error values
+     */
+    IgnoreErrors = 6,
+    /**
+     * Ignore hidden rows and error values.
+     * @name Ignore hidden rows and error values
+     */
+    IgnoreHiddenErrors = 7
+}
+/**
+ * Returns an aggregate in a list or database.
  * @param functionNum The function to use: 1-19.
  * @param options The options for the aggregate: 0-7.
  * @param array The ranges to aggregate.
  * @param KOrRest If functionNum is 14-19, this is the k value. Otherwise, this is the first of the ranges to aggregate.
  *
  * @remarks
- * | functionNum | Function        |
- * |--------------|-----------------|
- * | 1            | AVERAGE         |
- * | 2            | COUNT           |
- * | 3            | COUNTA          |
- * | 4            | MAX             |
- * | 5            | MIN             |
- * | 6            | PRODUCT         |
- * | 7            | STDEV           |
- * | 8            | STDEVP          |
- * | 9            | SUM             |
- * | 10           | VAR             |
- * | 11           | VARP            |
- * | 12           | MEDIAN          |
- * | 13           | MODE.SNGL       |
- * | 14           | LARGE           |
- * | 15           | SMALL           |
- * | 16           | PERCENTILE.INC  |
- * | 17           | QUARTILE.INC    |
- * | 18           | PERCENTILE.EXC  |
- * | 19           | QUARTILE.EXC    |
- *
- * | options | Behavior                                              |
- * |---------|-------------------------------------------------------|
- * | 0       | Ignore nested SUBTOTAL and AGGREGATE functions        |
- * | 1       | Ignore hidden rows, nested SUBTOTAL and AGGREGATE     |
- * | 2       | Ignore error values, nested SUBTOTAL and AGGREGATE    |
- * | 3       | Ignore hidden rows, errors, nested SUBTOTAL/AGGREGATE |
- * | 4       | Ignore nothing                                        |
- * | 5       | Ignore hidden rows                                    |
- * | 6       | Ignore error values                                   |
- * | 7       | Ignore hidden rows and error values                   |
- *
- * Note: nested SUBTOTAL/AGGREGATE calls within ref ranges are not excluded
- * from the calculation in this implementation. This matches the behavior of
- * most spreadsheet engines but differs from Excel in edge cases where
- * SUBTOTAL results appear within the referenced range.
- */
-export declare function AGGREGATE(functionNum: number, options: number, array: AcceptRefError<IRange>, ...KOrRest: AcceptRefError<IRange>[]): Scalar;
-/**
- * @summary Converts a Roman numeral to Arabic.
+ * Nested SUBTOTAL and AGGREGATE results are always excluded, regardless of `options`.
+ */
+export declare function AGGREGATE(functionNum: ReportType<AggregateFunction>, options: ReportType<AggregateOptions>, array: ReportType<IRange>, ...KOrRest: Repeating<IRange, 254>): Scalar;
+/**
+ * Converts a Roman numeral to Arabic.
  * @param text is the Roman numeral you want to convert.
  */
 export declare function ARABIC(text: string): number;
 /**
- * @summary Converts a number into a text representation with the given radix (base).
+ * Converts a number into a text representation with the given radix (base).
  * @param number is the number that you want to convert.
  * @param radix is the base Radix that you want to convert the number into.
  * @param minLength is the minimum length of the returned string.
+ *
+ * @remarks
+ * Zero has NO digits and `min_length` only pads them: `BASE(0,16,0)` is the empty string, and
+ * `BASE(0,16)` is "0" because an ABSENT `min_length` is 1 where an empty slot is 0.
+ *
+ * `number` and `min_length` are refused on the RAW argument, before the truncation each of them
+ * takes, so `BASE(-0.5,16)` is `#NUM!`. The pad reaches 255 characters and no further.
  */
-export declare function BASE(number: number, radix: number, minLength?: number): string | number;
+export declare function BASE(number: number, radix: number, minLength?: Omittable<number>): string | number;
 /**
- * @summary Rounds a number up, to the nearest multiple of significance.
+ * Rounds a number up, to the nearest multiple of significance.
  * @param number is the value you want to round.
  * @param significance is the multiple to which you want to round.
  * @category Compatibility
  */
 export declare function CEILING(number: number, significance: number): number;
 /**
+ * Rounds a number up, to the nearest integer or to the nearest multiple of significance.
  * @name CEILING.MATH
- * @summary Rounds a number up, to the nearest integer or to the nearest multiple of significance.
  * @param number is the real number you want to round.
- * @param significance when given and nonzero this function will round away from zero.
+ * @param significance is the multiple to which you want to round.
+ * @param mode when given and nonzero this function will round away from zero.
  */
 export declare function CEILING_MATH(number: number, significance?: Omittable<number>, mode?: number): number;
 /**
+ * Rounds a number up to the nearest integer or to the nearest multiple of significance.
  * @name CEILING.PRECISE
- * @summary Rounds a number up to the nearest integer or to the nearest multiple of significance.
  * @param number is the real number you want to round.
  * @param significance is the multiple to which you want to round.
  * @category Compatibility
  */
 export declare function CEILING_PRECISE(number: number, significance?: Omittable<number>): number;
 /**
+ * Rounds a number up, to the nearest multiple of significance.
  * @name ECMA.CEILING
- * @summary Rounds a number up, to the nearest multiple of significance.
  * @param number is the value you want to round.
  * @param significance is the multiple to which you want to round.
  * @category Compatibility
  */
 export declare function ECMA_CEILING(number: number, significance: number): number;
 /**
- * @summary Returns the number of combinations for a given number of items.
+ * Returns the number of combinations for a given number of items.
  * @param number is the total number of items.
  * @param numberChosen is the number of items in each combination.
  */
 export declare function COMBIN(number: number, numberChosen: number): number;
 /**
- * @summary Returns the number of combinations with repetitions for a given number of items.
+ * Returns the number of combinations with repetitions for a given number of items.
  * @param number is the total number of items.
  * @param numberChosen is the number of items in each combination.
  */
 export declare function COMBINA(number: number, numberChosen: number): number;
 /**
- * @summary Converts a text representation of a number in a given base into a decimal number.
+ * Converts a text representation of a number in a given base into a decimal number.
  * @param number is the number that you want to convert.
  * @param radix is the base Radix of the number you are converting.
  */
 export declare function DECIMAL(number: string, radix: number): number;
 /**
- * @summary Converts radians to degrees.
+ * Converts radians to degrees.
  * @param angle is the angle in radians that you want to convert.
  */
 export declare function DEGREES(angle: number): number;
 /**
- * @summary Rounds a positive number up and negative number down to the nearest even integer.
+ * Rounds a positive number up and negative number down to the nearest even integer.
  * @param number is the value to round.
  */
 export declare function EVEN(number: number): number;
 /**
- * @summary Returns e raised to the power of a given number.
+ * Returns e raised to the power of a given number.
  * @param number is the exponent applied to the base e. The constant e equals 2.71828182845904, the base of the natural logarithm.
  */
 export declare function EXP(number: number): number;
 /**
- * @summary Returns the factorial of a number, equal to 1*2*3*...* Number.
+ * Returns the factorial of a number, equal to 1*2*3*...* Number.
  * @param number is the nonnegative number you want the factorial for.
+ *
+ * @remarks
+ * Alone among the combinatorial functions, FACT reads its argument at fifteen significant
+ * digits before truncating it: `FACT(0.0006*10000)` is 720, the factorial of 6, where the
+ * double is 5.999999999999999 and FACTDOUBLE, COMBIN, GCD, LCM, BASE and ROMAN all answer for
+ * 5. The sign is refused BEFORE that truncation, so `FACT(-0.5)` is `#NUM!` where the truncated
+ * argument would be zero.
+ *
+ * 170 is the last factorial that fits a double.
  */
 export declare function FACT(number: number): number;
 /**
- * @summary Returns the double factorial of a number.
+ * Returns the double factorial of a number.
  * @param number is the value for which to return the double factorial.
+ *
+ * @remarks
+ * `FACTDOUBLE(TRUE)` is `#VALUE!` and `FACTDOUBLE(A1:A3)` is `#VALUE!`, where FACT coerces the
+ * boolean and spills the reference — the two sit in one family and are declared differently.
+ *
+ * The bound is on the RAW argument (`FACTDOUBLE(-1.5)` is `#NUM!` and `FACTDOUBLE(-0.9)` is 1),
+ * and the odd tail runs to 301 before it overflows, two steps past the even one.
  */
-export declare function FACTDOUBLE(number: number): number;
+export declare function FACTDOUBLE(number: NoLift<Omittable<AcceptError<Scalar>>>): number;
 /**
- * @summary Rounds a number down to the nearest multiple of significance.
+ * Rounds a number down to the nearest multiple of significance.
  * @param number is the real number you want to round.
  * @param significance is the multiple to which you want to round. Number and Significance must either both be positive or both be negative.
  * @category Compatibility
  */
 export declare function FLOOR(number: number, significance: number): number;
 /**
+ * Rounds a number down, to the nearest integer or to the nearest multiple of significance.
  * @name FLOOR.MATH
- * @summary Rounds a number down, to the nearest integer or to the nearest multiple of significance.
  * @param number is the real number you want to round.
  * @param significance is the multiple to which you want to round.
  * @param mode when given and nonzero this function will round towards zero.
  */
 export declare function FLOOR_MATH(number: number, significance?: Omittable<number>, mode?: Omittable<number>): Scalar;
 /**
+ * Rounds a number down to the nearest integer or to the nearest multiple of significance.
  * @name FLOOR.PRECISE
- * @summary Rounds a number down to the nearest integer or to the nearest multiple of significance.
  * @param number is the real number you want to round.
  * @param significance is the multiple to which you want to round.
  */
 export declare function FLOOR_PRECISE(number: number, significance?: Omittable<number>): number;
 /**
- * @summary Returns the greatest common divisor.
+ * Returns the greatest common divisor.
  * @param number are 1 to 255 values.
- * @compat atp
  */
-export declare function GCD(number: number[]): number;
+export declare function GCD(number: NoFilter<number>[]): number;
 /**
- * @summary Rounds a number down to the nearest integer.
+ * Rounds a number down to the nearest integer.
  * @param number is the real number you want to round down to an integer.
  */
 export declare function INT(number: number): number;
 /**
+ * Rounds a number up to the nearest integer.
  * @name ISO.CEILING
- * @summary Rounds a number up to the nearest integer.
  * @param number is the real number you want to round up to an integer.
  * @param significance is the multiple to which you want to round number.
  * @category Compatibility
  */
-export declare function ISO_CEILING(number: number, significance?: number): number;
+export declare function ISO_CEILING(number: number, significance?: Omittable<number>): number;
 /**
- * @summary Returns the least common multiple.
+ * Returns the least common multiple.
  * @param number are 1 to 255 values for which you want the least common multiple.
- * @compat atp
  */
-export declare function LCM(number: number[]): number;
+export declare function LCM(number: NoFilter<number>[]): number;
 /**
- * @summary Returns the natural logarithm of a number.
+ * Returns the natural logarithm of a number.
  * @param number is the positive real number for which you want the natural logarithm.
  */
 export declare function LN(number: number): number;
 /**
- * @summary Returns the logarithm of a number to the base you specify.
+ * Returns the logarithm of a number to the base you specify.
  * @param number is the positive real number for which you want the logarithm.
  * @param base is the base of the logarithm.
+ *
+ * @remarks
+ * An OMITTED base is 0 and therefore `#NUM!` — `LOG(8,)` does not fall back to 10 the way an
+ * absent one does, and neither does a blank cell. An absent one is `LOG10` exactly, which is not
+ * the same double as `LN(number)/LN(10)`.
  */
 export declare function LOG(number: number, base?: number): number;
 /**
- * @summary Returns the base-10 logarithm of a number.
+ * Returns the base-10 logarithm of a number.
  * @param number is the positive real number for which you want the base-10 logarithm.
  */
 export declare function LOG10(number: number): number;
 /**
- * @summary Returns the matrix determinant of an array.
+ * Returns the matrix determinant of an array.
  * @param array is a numeric array with an equal number of rows and columns, either a cell range or an array constant.
+ *
+ * @remarks
+ * A scalar and a single cell are a 1x1 matrix, so `MDETERM(5)` is 5; any other shape that is not
+ * square is `#VALUE!`, a whole-column reference and a union included.
+ *
+ * The answer of a SINGULAR matrix is not zero. It is whatever the elimination leaves —
+ * `MDETERM({1,2,3;4,5,6;7,8,9})` is 6.661338147750939E-16 and its transpose is exactly 0 — so
+ * there is no tolerance anywhere in the body.
  */
-export declare function MDETERM(array: IRange<number>): Scalar;
+export declare function MDETERM(array: IRange): Scalar;
 /**
- * @summary Returns the inverse matrix for the matrix stored in an array.
+ * Returns the inverse matrix for the matrix stored in an array.
  * @param array is a numeric array with an equal number of rows and columns, either a cell range or an array constant.
+ *
+ * @remarks
+ * A zero PIVOT is `#NUM!` and nothing else is: a matrix that is merely close to singular
+ * inverts, and answers the large numbers that follow from it — the exactly singular
+ * `{1,2,3;4,5,6;7,8,9}` inverts to entries near 9E15 rather than being refused.
+ *
+ * Like MDETERM, it is a 1x1 matrix that a scalar and a single cell describe (`MINVERSE(5)` is
+ * 0.2), and any non-numeric member is `#VALUE!`.
  */
-export declare function MINVERSE(array: IRange<number>): Scalar[][];
+export declare function MINVERSE(array: IRange): Scalar[][];
 /**
- * @summary Returns the matrix product of two arrays, an array with the same number of rows as array1 and columns as array2.
+ * Returns the matrix product of two arrays, an array with the same number of rows as array1 and columns as array2.
  * @param array1 is the first array of numbers to multiply and must have the same number of columns as Array2 has rows.
  * @param array2 is the second array of numbers to multiply and must have the same number of columns as Array1 has rows.
+ *
+ * @remarks
+ * The shape rule is the INNER dimensions, not squareness, so a 2x2 against a 2x3 answers a 2x3.
+ * Two scalars are two 1x1 matrices and multiply, while a scalar against a matrix is `#VALUE!` —
+ * there is no broadcast here.
+ *
+ * Each cell is a SEQUENTIAL sum from zero, left to right, which is observable wherever the terms
+ * cancel: `MMULT({1,1E16,-1E16},{1;1;1})` is 0 and the same three numbers reordered are 1.
  */
-export declare function MMULT(array1: IRange<number>, array2: IRange<number>): Scalar[][];
+export declare function MMULT(array1: IRange, array2: IRange): Scalar[][];
 /**
- * @summary Returns the remainder after a number is divided by a divisor.
+ * Returns the remainder after a number is divided by a divisor.
  * @param number is the number for which you want to find the remainder after the division is performed.
  * @param divisor is the number by which you want to divide Number.
  */
 export declare function MOD(number: number, divisor: number): number;
 /**
- * @summary Returns a number rounded to the desired multiple.
+ * Returns a number rounded to the desired multiple.
  * @param number is the value to round.
  * @param multiple is the multiple to which you want to round number.
+ * @remarks
+ * `MROUND(A1:A3,3)` is `#VALUE!` where the native `MOD(A1:A3,3)` spills three results, and an
+ * ARRAY constant still lifts at the same slot (`MROUND({1.5;-2.5},3)` spills two).
  */
-export declare function MROUND(number: number, multiple: number): number;
+export declare function MROUND(number: NoLift<Omittable<AcceptError<Scalar>>>, multiple: NoLift<Omittable<AcceptError<Scalar>>>): number;
 /**
- * @summary Returns the multinomial of a set of numbers.
+ * Returns the multinomial of a set of numbers.
  * @param number are 1 to 255 values for which you want the multinomial.
- * @compat atp
  */
-export declare function MULTINOMIAL(number: number[]): number;
+export declare function MULTINOMIAL(number: NoFilter<number>[]): number;
 /**
- * @summary Returns the unit matrix for the specified dimension.
+ * Returns the unit matrix for the specified dimension.
  * @param dimension is an integer specifying the dimension of the unit matrix that you want to return.
+ *
+ * @remarks
+ * The dimension is the RAW double, truncated: `MUNIT(0.0006*10000)` is the 5x5 identity, where
+ * SEQUENCE and RANDARRAY read the same expression at fifteen significant digits and build six.
+ * A dimension that truncates to zero or below is `#VALUE!`.
+ *
+ * A dimension too large to build is neither an error nor a matrix — it is an EMPTY array, whose
+ * `ROWS`, `COLUMNS`, `COUNT` and `SUM` are all 0.
  */
 export declare function MUNIT(dimension: number): IRange;
 /**
- * @summary Rounds a positive number up and negative number down to the nearest odd integer.
+ * Rounds a positive number up and negative number down to the nearest odd integer.
  * @param number is the value to round.
  */
 export declare function ODD(number: number): number;
 /**
- * @summary Returns the percentage of a subset of a given data set.
+ * Returns the percentage of a subset of a given data set.
  * @param dataSubset is the subset.
  * @param dataAll is the data set.
  */
-export declare function PERCENTOF(dataSubset: IRange<number>, dataAll: IRange<number>): number;
+export declare function PERCENTOF(dataSubset: ReportType<IRange<number>>, dataAll: ReportType<IRange<number>>): number;
 /**
- * @summary Returns the value of Pi, 3.14159265358979, accurate to 15 digits.
+ * Returns the value of Pi, 3.14159265358979, accurate to 15 digits.
  */
 export declare function PI(): number;
 /**
- * @summary Returns the result of a number raised to a power.
+ * Returns the result of a number raised to a power.
  * @param number is the base number, any real number.
  * @param power is the exponent, to which the base number is raised.
  */
 export declare function POWER(number: number, power: number): number;
 /**
- * @summary Multiplies all the numbers given as arguments.
+ * Multiplies all the numbers given as arguments.
  * @param number are 1 to 255 numbers, logical values, or text representations of numbers that you want to multiply.
+ *
+ * @remarks
+ * The EMPTY product is 0 rather than 1: `PRODUCT(A1:A3)` over three blank or three text cells is
+ * 0, and so is `PRODUCT(A1)` on a blank cell. The identity only appears once something numeric
+ * has been multiplied, so `PRODUCT(A1:A3,2)` over the same three cells is 2.
+ *
+ * The accumulation is left to right and nothing rescues an intermediate overflow:
+ * `PRODUCT(1E200,1E200,1E-200)` is `#NUM!` where the same three in the other order answer 1E200.
  */
 export declare function PRODUCT(number: IRange<number>[]): number;
 /**
- * @summary Returns the integer portion of a division.
+ * Returns the integer portion of a division.
  * @param numerator is the dividend.
  * @param denominator is the divisor.
+ * @remarks
+ * `QUOTIENT(A1:A3,3)` is `#VALUE!` where the native `MOD(A1:A3,3)` spills; an array constant
+ * still lifts.
  */
-export declare function QUOTIENT(numerator: number, denominator: number): number;
+export declare function QUOTIENT(numerator: NoLift<Omittable<AcceptError<Scalar>>>, denominator: NoLift<Omittable<AcceptError<Scalar>>>): number;
 /**
- * @summary Converts degrees to radians.
+ * Converts degrees to radians.
  * @param angle is an angle in degrees that you want to convert.
  */
 export declare function RADIANS(angle: number): number;
 /**
- * @summary Returns a random number greater than or equal to 0 and less than 1, evenly distributed (changes on recalculation).
+ * Returns a random number greater than or equal to 0 and less than 1, evenly distributed (changes on recalculation).
+ *
+ * @remarks
+ * The draw carries 53 bits — it is a multiple of 2^-53, not of 2^-32 — and never reaches 1.
  */
-export declare function RAND(): number;
+export declare function RAND(): Volatile<number>;
 /**
- * @summary Returns an array of random numbers.
+ * Returns an array of random numbers.
  * @param rows the number of rows in the returned array.
  * @param columns the number of columns in the returned array.
  * @param min the minimum number you would like returned.
  * @param max the maximum number you would like returned.
  * @param integer return an integer or a decimal value. TRUE for an integer, FALSE for a decimal number.
+ *
+ * @remarks
+ * `integer` is a LOGICAL slot and reads like one: a number coerces (0 is FALSE, anything else
+ * TRUE) and TEXT does not, numeric text included, where every other slot here parses it. Absent,
+ * omitted and blank all mean FALSE.
+ *
+ * In integer mode a bound that is not a whole number is `#VALUE!` rather than being truncated,
+ * and both ends are INCLUSIVE; the decimal mode's `max` is not (`RANDARRAY(1,1,0,1)` never
+ * answers 1). `min` above `max` is `#VALUE!` in both modes.
  */
-export declare function RANDARRAY(rows?: number, columns?: number, min?: number, max?: number, integer?: boolean): IRange;
+export declare function RANDARRAY(rows?: Omittable<number>, columns?: Omittable<number>, min?: Omittable<number>, max?: Omittable<number>, integer?: Omittable<boolean>): Volatile<IRange>;
 /**
- * @summary Returns a random number between the numbers you specify.
+ * Returns a random number between the numbers you specify.
  * @param bottom is the smallest integer RANDBETWEEN will return.
  * @param top is the largest integer RANDBETWEEN will return.
+ *
+ * @remarks
+ * Both bounds are taken to their CEILING, and the raw double is what is read:
+ * `RANDBETWEEN(2.2,2.2)` is 3 and `RANDBETWEEN(0.07*100,0.07*100)` is 8, where the rounding
+ * family's fifteen-digit reading would say 7. The refusal is decided BEFORE that ceiling, on the
+ * arguments as given — `RANDBETWEEN(2.5,2.2)` is `#NUM!` although both ends ceil to 3.
+ *
+ * The arguments are read RIGHT TO LEFT, so a fault in `top` outranks one in `bottom`.
  */
-export declare function RANDBETWEEN(bottom: Scalar, top: Scalar): number;
+export declare function RANDBETWEEN(bottom: NoLift<Omittable<AcceptError<Scalar>>>, top: NoLift<Omittable<AcceptError<Scalar>>>): Volatile<number>;
 /**
- * @summary Converts an Arabic numeral to Roman, as text.
+ * Converts an Arabic numeral to Roman, as text.
  * @param number is the Arabic numeral you want to convert.
  * @param form is the number specifying the type of Roman numeral you want.
+ *
+ * @remarks
+ * `form` runs 0 (classic) to 4 (most concise) and is also read as a LOGICAL: `ROMAN(499,TRUE)`
+ * is the classic "CDXCIX" and `ROMAN(499,FALSE)` is "ID". Anything outside 0..4 is `#VALUE!`.
+ *
+ * A concise form replaces a four-of-a-kind by a subtraction from a larger numeral, and repeats
+ * that at most `form` times: 499 is "CDXCIX", "LDVLIV", "XDIX", "VDIV", "ID" as the form rises.
  */
-export declare function ROMAN(number: number, form?: number): Scalar;
+export declare function ROMAN(number: number, form?: Omittable<Scalar>): Scalar;
 /**
- * @summary Rounds a number to a specified number of digits.
+ * Rounds a number to a specified number of digits.
  * @param number is the number you want to round.
  * @param numDigits is the number of digits to which you want to round. Negative rounds to the left of the decimal point to the nearest integer.
  */
 export declare function ROUND(number: number, numDigits: number): number;
 /**
- * @summary Rounds a number down, toward zero.
+ * Rounds a number down, toward zero.
  * @param number is any real number that you want rounded down.
  * @param numDigits is the number of digits to which you want to round. Negative rounds to the left of the decimal point to the nearest integer.
  */
 export declare function ROUNDDOWN(number: number, numDigits: number): number;
 /**
- * @summary Rounds a number up, away from zero.
+ * Rounds a number up, away from zero.
  * @param number is any real number that you want rounded up.
  * @param numDigits is the number of digits to which you want to round. Negative rounds to the left of the decimal point to the nearest integer.
  */
 export declare function ROUNDUP(number: number, numDigits: number): number;
 /**
- * @summary Returns a sequence of numbers.
+ * Returns a sequence of numbers.
  * @param rows the number of rows to return.
  * @param columns the number of columns to return.
  * @param start the first number in the sequence.
  * @param step the amount to increment each subsequent value in the sequence.
+ *
+ * @remarks
+ * The values ACCUMULATE rather than being computed from the index: `SEQUENCE(1,3,1,0.1)` ends at
+ * 1.2000000000000002, which `start + i * step` does not produce, and a two-dimensional answer is
+ * the same running sum read in row-major order.
  */
 export declare function SEQUENCE(rows: Omittable<number>, columns?: Omittable<number>, start?: Omittable<number>, step?: Omittable<number>): IRange;
 /**
- * @summary Returns the sum of a power series based on the formula.
+ * Returns the sum of a power series based on the formula.
  * @param x is the input value to the power series.
  * @param n is the initial power to which you want to raise x.
  * @param m is the step by which to increase n for each term in the series.
  * @param coefficients is a set of coefficients by which each successive power of x is multiplied.
+ *
+ * @remarks
+ * `n` and `m` are REAL exponents, not counts — `SERIESSUM(2,-0.5,1,{12,18,24})` answers.
+ *
+ * Coefficients are taken in row-major order from a range of any shape, and a BLANK member is
+ * skipped rather than read as zero, so it does not consume a power: three cells holding 12,
+ * blank, 18 are the series `12·x^n + 18·x^(n+m)`. A member that is text — numeric text included
+ * — is `#VALUE!`, where the same text in GCD, LCM or MULTINOMIAL would be coerced.
+ *
+ * A term whose power is undefined contributes NOTHING rather than failing the sum:
+ * `SERIESSUM(-2,1,0.5,{12,18,24})` is 72, the first and third terms alone, where the second
+ * raises a negative base to a fractional power. A power that OVERFLOWS is still `#NUM!`, and so
+ * is a zero base at a non-positive exponent.
  */
-export declare function SERIESSUM(x: number, n: number, m: number, coefficients: IRange): number;
+export declare function SERIESSUM(x: NoLift<Omittable<AcceptError<Scalar>>>, n: NoLift<Omittable<AcceptError<Scalar>>>, m: NoLift<Omittable<AcceptError<Scalar>>>, coefficients: Omittable<AcceptError<IRange>>): number;
 /**
- * @summary Returns the sign of a number: 1 if the number is positive, zero if the number is zero, or -1 if the number is negative.
+ * Returns the sign of a number: 1 if the number is positive, zero if the number is zero, or -1 if the number is negative.
  * @param number is any real number.
  */
 export declare function SIGN(number: number): number;
 /**
- * @summary Returns the square root of a number.
+ * Returns the square root of a number.
  * @param number is the number for which you want the square root.
  */
 export declare function SQRT(number: number): number;
 /**
- * @summary Returns the square root of (number * Pi).
+ * Returns the square root of (number * Pi).
  * @param number is the number by which p is multiplied.
+ * @remarks
+ * The category's one Analysis ToolPak name, and it behaves like one where its native neighbors
+ * do not: `SQRTPI(TRUE)` is `#VALUE!` where `SQRT(TRUE)` is 1, and `SQRTPI(A1:A3)` is `#VALUE!`
+ * where every native sibling spills three results. An array CONSTANT still lifts.
+ *
+ * The product is taken before the root, so a `number` whose `number * Pi` overflows is `#NUM!`
+ * even though its own square root is ordinary: `SQRTPI(1E307*17)` is `#NUM!` and
+ * `SQRT(1E307*17)` is 1.3E154.
  */
-export declare function SQRTPI(number: number): number;
+export declare function SQRTPI(number: NoLift<Omittable<AcceptError<Scalar>>>): number;
 /**
- * @summary Returns a subtotal in a list or database.
+ * The calculation SUBTOTAL performs; 101-111 leave out hidden rows.
+ *
+ * @remarks
+ * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`9.9`
+ * is SUM, measured), which an enum's gate does not, so the body keeps the verdict. Excel labels
+ * 101-111 with the bare function name, as 1-11; a member name keys the descriptor and the
+ * language packs, so each must be unique.
+ */
+declare enum SubtotalFunction {
+    /**
+     * The average of the values.
+     * @name AVERAGE
+     */
+    Average = 1,
+    /**
+     * How many values are numbers.
+     * @name COUNT
+     */
+    Count = 2,
+    /**
+     * How many values are not empty.
+     * @name COUNTA
+     */
+    CountA = 3,
+    /**
+     * The largest value.
+     * @name MAX
+     */
+    Max = 4,
+    /**
+     * The smallest value.
+     * @name MIN
+     */
+    Min = 5,
+    /**
+     * The product of the values.
+     * @name PRODUCT
+     */
+    Product = 6,
+    /**
+     * The standard deviation of a sample.
+     * @name STDEV
+     */
+    Stdev = 7,
+    /**
+     * The standard deviation of a whole population.
+     * @name STDEVP
+     */
+    StdevP = 8,
+    /**
+     * The sum of the values.
+     * @name SUM
+     */
+    Sum = 9,
+    /**
+     * The variance of a sample.
+     * @name VAR
+     */
+    Var = 10,
+    /**
+     * The variance of a whole population.
+     * @name VARP
+     */
+    VarP = 11,
+    /**
+     * The average of the values, leaving out hidden rows.
+     * @name AVERAGE (visible rows)
+     */
+    AverageVisible = 101,
+    /**
+     * How many values are numbers, leaving out hidden rows.
+     * @name COUNT (visible rows)
+     */
+    CountVisible = 102,
+    /**
+     * How many values are not empty, leaving out hidden rows.
+     * @name COUNTA (visible rows)
+     */
+    CountAVisible = 103,
+    /**
+     * The largest value, leaving out hidden rows.
+     * @name MAX (visible rows)
+     */
+    MaxVisible = 104,
+    /**
+     * The smallest value, leaving out hidden rows.
+     * @name MIN (visible rows)
+     */
+    MinVisible = 105,
+    /**
+     * The product of the values, leaving out hidden rows.
+     * @name PRODUCT (visible rows)
+     */
+    ProductVisible = 106,
+    /**
+     * The standard deviation of a sample, leaving out hidden rows.
+     * @name STDEV (visible rows)
+     */
+    StdevVisible = 107,
+    /**
+     * The standard deviation of a whole population, leaving out hidden rows.
+     * @name STDEVP (visible rows)
+     */
+    StdevPVisible = 108,
+    /**
+     * The sum of the values, leaving out hidden rows.
+     * @name SUM (visible rows)
+     */
+    SumVisible = 109,
+    /**
+     * The variance of a sample, leaving out hidden rows.
+     * @name VAR (visible rows)
+     */
+    VarVisible = 110,
+    /**
+     * The variance of a whole population, leaving out hidden rows.
+     * @name VARP (visible rows)
+     */
+    VarPVisible = 111
+}
+/**
+ * Returns a subtotal in a list or database.
  * @param functionNum is the number 1 to 11 that specifies the summary function for the subtotal.
  * @param ref are 1 to 254 ranges or references for which you want the subtotal.
  *
  * @remarks
- * | functionNum (includes hidden rows) | functionNum (ignores hidden rows)  | Function |
-   |-------------------------------------|-------------------------------------|----------|
-   | 1                                   | 101                                 | AVERAGE  |
-   | 2                                   | 102                                 | COUNT    |
-   | 3                                   | 103                                 | COUNTA   |
-   | 4                                   | 104                                 | MAX      |
-   | 5                                   | 105                                 | MIN      |
-   | 6                                   | 106                                 | PRODUCT  |
-   | 7                                   | 107                                 | STDEV    |
-   | 8                                   | 108                                 | STDEVP   |
-   | 9                                   | 109                                 | SUM      |
-   | 10                                  | 110                                 | VAR      |
-   | 11                                  | 111                                 | VARP     |
- *
- * Note: nested SUBTOTAL/AGGREGATE calls within ref ranges are not excluded
- * from the calculation in this implementation. This matches the behavior of
- * most spreadsheet engines but differs from Excel in edge cases where
- * SUBTOTAL results appear within the referenced range.
- */
-export declare function SUBTOTAL(functionNum: number, // 1 - 11
-ref: AcceptError<IReferenceRange>[]): Scalar;
-/**
- * @summary Adds all the numbers in a range of cells.
+ * Nested SUBTOTAL and AGGREGATE results within ref are always excluded.
+ */
+export declare function SUBTOTAL(functionNum: ReportType<SubtotalFunction>, ref: IReferenceRange[]): Scalar;
+/**
+ * Adds all the numbers in a range of cells.
  * @param number are 1 to 255 numbers to sum. Logical values and text are ignored in cells, included if typed as arguments.
  */
 export declare function SUM(number: IRange<number>[]): number;
 /**
- * @summary Adds the cells specified by a given condition or criteria.
+ * Adds the cells specified by a given condition or criteria.
  * @param range is the range of cells you want evaluated.
  * @param criteria is the condition or criteria in the form of a number, expression, or text that defines which cells will be added.
  * @param sumRange are the actual cells to sum. If omitted, the cells in range are used.
  */
-export declare function SUMIF(range: AcceptError<IReferenceRange>, criteria: AcceptError<Scalar>, sumRange?: AcceptError<IReferenceRange>): Scalar;
+export declare function SUMIF(range: IReferenceRange, criteria: AcceptError<Scalar>, sumRange?: IReferenceRange): Scalar;
 /**
- * @summary Adds the cells specified by a given set of conditions or criteria.
+ * Adds the cells specified by a given set of conditions or criteria.
  * @param sumRange are the actual cells to sum.
  * @param criteria the ranges to evaluate and the conditions to evaluate them against.
  * @param criteria.criteriaRange is the range of cells you want evaluated for the particular condition.
  * @param criteria.criteria is the condition or criteria in the form of a number, expression, or text that defines which cells will be added.
  */
-export declare function SUMIFS(sumRange: AcceptError<IRange>, criteria: Repeating<[criteriaRange: AcceptError<IReferenceRange>, criteria: AcceptError<Scalar>]>): Scalar;
+export declare function SUMIFS(sumRange: IReferenceRange, criteria: Repeating<[criteriaRange: IReferenceRange, criteria: AcceptError<Scalar>]>): Scalar;
 /**
- * @summary Returns the sum of the products of corresponding ranges or arrays.
+ * Returns the sum of the products of corresponding ranges or arrays.
  * @param array are 2 to 255 arrays for which you want to multiply and then add components. All arrays must have the same dimensions.
  */
 export declare function SUMPRODUCT(array: IRange[]): number;
 /**
- * @summary Returns the sum of the squares of the arguments. The arguments can be numbers, arrays, names, or references to cells that contain numbers.
+ * Returns the sum of the squares of the arguments. The arguments can be numbers, arrays, names, or references to cells that contain numbers.
  * @param number are 1 to 255 numbers, arrays, names, or references to arrays for which you want the sum of the squares.
  */
 export declare function SUMSQ(number: IRange<number>[]): number;
 /**
- * @summary Sums the differences between the squares of two corresponding ranges or arrays.
+ * Sums the differences between the squares of two corresponding ranges or arrays.
  * @param arrayX is the first range or array of numbers and can be a number or name, array, or reference that contains numbers.
  * @param arrayY is the second range or array of numbers and can be a number or name, array, or reference that contains numbers.
  */
-export declare function SUMX2MY2(arrayX: AcceptError<IRange>, arrayY: AcceptError<IRange>): number;
+export declare function SUMX2MY2(arrayX: IRange, arrayY: IRange): number;
 /**
- * @summary Returns the sum total of the sums of squares of numbers in two corresponding ranges or arrays.
+ * Returns the sum total of the sums of squares of numbers in two corresponding ranges or arrays.
  * @param arrayX is the first range or array of numbers and can be a number or name, array, or reference that contains numbers.
  * @param arrayY is the second range or array of numbers and can be a number or name, array, or reference that contains numbers.
  */
-export declare function SUMX2PY2(arrayX: AcceptError<IRange>, arrayY: AcceptError<IRange>): number;
+export declare function SUMX2PY2(arrayX: IRange, arrayY: IRange): number;
 /**
- * @summary Sums the squares of the differences in two corresponding ranges or arrays.
+ * Sums the squares of the differences in two corresponding ranges or arrays.
  * @param arrayX is the first range or array of numbers and can be a number or name, array, or reference that contains numbers.
  * @param arrayY is the second range or array of numbers and can be a number or name, array, or reference that contains numbers.
  */
-export declare function SUMXMY2(arrayX: AcceptError<IRange>, arrayY: AcceptError<IRange>): number;
+export declare function SUMXMY2(arrayX: IRange, arrayY: IRange): number;
 /**
- * @summary Truncates a number to an integer by removing the decimal, or fractional, part of the number.
+ * Truncates a number to an integer by removing the decimal, or fractional, part of the number.
  * @param number is the number you want to truncate.
  * @param numDigits is a number specifying the precision of the truncation.
  */
 export declare function TRUNC(number: number, numDigits?: number): number;
+export {};
 //# sourceMappingURL=Math.d.ts.map