fable 3.1.51 → 3.1.52

package/docs/services/expression-parser-functions/floor.md

@@ -0,0 +1,70 @@
+# floor
+
+Returns the largest integer less than or equal to a number.
+
+## Syntax
+
+```
+floor(value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Number/String | The value to floor |
+
+## Returns
+
+String - The largest integer less than or equal to the input.
+
+## Description
+
+The `floor` function rounds a number down to the nearest integer. For positive numbers, this truncates the decimal portion. For negative numbers, it rounds away from zero (more negative).
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = floor(3.7)
+// Result: "3"
+
+Result = floor(3.2)
+// Result: "3"
+
+Result = floor(3.0)
+// Result: "3"
+
+Result = floor(-2.3)
+// Result: "-3" (rounds toward negative infinity)
+```
+
+### With Expressions
+
+```expression
+// Get the integer part of a calculation
+WholeUnits = floor(TotalAmount / UnitPrice)
+
+// Determine array index from position
+Index = floor(Position / ItemSize)
+```
+
+## Use Cases
+
+- **Integer division**: Getting the quotient without remainder
+- **Array indexing**: Converting continuous values to discrete indices
+- **Pagination**: Calculating page numbers
+- **Time calculations**: Converting decimal hours to whole hours
+
+## Related Functions
+
+- [ceil](./ceil.md) - Round up (ceiling)
+- [round](./round.md) - Round to nearest
+- [tofixed](./tofixed.md) - Format to fixed decimal places
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Returns a string representation
+- For negative numbers, floor(-2.3) = -3, not -2

package/docs/services/expression-parser-functions/gaussianelimination.md

@@ -0,0 +1,75 @@
+# gaussianelimination
+
+Solves a system of linear equations using Gaussian elimination.
+
+## Syntax
+
+```
+gaussianelimination(coefficientMatrix, constantVector)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `coefficientMatrix` | Array | Matrix of coefficients (n×n) |
+| `constantVector` | Array | Vector of constants (length n) |
+
+## Returns
+
+Array - Solution vector.
+
+## Description
+
+The `gaussianelimination` function solves a system of linear equations Ax = b using Gaussian elimination with back substitution.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Solve:
+// 2x + y = 5
+// x + 3y = 10
+
+A = [[2, 1], [1, 3]]
+b = [5, 10]
+Solution = GAUSSIANELIMINATION(A, b)
+// Result: [1, 3] meaning x=1, y=3
+```
+
+### 3x3 System
+
+```expression
+// Three equations with three unknowns
+Coefficients = [[1, 2, 1], [2, 6, 1], [1, 1, 4]]
+Constants = [2, 7, 3]
+Solution = GAUSSIANELIMINATION(Coefficients, Constants)
+```
+
+### Engineering Problem
+
+```expression
+// Solve circuit/structure equations
+Values = GAUSSIANELIMINATION(SystemMatrix, LoadVector)
+```
+
+## Use Cases
+
+- **Engineering**: Structural analysis
+- **Physics**: Equilibrium problems
+- **Economics**: Input-output models
+- **Optimization**: Constraint systems
+
+## Related Functions
+
+- [matrixinverse](./matrixinverse.md) - Alternative via inverse
+- [matrixmultiply](./matrixmultiply.md) - Verify solutions
+- [leastsquares](./leastsquares.md) - Overdetermined systems
+
+## Notes
+
+- Efficient for dense systems
+- Handles n×n systems
+- May have numerical precision limits
+- Uses the Math service's `gaussianElimination` method

package/docs/services/expression-parser-functions/generatearrayofobjectsfromsets.md

