HyperFormula (v2.6.0)

# Config Class

# Constructors

# constructor

+ new Config(options: Partial‹ConfigParams›, showDeprecatedWarns: boolean): Config

Defined in src/Config.ts:617 (opens new window)

Parameters:

Name Type Default
options Partial‹ConfigParams› {}
showDeprecatedWarns boolean true

Returns: Config

# Properties

# accentSensitive Readonly

• accentSensitive: boolean

Defined in src/Config.ts:539 (opens new window)

When set to true, makes string comparison accent-sensitive.

Applies only to comparison operators.

default false

# arrayColumnSeparator Readonly

• arrayColumnSeparator: "," | ";"

Defined in src/Config.ts:549 (opens new window)

Sets a column separator symbol for array notation.

default ','

# arrayRowSeparator Readonly

• arrayRowSeparator: ";" | "|"

Defined in src/Config.ts:551 (opens new window)

Sets a row separator symbol for array notation.

default ';'

# binarySearchThreshold Readonly

• binarySearchThreshold: number

Defined in src/Config.ts:592 (opens new window)

Sets a minimum number of elements that a range must have to use binary search.

deprecated Every search of sorted data always uses binary search.

default 20

# caseFirst Readonly

• caseFirst: "upper" | "lower" | "false"

Defined in src/Config.ts:541 (opens new window)

When set to upper, upper case sorts first.

When set to lower, lower case sorts first.

When set to false, uses the locale's default.

default 'lower'

# caseSensitive Readonly

• caseSensitive: boolean

Defined in src/Config.ts:535 (opens new window)

When set to true, makes string comparison case-sensitive.

Applies to comparison operators only.

default false

# chooseAddressMappingPolicy Readonly

• chooseAddressMappingPolicy: ChooseAddressMapping

Defined in src/Config.ts:537 (opens new window)

Sets the address mapping policy to be used.

Built-in implementations:

  • DenseSparseChooseBasedOnThreshold: sets the address mapping policy separately for each sheet, based on fill ratio.
  • AlwaysDense: uses DenseStrategy for all sheets.
  • AlwaysSparse: uses SparseStrategy for all sheets.

default AlwaysDense

# currencySymbol Readonly

• currencySymbol: string[]

Defined in src/Config.ts:596 (opens new window)

Sets symbols that denote currency numbers.

For more information, see the Internationalization features guide.

default ['$']

# dateFormats Readonly

• dateFormats: string[]

Defined in src/Config.ts:543 (opens new window)

Sets the date formats accepted by the date-parsing function.

A format must be specified as a string consisting of tokens and separators.

Supported tokens:

  • DD (day of month)
  • MM (month as a number)
  • YYYY (year as a 4-digit number)
  • YY (year as a 2-digit number)

Supported separators:

  • / (slash)
  • - (dash)
  • . (dot)
  • (empty space)

Regardless of the separator specified in the format string, all of the above are accepted by the date-parsing function.

For more information, see the Date and time handling guide.

default ['DD/MM/YYYY', 'DD/MM/YY']

# decimalSeparator Readonly

• decimalSeparator: "." | ","

Defined in src/Config.ts:553 (opens new window)

Sets a decimal separator used for parsing numerical literals.

Can be one of the following:

  • . (period)
  • , (comma)

Must be different from thousandSeparator and functionArgSeparator.

For more information, see the Internationalization features guide.

default '.'

# evaluateNullToZero Readonly

• evaluateNullToZero: boolean

Defined in src/Config.ts:572 (opens new window)

When set to true, formulas evaluating to null evaluate to 0 instead.

default false

# functionArgSeparator Readonly

• functionArgSeparator: string

Defined in src/Config.ts:547 (opens new window)

Sets a separator character that separates procedure arguments in formulas.

Must be different from decimalSeparator and thousandSeparator.

For more information, see the Internationalization features guide.

default ','

# functionPlugins Readonly

• functionPlugins: FunctionPluginDefinition[]

Defined in src/Config.ts:564 (opens new window)

Lists additional function plugins to be used by the formula interpreter.

default []

# ignorePunctuation Readonly

• ignorePunctuation: boolean

Defined in src/Config.ts:568 (opens new window)

When set to true, string comparison ignores punctuation.

default false

# ignoreWhiteSpace Readonly

• ignoreWhiteSpace: "standard" | "any"

Defined in src/Config.ts:559 (opens new window)

