Skip to content

Commit ed7a4c9

Browse files
sequbasequba
authored
Rename the properties of FunctionMetadata and deprecate the old ones (#1558)
* Deprecate FunctionMetadata.arrayFunction in favor of enableArrayArithmeticForArguments * Add unit tests for depracated function metadata * Depracate arraySizeMethod param in favor of sizeOfResultArrayMethod * Add changelog entry * Tweak the docs
1 parent ecaff4b commit ed7a4c9

16 files changed

Lines changed: 213 additions & 66 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
77

88
## [Unreleased]
99

10+
### Changed
11+
12+
- Renamed the `arraySizeMethod` parameter in the `FunctionMetadata` interface to `sizeOfResultArrayMethod`. The `arraySizeMethod` is deprecated and will be removed in one of the next major releases. [#1401](https://github.com/handsontable/hyperformula/issues/1401)
13+
- Renamed the `arrayFunction` parameter in the `FunctionMetadata` interface to `enableArrayArithmeticForArguments`. The `arrayFunction` is deprecated and will be removed in one of the next major releases. [#1401](https://github.com/handsontable/hyperformula/issues/1401)
14+
1015
### Fixed
1116

1217
- Fixed an issue where the `OFFSET` function was ignoring the sheet reference in the provided address. [#1477](https://github.com/handsontable/hyperformula/issues/1477)

‎docs/guide/basic-operations.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ to pass the following parameters:
135135
* Sheet ID
136136
* Starting row
137137
* Number of rows to be moved
138-
* Target row
138+
* [Target row](../api/classes/hyperformula.md#moverows)
139139

140140
This method returns [an array of changed cells](#changes-array).
141141

@@ -149,7 +149,7 @@ const changes = hfInstance.moveRows(0, 0, 1, 2);
149149

150150
You can change the order of rows by using the [`setRowOrder`](../api/classes/hyperformula.md#setroworder) method. You need to pass the following parameters:
151151
* Sheet ID
152-
* New row order
152+
* [New row order](../api/classes/hyperformula.md#setroworder)
153153

154154
This method returns [an array of changed cells](#changes-array).
155155

@@ -196,7 +196,7 @@ You need to pass the following parameters:
196196
* Sheet ID
197197
* Starting column
198198
* Number of columns to be moved
199-
* Target column
199+
* [Target column](../api/classes/hyperformula.md#movecolumns)
200200

201201
This method returns [an array of changed cells](#changes-array).
202202

@@ -210,7 +210,7 @@ const changes = hfInstance.moveColumns(0, 0, 1, 2);
210210

211211
You can change the order of columns by using the [`setColumnOrder`](../api/classes/hyperformula.md#setcolumnorder) method. You need to pass the following parameters:
212212
* Sheet ID
213-
* New column order
213+
* [New column order](../api/classes/hyperformula.md#setcolumnorder)
214214

215215
This method returns [an array of changed cells](#changes-array).
216216

‎docs/guide/built-in-functions.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@ Total number of functions: **{{ $page.functionsCount }}**
6464
| Function ID | Description | Syntax |
6565
|:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------|
6666
| DATE | Returns the specified date as the number of full days since [`nullDate`](../api/interfaces/configparams.md#nulldate). | DATE(Year, Month, Day) |
67-
| DATEDIF | Calculates distance between two dates, in selected units: "D" (days), "M" (months), "Y" (years), "MD" (days ignoring months and years), "YM" (months ignoring years), or "YD" (days ignoring years). | DATEDIF(Date1, Date2, Unit) |
68-
| DATEVALUE | Parses a date string and returns it as the number of full days since [`nullDate`](../api/interfaces/configparams.md#nulldate).<br><br>Accepts formats set by the [`dateFormats`](../api/interfaces/configparams.md#dateformats) option. | DATEVALUE(Datestring) |
67+
| DATEDIF | Calculates distance between two dates.<br>Supported units: "D" (days), "M" (months), "Y" (years), "MD" (days ignoring months and years), "YM" (months ignoring years), or "YD" (days ignoring years). | DATEDIF(Date1, Date2, Unit) |
68+
| DATEVALUE | Parses a date string and returns it as the number of full days since [`nullDate`](../api/interfaces/configparams.md#nulldate).<br>Accepts formats set by the [`dateFormats`](../api/interfaces/configparams.md#dateformats) option. | DATEVALUE(Datestring) |
6969
| DAY | Returns the day of the given date value. | DAY(Number) |
7070
| DAYS | Calculates the difference between two date values. | DAYS(Date2, Date1) |
7171
| DAYS360 | Calculates the difference between two date values in days, in 360-day basis. | DAYS360(Date2, Date1[, Format]) |
@@ -81,7 +81,7 @@ Total number of functions: **{{ $page.functionsCount }}**
8181
| NOW | Returns current date + time as a number of days since [`nullDate`](../api/interfaces/configparams.md#nulldate). | NOW() |
8282
| SECOND | Returns second component of given time. | SECOND(Time) |
8383
| TIME | Returns the number that represents a given time as a fraction of full day. | TIME(Hour, Minute, Second) |
84-
| TIMEVALUE | Parses a time string and returns a number that represents it as a fraction of a full day.<br><br>Accepts formats set by the [`timeFormats`](../api/interfaces/configparams.md#timeformats) option. | TIMEVALUE(Timestring) |
84+
| TIMEVALUE | Parses a time string and returns a number that represents it as a fraction of a full day.<br>Accepts formats set by the [`timeFormats`](../api/interfaces/configparams.md#timeformats) option. | TIMEVALUE(Timestring) |
8585
| TODAY | Returns an integer representing the current date as the number of full days since [`nullDate`](../api/interfaces/configparams.md#nulldate). | TODAY() |
8686
| WEEKDAY | Computes a number between 1-7 representing the day of week. | WEEKDAY(Date, Type) |
8787
| WEEKNUM | Returns a week number that corresponds to the week of year. | WEEKNUM(Date, Type) |
@@ -499,7 +499,7 @@ Total number of functions: **{{ $page.functionsCount }}**
499499
| SPLIT | Divides the provided text using the space character as a separator and returns the substring at the zero-based position specified by the second argument.<br>`SPLIT("Lorem ipsum", 0) -> "Lorem"`<br>`SPLIT("Lorem ipsum", 1) -> "ipsum"` | SPLIT(Text, Index) |
500500
| SUBSTITUTE | Returns string where occurrences of Old_text are replaced by New_text. Replaces only specific occurrence if last parameter is provided. | SUBSTITUTE(Text, Old_text, New_text, [Occurrence]) |
501501
| T | Returns text if given value is text, empty string otherwise. | T(Value) |
502-
| TEXT | Converts a number into text according to a given format.<br><br>By default, accepts the same formats that can be passed to the [`dateFormats`](../api/interfaces/configparams.md#dateformats) option, but can be further customized with the [`stringifyDateTime`](../api/interfaces/configparams.md#stringifydatetime) option. | TEXT(Number, Format) |
502+
| TEXT | Converts a number into text according to a given format.<br>By default, accepts the same formats that can be passed to the [`dateFormats`](../api/interfaces/configparams.md#dateformats) option, but can be further customized with the [`stringifyDateTime`](../api/interfaces/configparams.md#stringifydatetime) option. | TEXT(Number, Format) |
503503
| TRIM | Strips extra spaces from text. | TRIM("Text") |
504504
| UNICHAR | Returns the character created by using provided code point. | UNICHAR(Number) |
505505
| UNICODE | Returns the Unicode code point of a first character of a text. | UNICODE(Text) |

‎docs/guide/compatibility-with-google-sheets.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Still, with the right configuration, you can achieve nearly full compatibility.
1919

2020
Google Sheets has built-in constants (keywords) for the boolean values (`TRUE` and `FALSE`).
2121

22-
To set up HyperFormula in the same way, define `TRUE` and `FALSE` as [named expressions](named-expressions.md), by using HyperFormula's [`TRUE`](built-in-functions.md#logical) and [`FALSE`](built-in-functions.md#logical) functions.
22+
To set up HyperFormula in the same way, define `TRUE` and `FALSE` as [named expressions](named-expressions.md), by using HyperFormula's [`TRUE()`](built-in-functions.md#logical) and [`FALSE()`](built-in-functions.md#logical) functions.
2323

2424
```js
2525
hfInstance.addNamedExpression('TRUE', '=TRUE()');

‎docs/guide/compatibility-with-microsoft-excel.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Related options:
5656

5757
Microsoft Excel has built-in constants (keywords) for the boolean values (`TRUE` and `FALSE`).
5858

59-
To set up HyperFormula in the same way, define `TRUE` and `FALSE` as [named expressions](named-expressions.md), by using HyperFormula's [`TRUE`](built-in-functions.md#logical) and [`FALSE`](built-in-functions.md#logical) functions.
59+
To set up HyperFormula in the same way, define `TRUE` and `FALSE` as [named expressions](named-expressions.md), by using HyperFormula's [`TRUE()`](built-in-functions.md#logical) and [`FALSE()`](built-in-functions.md#logical) functions.
6060

6161
```js
6262
hfInstance.addNamedExpression('TRUE', '=TRUE()');

‎docs/guide/custom-functions.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -258,12 +258,12 @@ export class MyCustomPlugin extends FunctionPlugin {
258258

259259
A function that returns an array will cause the `VALUE!` error unless you also
260260
declare a companion method for the array size. To do that, provide the
261-
`arraySizeMethod` that calculates the size of the result array based on the
261+
`sizeOfResultArrayMethod` that calculates the size of the result array based on the
262262
function arguments and returns an instance of the
263263
[`ArraySize` class](../api/classes/arraysize.md).
264264

265265
::: tip
266-
When you use your custom function in a formula, `arraySizeMethod` is triggered every time the formula changes, but not when the dependencies of the formula change.
266+
When you use your custom function in a formula, `sizeOfResultArrayMethod` is triggered every time the formula changes, but not when the dependencies of the formula change.
267267
This can cause unexpected behavior if the size of the result array depends on the values in the referenced cells.
268268
:::
269269

@@ -286,7 +286,7 @@ export class MyCustomPlugin extends FunctionPlugin {
286286
MyCustomPlugin.implementedFunctions = {
287287
DOUBLE_RANGE: {
288288
method: 'doubleRange',
289-
arraySizeMethod: 'doubleRangeResultArraySize',
289+
sizeOfResultArrayMethod: 'doubleRangeResultArraySize',
290290
parameters: [{ argumentType: FunctionArgumentType.RANGE }],
291291
},
292292
};
@@ -378,15 +378,17 @@ You can set the following options for your function:
378378
|-------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
379379
| `method` (required) | String | Name of the method that implements the custom function logic. |
380380
| `parameters` | Array | Specification of the arguments accepted by the function and their [validation options](#argument-validation-options). |
381-
| `arraySizeMethod` | String | Name of the method that calculates the size of the result array. Not required for functions that never return an array. |
381+
| `sizeOfResultArrayMethod` | String | Name of the method that calculates the size of the result array. Not required for functions that never return an array. |
382382
| `returnNumberType` | String | If the function returns a numeric value, this option indicates how to interpret the returned number.<br/>Possible values: `NUMBER_RAW, NUMBER_DATE, NUMBER_TIME, NUMBER_DATETIME, NUMBER_CURRENCY, NUMBER_PERCENT`.<br/>Default: `NUMBER_RAW` |
383383
| `repeatLastArgs` | Number | For functions with a variable number of arguments: sets how many last arguments can be repeated indefinitely.<br/>Default: `0` |
384384
| `expandRanges` | Boolean | `true`: ranges in the function's arguments are inlined to (possibly multiple) scalar arguments.<br/>Default: `false` |
385385
| `isVolatile` | Boolean | `true`: the function is [volatile](volatile-functions.md).<br/>Default: `false` |
386386
| `isDependentOnSheetStructureChange` | Boolean | `true`: the function gets recalculated with each sheet shape change (e.g., when adding/removing rows or columns).<br/>Default: `false` |
387387
| `doesNotNeedArgumentsToBeComputed` | Boolean | `true`: the function treats reference or range arguments as arguments that don't create dependency (other arguments are properly evaluated).<br/>Default: `false` |
388-
| `arrayFunction` | Boolean | `true`: the function enables the [array arithmetic mode](arrays.md) in its arguments and nested expressions.<br/>Default: `false` |
388+
| `enableArrayArithmeticForArguments` | Boolean | `true`: the function enables the [array arithmetic mode](arrays.md) in its arguments and nested expressions.<br/>Default: `false` |
389389
| `vectorizationForbidden` | Boolean | `true`: the function will never get [vectorized](arrays.md#passing-arrays-to-scalar-functions-vectorization).<br/>Default: `false` |
390+
| `arraySizeMethod` | String | Deprecated; Use `sizeOfResultArrayMethod` instead. |
391+
| `arrayFunction` | Boolean | Deprecated; Use `enableArrayArithmeticForArguments` instead. |
390392

391393
You can set the options in the static `implementedFunctions` property of your
392394
function plugin:
@@ -400,14 +402,14 @@ MyCustomPlugin.implementedFunctions = {
400402
// your argument validation options
401403
},
402404
],
403-
arraySizeMethod: 'myArraySizeMethod',
405+
sizeOfResultArrayMethod: 'myArraySizeMethod',
404406
returnNumberType: 'NUMBER_RAW',
405407
repeatLastArgs: 0,
406408
expandRanges: false,
407409
isVolatile: false,
408410
isDependentOnSheetStructureChange: false,
409411
doesNotNeedArgumentsToBeComputed: false,
410-
arrayFunction: false,
412+
enableArrayArithmeticForArguments: false,
411413
vectorizationForbidden: false,
412414
},
413415
};

0 commit comments

Comments
 (0)