@@ -0,0 +1,70 @@
+# generatearrayofobjectsfromsets
+
+Generates an array of objects from parallel arrays.
+
+## Syntax
+
+```
+generatearrayofobjectsfromsets(keys, valueArrays)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `keys` | Array | Array of property names |
+| `valueArrays` | Array | Array of value arrays |
+
+## Returns
+
+Array - Array of objects with properties from keys and values from arrays.
+
+## Description
+
+The `generatearrayofobjectsfromsets` function creates an array of objects by combining property names with parallel arrays of values. Each object gets its properties from corresponding positions in the value arrays.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Keys = ["name", "age"]
+Names = ["Alice", "Bob", "Carol"]
+Ages = [25, 30, 35]
+
+Result = GENERATEARRAYOFOBJECTSFROMSETS(Keys, [Names, Ages])
+// Result: [
+//   { name: "Alice", age: 25 },
+//   { name: "Bob", age: 30 },
+//   { name: "Carol", age: 35 }
+// ]
+```
+
+### From CSV Columns
+
+```expression
+Headers = ["id", "product", "price"]
+Column1 = ["001", "002", "003"]
+Column2 = ["Widget", "Gadget", "Thing"]
+Column3 = [9.99, 19.99, 4.99]
+
+Records = GENERATEARRAYOFOBJECTSFROMSETS(Headers, [Column1, Column2, Column3])
+```
+
+## Use Cases
+
+- **Data transformation**: Convert columnar to row data
+- **CSV processing**: Build objects from columns
+- **Parallel arrays**: Combine related arrays
+- **Data generation**: Create structured data
+
+## Related Functions
+
+- [createvalueobjectbyhashes](./createvalueobjectbyhashes.md) - Create single object
+- [objectkeystoarray](./objectkeystoarray.md) - Extract keys
+- [flatten](./flatten.md) - Flatten arrays
+
+## Notes
+
+- Value arrays should have same length
+- Uses the Math service's `generateArrayOfObjectsFromSets` method

package/docs/services/expression-parser-functions/getvalue.md