Controls the set of whitespace characters that are allowed inside a formula.

When set to 'standard', allows only SPACE (U+0020), CHARACTER TABULATION (U+0009), LINE FEED (U+000A), and CARRIAGE RETURN (U+000D) (compliant with OpenFormula Standard 1.3)

When set to 'any', allows all whitespace characters that would be captured by the \s character class of the JavaScript regular expressions.

default 'standard'

# language Readonly

• language: string

Defined in src/Config.ts:557 (opens new window)

Sets a translation package for function and error names.

For more information, see the Localizing functions guide.

default 'enGB'

# leapYear1900 Readonly

• leapYear1900: boolean

Defined in src/Config.ts:566 (opens new window)

Sets year 1900 as a leap year.

For compatibility with Lotus 1-2-3 and Microsoft Excel, set this option to true.

For more information, see nullDate.

default false

# licenseKey Readonly

• licenseKey: string

Defined in src/Config.ts:561 (opens new window)

Sets your HyperFormula license key.

To use HyperFormula on the GPLv3 license terms, set this option to gpl-v3.

To use HyperFormula with your commercial license, set this option to your valid license key string.

For more information, go here.

default undefined

# localeLang Readonly

• localeLang: string

Defined in src/Config.ts:570 (opens new window)

Sets the locale for language-sensitive string comparison.

Accepts IETF BCP 47 language tags.

For more information, see the Internationalization features guide.

default 'en'

# matchWholeCell Readonly

• matchWholeCell: boolean

Defined in src/Config.ts:617 (opens new window)

# maxColumns Readonly

• maxColumns: number

Defined in src/Config.ts:608 (opens new window)

Sets the maximum number of columns.

default 18.278 (Columns A, B, ..., ZZZ)

# maxRows Readonly

• maxRows: number

Defined in src/Config.ts:606 (opens new window)

Sets the maximum number of rows.

default 40.000

# nullDate Readonly

• nullDate: SimpleDate

Defined in src/Config.ts:594 (opens new window)

Internally, each date is represented as a number of days that passed since nullDate.

This option sets a specific date from which that number of days is counted.

For more information, see the Date and time handling guide.

default {year: 1899, month: 12, day: 30}

# nullYear Readonly

• nullYear: number

Defined in src/Config.ts:574 (opens new window)

Sets the interpretation of two-digit year values.

Two-digit year values (xx) can either become 19xx or 20xx.

If xx is less or equal to nullYear, two-digit year values become 20xx.

If xx is more than nullYear, two-digit year values become 19xx.

default 30

# parseDateTime Readonly

• parseDateTime: function

Defined in src/Config.ts:576 (opens new window)

Sets a function that parses strings representing date-time into actual date-time values.

The function should return a DateTime object or undefined.

For more information, see the Date and time handling guide.

default defaultParseToDateTime

# Type declaration:

▸ (dateTimeString: string, dateFormat?: undefined | string, timeFormat?: undefined | string): Maybe‹DateTime›

Parameters:

Name Type
dateTimeString string
dateFormat? undefined | string
timeFormat? undefined | string

# precisionEpsilon Readonly

• precisionEpsilon: number

Defined in src/Config.ts:582 (opens new window)

Sets how far two numerical values need to be from each other to be treated as non-equal.

a and b are equal if all three of the following conditions are met:

  • Both a and b are of the same sign
  • abs(a) <= (1+precisionEpsilon) * abs(b)
  • abs(b) <= (1+precisionEpsilon) * abs(a)

Additionally, this option controls the snap-to-zero behavior for additions and subtractions:

  • For c=a+b, if abs(c) <= precisionEpsilon * abs(a), then c is set to 0
  • For c=a-b, if abs(c) <= precisionEpsilon * abs(a), then c is set to 0

default 1e-13

# precisionRounding Readonly

• precisionRounding: number

Defined in src/Config.ts:584 (opens new window)

Sets the precision level of calculations' output.

Internally, all arithmetic operations are performed using JavaScript's built-in numbers. But when HyperFormula exports a cell's value, it rounds the output to the precisionRounding number of significant digits.

Setting precisionRounding too low can cause large numbers' imprecision (for example, with precisionRounding set to 4, 100005 becomes 100010).

We recommend setting precisionRounding to a value between 10 and 14.

default 14

# smartRounding Readonly

• smartRounding: boolean

Defined in src/Config.ts:586 (opens new window)

When set to false, no rounding happens, and numbers are equal if and only if they are of truly identical value.

For more information, see precisionEpsilon.

default true

# stringifyDateTime Readonly

• stringifyDateTime: function

Defined in src/Config.ts:578 (opens new window)

Sets a function that converts date-time values into strings.

The function should return a string or undefined.

For more information, see the Date and time handling guide.

default defaultStringifyDateTime

# Type declaration:

▸ (date: SimpleDateTime, formatArg: string): Maybe‹string›

Parameters:

Name Type
date SimpleDateTime
formatArg string

# stringifyDuration Readonly

• stringifyDuration: function

Defined in src/Config.ts:580 (opens new window)

Sets a function that converts time duration values into strings.

The function should return a string or undefined.

For more information, see the Date and time handling guide.

default defaultStringifyDuration

# Type declaration:

▸ (time: SimpleTime, formatArg: string): Maybe‹string›

Parameters:

Name Type
time SimpleTime
formatArg string

# thousandSeparator Readonly

• thousandSeparator: "" | "," | " " | "."

Defined in src/Config.ts:555 (opens new window)

Sets the thousands' separator symbol for parsing numerical literals.

Can be one of the following:

  • empty
  • , (comma)
  • (empty space)

Must be different from decimalSeparator and functionArgSeparator.

For more information, see the Internationalization features guide.

default ''

# timeFormats Readonly

• timeFormats: string[]

Defined in src/Config.ts:545 (opens new window)

Sets the time formats accepted by the time-parsing function.

A format must be specified as a string consisting of at least two tokens separated by : (a colon).

Supported tokens:

  • hh (hours)
  • mm (minutes)
  • ss, ss.s, ss.ss, ss.sss, ss.ssss, etc. (seconds)

The number of decimal places in the seconds token does not matter. All versions of the seconds token are equivalent in the context of parsing time values. Regardless of the time format specified, the hours-minutes-seconds value may be followed by the AM/PM designator.

For more information, see the Date and time handling guide.

example E.g. for timeFormats = ['hh:mm:ss.sss'], valid time strings include:

  • 1:33:33
  • 1:33:33.3
  • 1:33:33.33
  • 1:33:33.333
  • 01:33:33
  • 1:33:33 AM
  • 1:33:33 PM
  • 1:33:33 am
  • 1:33:33 pm
  • 1:33:33AM
  • 1:33:33PM

default ['hh:mm', 'hh:mm:ss.sss']

# undoLimit Readonly

• undoLimit: number

Defined in src/Config.ts:598 (opens new window)

Sets the number of elements kept in the undo history.

default 20

# useArrayArithmetic Readonly

• useArrayArithmetic: boolean

Defined in src/Config.ts:533 (opens new window)

When set to true, array arithmetic is enabled globally.

When set to false, array arithmetic is enabled only inside array functions (ARRAYFORMULA, FILTER, and ARRAY_CONSTRAIN).

For more information, see the Arrays guide.

default false

# useColumnIndex Readonly

• useColumnIndex: boolean

Defined in src/Config.ts:588 (opens new window)

When set to true, switches column search strategy from binary search to column index.

Using column index improves efficiency of the VLOOKUP and MATCH functions, but increases memory usage.

When searching with wildcards or regular expressions, column search strategy falls back to binary search (even with useColumnIndex set to true).

default false

# useRegularExpressions Readonly

• useRegularExpressions: boolean

Defined in src/Config.ts:615 (opens new window)

# useStats Readonly

• useStats: boolean

Defined in src/Config.ts:590 (opens new window)

When set to true, enables gathering engine statistics and timings.

Useful for testing and benchmarking.

default false

# useWildcards Readonly

• useWildcards: boolean

Defined in src/Config.ts:616 (opens new window)

# Methods

# getConfig

▸ getConfig(): ConfigParams

Defined in src/Config.ts:755 (opens new window)

Returns: ConfigParams

# mergeConfig

▸ mergeConfig(init: Partial‹ConfigParams›): Config

Defined in src/Config.ts:759 (opens new window)

Parameters:

Name Type
init Partial‹ConfigParams›

Returns: Config

# Object literals

# defaultConfig Static

# ▪ defaultConfig: object

Defined in src/Config.ts:491 (opens new window)

# accentSensitive

• accentSensitive: false = false

Defined in src/Config.ts:492 (opens new window)