@@ -0,0 +1,90 @@
+# getvalue
+
+Retrieves a value from application state using a hash/path address.
+
+## Syntax
+
+```
+getvalue(path)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | String | Dot-notation path to the value (in quotes) |
+
+## Returns
+
+The value at the specified path, or `undefined` if not found.
+
+## Description
+
+The `getvalue` function retrieves values from the Fable application state (AppData, services, etc.) using a dot-notation path. This allows expressions to access data stored elsewhere in the application.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Access a simple value
+PitSize = getvalue("AppData.Pit")
+// If AppData.Pit = "Bottomless"
+// Result: "Bottomless"
+```
+
+### Array Access
+
+```expression
+// Access array elements
+FirstStudent = GETVALUE("AppData.Students[0]")
+// If AppData.Students = ["Kim", "Jim", "Joan Jett", "Tank Girl"]
+// Result: "Kim"
+
+ThirdStudent = GETVALUE("AppData.Students[2]")
+// Result: "Joan Jett"
+```
+
+### Nested Object Access
+
+```expression
+// Access nested properties
+CityName = getvalue("AppData.Cities[0].city")
+// If AppData.Cities[0] = { city: "New York", state: "New York" }
+// Result: "New York"
+```
+
+### With Null Coalescence Assignment
+
+```expression
+// Only assign if target doesn't already have a value
+Name ?= GETVALUE("AppData.Students[0]")
+// Sets Name to "Kim" only if Name is currently empty/undefined
+```
+
+### In Complex Expressions
+
+```expression
+// Combine with other functions
+Histogram = aggregationhistogrambyobject(getvalue("AppData.Teams"), "States", "Score")
+```
+
+## Use Cases
+
+- **Configuration access**: Reading application settings
+- **Data lookup**: Retrieving stored values
+- **Dynamic references**: Access paths determined at runtime
+- **Cross-module data**: Sharing data between components
+
+## Related Functions
+
+- [getvaluearray](./getvaluearray.md) - Get array of values
+- [getvalueobject](./getvalueobject.md) - Get object of values
+
+## Notes
+
+- The path must be quoted (it's a string)
+- Accesses `fable.Utility.getInternalValueByHash`
+- Returns `undefined` if the path doesn't exist
+- Array indices use bracket notation: `[0]`, `[1]`, etc.
+- Works with any data stored on the Fable instance

package/docs/services/expression-parser-functions/getvaluearray.md

@@ -0,0 +1,64 @@
+# getvaluearray
+
+Gets a value from an array by index.
+
+## Syntax
+
+```
+getvaluearray(array, index)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to retrieve from |
+| `index` | Number | Zero-based index |
+
+## Returns
+
+Any - The value at the specified index.
+
+## Description
+
+The `getvaluearray` function retrieves a value from an array at the specified index. Uses zero-based indexing.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = GETVALUEARRAY(["a", "b", "c", "d"], 2)
+// Result: "c" (index 2, third element)
+```
+
+### First Element
+
+```expression
+First = GETVALUEARRAY(Items, 0)
+```
+
+### With Variable Index
+
+```expression
+SelectedItem = GETVALUEARRAY(Options, SelectedIndex)
+```
+
+## Use Cases
+
+- **Random selection**: Get random array element
+- **Indexed access**: Retrieve by position
+- **Dynamic selection**: Variable-based selection
+- **Data extraction**: Get specific element
+
+## Related Functions
+
+- [getvalue](./getvalue.md) - Get property from object
+- [getvalueobject](./getvalueobject.md) - Get from object by key
+- [slice](./slice.md) - Get range of elements
+
+## Notes
+
+- Zero-based indexing
+- Returns undefined for out-of-bounds
+- Uses the Logic service's `getValueArray` method

package/docs/services/expression-parser-functions/getvalueobject.md

@@ -0,0 +1,67 @@
+# getvalueobject
+
+Gets a value from an object by key.
+
+## Syntax
+
+```
+getvalueobject(object, key)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Object | The object to retrieve from |
+| `key` | String | The property key |
+
+## Returns
+
+Any - The value of the specified property.
+
+## Description
+
+The `getvalueobject` function retrieves a value from an object using a string key. This is useful for dynamic property access.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given object: { name: "John", age: 30 }
+Result = GETVALUEOBJECT(Person, "name")
+// Result: "John"
+```
+
+### Dynamic Key
+
+```expression
+PropertyName = "email"
+Value = GETVALUEOBJECT(User, PropertyName)
+```
+
+### Histogram Access
+
+```expression
+// Get count for specific category
+Count = GETVALUEOBJECT(CategoryCounts, "Electronics")
+```
+
+## Use Cases
+
+- **Dynamic access**: Access property by variable name
+- **Histogram lookup**: Get value by key
+- **Configuration**: Access settings by name
+- **Data extraction**: Get nested values
+
+## Related Functions
+
+- [getvalue](./getvalue.md) - Get from data state
+- [getvaluearray](./getvaluearray.md) - Get from array by index
+- [objectkeystoarray](./objectkeystoarray.md) - Get all keys
+
+## Notes
+
+- String key access
+- Returns undefined for missing keys
+- Uses the Logic service's `getValueObject` method

package/docs/services/expression-parser-functions/if.md

@@ -0,0 +1,109 @@
+# if
+
+Performs a conditional comparison and returns one of two values based on the result.
+
+## Syntax
+
+```
+if(left, operator, right, onTrue, onFalse)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `left` | Any | Left value to compare |
+| `operator` | String | Comparison operator |
+| `right` | Any | Right value to compare |
+| `onTrue` | Any | Value returned if comparison is true |
+| `onFalse` | Any | Value returned if comparison is false |
+
+### Comparison Operators
+
+| Operator | Alias | Description |
+|----------|-------|-------------|
+| `<` | `LT` | Less than |
+| `<=` | `LTE` | Less than or equal |
+| `>` | `GT` | Greater than |
+| `>=` | `GTE` | Greater than or equal |
+| `==` | | Loose equality (with small tolerance for numbers) |
+| `===` | | Strict equality |
+
+## Returns
+
+The `onTrue` value if the comparison is true, otherwise `onFalse`.
+
+## Description
+
+The `if` function evaluates a condition and returns different values based on the result. It supports both numeric comparisons (with arbitrary precision) and string comparisons.
+
+## Examples
+
+### Basic Comparison
+
+```expression
+GTE = If(AppData.Cities[0].latitude, "<", "50", "west", "east")
+// If latitude < 50, returns "west", otherwise "east"
+// Result: "west"
+```
+
+### String Comparison
+
+```expression
+Equals = If(AppData.Cities[0].city, "==", "New York", "yes", "no")
+// Result: "yes"
+```
+
+### Numeric Equality with Tolerance
+
+```expression
+// Uses small epsilon for floating point comparison
+EpsilonEquals = If("1.0000000001", "==", "1", "yes", "no")
+// Result: "yes" (within tolerance)
+
+// Strict equality requires exact match
+PreciseEquals = If("1.0000000001", "===", "1", "yes", "no")
+// Result: "no" (not exactly equal)
+```
+
+### Computed Return Values
+
+```expression
+// Return values can be expressions
+Computed = If(AppData.Cities[0].latitude, "<", "50", AppData.Cities[0].latitude + 25, AppData.Cities[0].latitude - 25)
+```
+
+### Nested Conditions
+
+```expression
+// Chain conditions for multiple outcomes
+Grade = IF(Score, ">=", 90, "A", IF(Score, ">=", 80, "B", IF(Score, ">=", 70, "C", "F")))
+```
+
+### In Complex Expressions
+
+```expression
+// Conditional within larger expressions
+WetCount = IF(DryCount, "<=", 30, DryCount, WetCountIntermediate)
+
+// Selecting between computed values
+CombinedValues = MAP VAR dry FROM DryValues VAR wet FROM WetValues VAR x from XValues : IF(x, "LTE", Chart.OptimalMoistureContent, dry, wet)
+```
+
+## Use Cases
+
+- **Data validation**: Check if values meet criteria
+- **Conditional formatting**: Return different display values
+- **Business logic**: Apply different rules based on conditions
+- **Threshold checks**: Compare against limits
+
+## Related Functions
+
+- [when](./when.md) - Truthy check (simpler conditional)
+
+## Notes
+
+- Uses arbitrary precision for numeric comparisons
+- The `==` operator uses a tolerance of 0.000001 for numeric values
+- The `===` operator performs exact comparison for numbers
+- String comparisons are case-sensitive

package/docs/services/expression-parser-functions/iterativeseries.md

@@ -0,0 +1,107 @@
+# iterativeseries
+
+Performs iterative mathematical operations on set elements.
+
+## Syntax
+
+```
+iterativeseries(array, valueProperty, resultProperty, startValue, operation)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of objects to process |
+| `valueProperty` | String | Property name containing values |
+| `resultProperty` | String | Property name to store results |
+| `startValue` | Number/String | Initial value for the series |
+| `operation` | String | Operation to perform ("add", "subtract", "multiply", "divide") |
+
+## Returns
+
+Array - The input array with results added to each object.
+
+## Description
+
+The `iterativeseries` function performs a specified mathematical operation iteratively across an array of objects. It starts with an initial value and applies the operation with each element's value, storing the cumulative result.
+
+## Examples
+
+### Cumulative Addition
+
+```expression
+Result = ITERATIVESERIES(Values, "Value", "Resultant", 1, "add")
+
+// Input:
+Values = [
+    { Value: 10 },
+    { Value: 20 },
+    { Value: 5 }
+]
+
+// Output:
+// [
+//     { Value: 10, Resultant: "10" },   // 1 - 1 + 10 = 10
+//     { Value: 20, Resultant: "30" },   // 10 + 20 = 30
+//     { Value: 5, Resultant: "35" }     // 30 + 5 = 35
+// ]
+```
+
+### Running Product
+
+```expression
+Result = ITERATIVESERIES(Data, "Factor", "Product", 1, "multiply")
+
+// Input:
+Data = [
+    { Factor: 2 },
+    { Factor: 3 },
+    { Factor: 4 }
+]
+
+// Output: Products: 2, 6, 24
+```
+
+### Depreciation Calculation
+
+```expression
+// Calculate declining balance
+Assets = [
+    { DepreciationRate: 0.1 },
+    { DepreciationRate: 0.1 },
+    { DepreciationRate: 0.1 }
+]
+
+// Start with initial value and multiply by (1 - rate) each period
+Result = ITERATIVESERIES(Assets, "DepreciationRate", "RemainingValue", 1000, "custom")
+```
+
+## Available Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `"add"` | Cumulative addition |
+| `"subtract"` | Cumulative subtraction |
+| `"multiply"` | Cumulative multiplication |
+| `"divide"` | Cumulative division |
+
+## Use Cases
+
+- **Financial calculations**: Compound interest, depreciation
+- **Inventory**: Running balance calculations
+- **Statistics**: Cumulative products, geometric series
+- **Process modeling**: Sequential transformations
+
+## Related Functions
+
+- [cumulativesummation](./cumulativesummation.md) - Specifically for cumulative sums
+- [subtractingsummation](./subtractingsummation.md) - Specifically for subtracting
+- [sum](./sum.md) - Simple sum of all values
+
+## Notes
+
+- Modifies the input array by adding the result property
+- Uses arbitrary precision arithmetic
+- The start value is used as the initial accumulator
+- Works with the Math service's `iterativeSeries` method