# arrayColumnSeparator

• arrayColumnSeparator: "," = ","

Defined in src/Config.ts:510 (opens new window)

# arrayRowSeparator

• arrayRowSeparator: ";" = ";"

Defined in src/Config.ts:511 (opens new window)

# binarySearchThreshold

• binarySearchThreshold: number = 20

Defined in src/Config.ts:493 (opens new window)

# caseFirst

• caseFirst: "lower" = "lower"

Defined in src/Config.ts:496 (opens new window)

# caseSensitive

• caseSensitive: false = false

Defined in src/Config.ts:495 (opens new window)

# chooseAddressMappingPolicy

• chooseAddressMappingPolicy: AlwaysDense‹› = new AlwaysDense()

Defined in src/Config.ts:497 (opens new window)

# currencySymbol

• currencySymbol: string[] = ['$']

Defined in src/Config.ts:494 (opens new window)

# dateFormats

• dateFormats: string[] = ['DD/MM/YYYY', 'DD/MM/YY']

Defined in src/Config.ts:498 (opens new window)

# decimalSeparator

• decimalSeparator: "." = "."

Defined in src/Config.ts:499 (opens new window)

# evaluateNullToZero

• evaluateNullToZero: false = false

Defined in src/Config.ts:500 (opens new window)

# functionArgSeparator

• functionArgSeparator: string = ","

Defined in src/Config.ts:501 (opens new window)

# functionPlugins

• functionPlugins: never[] = []

Defined in src/Config.ts:502 (opens new window)

# ignorePunctuation

• ignorePunctuation: false = false

Defined in src/Config.ts:503 (opens new window)

# ignoreWhiteSpace

• ignoreWhiteSpace: "standard" = "standard"

Defined in src/Config.ts:505 (opens new window)

# language

• language: string = "enGB"

Defined in src/Config.ts:504 (opens new window)

# leapYear1900

• leapYear1900: false = false

Defined in src/Config.ts:507 (opens new window)

# licenseKey

• licenseKey: string = ""

Defined in src/Config.ts:506 (opens new window)

# localeLang

• localeLang: string = "en"

Defined in src/Config.ts:508 (opens new window)

# matchWholeCell

• matchWholeCell: true = true

Defined in src/Config.ts:509 (opens new window)

# maxColumns

• maxColumns: number = 18278

Defined in src/Config.ts:513 (opens new window)

# maxRows

• maxRows: number = 40000

Defined in src/Config.ts:512 (opens new window)

# nullYear

• nullYear: number = 30

Defined in src/Config.ts:514 (opens new window)

# parseDateTime

• parseDateTime: defaultParseToDateTime = defaultParseToDateTime

Defined in src/Config.ts:516 (opens new window)

# precisionEpsilon

• precisionEpsilon: number = 1e-13

Defined in src/Config.ts:517 (opens new window)

# precisionRounding

• precisionRounding: number = 14

Defined in src/Config.ts:518 (opens new window)

# smartRounding

• smartRounding: true = true

Defined in src/Config.ts:519 (opens new window)

# stringifyDateTime

• stringifyDateTime: defaultStringifyDateTime = defaultStringifyDateTime

Defined in src/Config.ts:520 (opens new window)

# stringifyDuration

• stringifyDuration: defaultStringifyDuration = defaultStringifyDuration

Defined in src/Config.ts:521 (opens new window)

# thousandSeparator

• thousandSeparator: "" = ""

Defined in src/Config.ts:523 (opens new window)

# timeFormats

• timeFormats: string[] = ['hh:mm', 'hh:mm:ss.sss']

Defined in src/Config.ts:522 (opens new window)

# undoLimit

• undoLimit: number = 20

Defined in src/Config.ts:524 (opens new window)

# useArrayArithmetic

• useArrayArithmetic: false = false

Defined in src/Config.ts:529 (opens new window)

# useColumnIndex

• useColumnIndex: false = false

Defined in src/Config.ts:527 (opens new window)

# useRegularExpressions

• useRegularExpressions: false = false

Defined in src/Config.ts:525 (opens new window)

# useStats

• useStats: false = false

Defined in src/Config.ts:528 (opens new window)

# useWildcards

• useWildcards: true = true

Defined in src/Config.ts:526 (opens new window)

▪ nullDate: object

Defined in src/Config.ts:515 (opens new window)

  • day: number = 30

  • month: number = 12

  • year: number = 1899