fable 3.1.51 → 3.1.52

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

@@ -0,0 +1,69 @@
+# matrixvectormultiply
+
+Multiplies a matrix by a vector.
+
+## Syntax
+
+```
+matrixvectormultiply(matrix, vector)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `matrix` | Array | 2D array representing the matrix (m×n) |
+| `vector` | Array | 1D array representing the vector (length n) |
+
+## Returns
+
+Array - The resulting vector (length m).
+
+## Description
+
+The `matrixvectormultiply` function multiplies a matrix by a column vector. The vector length must equal the number of columns in the matrix.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Matrix: [[1, 2], [3, 4]]
+// Vector: [5, 6]
+Result = MATRIXVECTORMULTIPLY([[1, 2], [3, 4]], [5, 6])
+// Result: [17, 39]
+// [1*5 + 2*6, 3*5 + 4*6] = [17, 39]
+```
+
+### Transformation
+
+```expression
+// Apply transformation to point
+NewPoint = MATRIXVECTORMULTIPLY(RotationMatrix, Point)
+```
+
+### Linear Combination
+
+```expression
+// Compute linear combination of basis vectors
+Result = MATRIXVECTORMULTIPLY(BasisMatrix, Coefficients)
+```
+
+## Use Cases
+
+- **Linear transformations**: Apply transforms to points
+- **Solving equations**: Part of solving Ax = b
+- **Graphics**: Coordinate transformations
+- **Physics**: Linear operations
+
+## Related Functions
+
+- [matrixmultiply](./matrixmultiply.md) - Matrix-matrix multiplication
+- [matrixtranspose](./matrixtranspose.md) - Transpose matrix
+- [matrixinverse](./matrixinverse.md) - Matrix inverse
+
+## Notes
+
+- Vector treated as column vector
+- Vector length must match matrix columns
+- Uses the Math service's `matrixVectorMultiply` method

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

@@ -0,0 +1,73 @@
+# max
+
+Returns the largest value from a set of numbers.
+
+## Syntax
+
+```
+max(value1, value2, ...)
+max(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Number(s) | Individual numbers or an array of numbers |
+
+## Returns
+
+String - The maximum value from the input set.
+
+## Description
+
+The `max` function finds and returns the largest value from a set of numbers. It can accept individual arguments or an array of values.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = MAX(5, 10, 3, 8)
+// Result: "10"
+```
+
+### With Variables
+
+```expression
+Highest = MAX(Score1, Score2, Score3)
+```
+
+### With Array
+
+```expression
+// Given an array of values
+MaxValue = MAX(AppData.Scores)
+```
+
+### In Expressions
+
+```expression
+// Find the highest price
+MaxPrice = MAX(FLATTEN(AppData.Products.price))
+```
+
+## Use Cases
+
+- **Data analysis**: Find highest values in datasets
+- **Pricing**: Determine maximum price
+- **Scoring**: Find top scores
+- **Limits**: Establish upper bounds
+
+## Related Functions
+
+- [min](./min.md) - Find minimum value
+- [largestinset](./largestinset.md) - Alternative for finding largest
+- [sortset](./sortset.md) - Sort values to find extremes
+- [avg](./avg.md) - Calculate average
+
+## Notes
+
+- Returns result as string (arbitrary precision)
+- Works with the Math service's `maxPrecise` method
+- Handles both individual arguments and arrays

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

@@ -0,0 +1,63 @@
+# mean
+
+Calculates the arithmetic mean (average) of values.
+
+## Syntax
+
+```
+mean(value1, value2, ...)
+mean(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Number(s) | Individual numbers or an array of numbers |
+
+## Returns
+
+String - The arithmetic mean.
+
+## Description
+
+The `mean` function calculates the arithmetic mean (average) of a set of numbers. This is an alias for the `avg` function.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = MEAN(10, 20, 30, 40, 50)
+// Result: "30"
+```
+
+### With Array
+
+```expression
+Average = MEAN(FLATTEN(AppData.Scores))
+```
+
+### Statistics
+
+```expression
+MeanValue = MEAN(DataSet)
+```
+
+## Use Cases
+
+- **Statistics**: Central tendency
+- **Analysis**: Average values
+- **Reporting**: Mean calculations
+
+## Related Functions
+
+- [avg](./avg.md) - Same function (alias)
+- [median](./median.md) - Middle value
+- [mode](./mode.md) - Most frequent value
+
+## Notes
+
+- Alias for `avg` function
+- Uses the Math service's `meanPrecise` method
+- Returns result as string for precision

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

@@ -0,0 +1,79 @@
+# median
+
+Returns the middle value of a sorted set.
+
+## Syntax
+
+```
+median(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | An array of numeric values |
+
+## Returns
+
+String - The median value.
+
+## Description
+
+The `median` function returns the middle value when all values are sorted. For an odd number of values, it returns the exact middle value. For an even number of values, it returns the average of the two middle values.
+
+## Examples
+
+### Odd Number of Values
+
+```expression
+TotalCost = MEDIAN(ItemCosts)
+// With ItemCosts = [100, 200, 50, 45, 5]
+// Sorted: [5, 45, 50, 100, 200]
+// Result: "50" (the middle value)
+```
+
+### Even Number of Values
+
+```expression
+Result = median([1, 2, 3, 4])
+// Sorted: [1, 2, 3, 4]
+// Middle values: 2 and 3
+// Result: "2.5" (average of 2 and 3)
+```
+
+### With Variable Data
+
+```expression
+MedianPrice = MEDIAN(Prices)
+// Finds the middle price point
+```
+
+## Use Cases
+
+- **Statistics**: Robust measure of central tendency
+- **Real estate**: Median home prices (less affected by outliers)
+- **Income analysis**: Median income (avoids skew from extremes)
+- **Quality metrics**: Median response time
+
+## Advantages Over Mean
+
+The median is more robust than the mean for skewed data:
+
+```expression
+// Example: [1, 2, 3, 4, 1000]
+Mean = 202     // Heavily influenced by 1000
+Median = 3     // Better represents typical value
+```
+
+## Related Functions
+
+- [avg](./avg.md) / [mean](./mean.md) - Arithmetic average
+- [mode](./mode.md) - Most frequent value
+- [min](./min.md) / [max](./max.md) - Extremes
+
+## Notes
+
+- Values are automatically sorted before finding median
+- Uses arbitrary precision arithmetic
+- Works with the Math service's `medianPrecise` method

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

@@ -0,0 +1,73 @@
+# min
+
+Returns the smallest value from a set of numbers.
+
+## Syntax
+
+```
+min(value1, value2, ...)
+min(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Number(s) | Individual numbers or an array of numbers |
+
+## Returns
+
+String - The minimum value from the input set.
+
+## Description
+
+The `min` function finds and returns the smallest value from a set of numbers. It can accept individual arguments or an array of values.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = MIN(5, 10, 3, 8)
+// Result: "3"
+```
+
+### With Variables
+
+```expression
+Lowest = MIN(Price1, Price2, Price3)
+```
+
+### With Array
+
+```expression
+// Given an array of values
+MinValue = MIN(AppData.Temperatures)
+```
+
+### Finding Range
+
+```expression
+// Calculate the range of values
+Range = MAX(Values) - MIN(Values)
+```
+
+## Use Cases
+
+- **Data analysis**: Find lowest values in datasets
+- **Pricing**: Determine minimum price
+- **Quality control**: Find minimum measurements
+- **Limits**: Establish lower bounds
+
+## Related Functions
+
+- [max](./max.md) - Find maximum value
+- [smallestinset](./smallestinset.md) - Alternative for finding smallest
+- [sortset](./sortset.md) - Sort values to find extremes
+- [avg](./avg.md) - Calculate average
+
+## Notes
+
+- Returns result as string (arbitrary precision)
+- Works with the Math service's `minPrecise` method
+- Handles both individual arguments and arrays

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

@@ -0,0 +1,66 @@
+# mode
+
+Returns the most frequently occurring value in a dataset.
+
+## Syntax
+
+```
+mode(value1, value2, ...)
+mode(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Number(s) | Individual numbers or an array of numbers |
+
+## Returns
+
+String - The value that appears most frequently.
+
+## Description
+
+The `mode` function finds and returns the most frequently occurring value in a dataset. If multiple values have the same highest frequency, it returns one of them.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = MODE(1, 2, 2, 3, 3, 3, 4)
+// Result: "3" (appears 3 times)
+```
+
+### With Array
+
+```expression
+// Find most common value
+MostCommon = MODE(AppData.Ratings)
+```
+
+### Survey Data
+
+```expression
+// Find most selected option
+PopularChoice = MODE(FLATTEN(AppData.Survey.response))
+```
+
+## Use Cases
+
+- **Survey analysis**: Find most common response
+- **Quality control**: Identify most frequent measurement
+- **Market research**: Most popular choice
+- **Statistics**: Central tendency analysis
+
+## Related Functions
+
+- [median](./median.md) - Middle value
+- [avg](./avg.md) - Arithmetic mean
+- [distributionhistogram](./distributionhistogram.md) - Full frequency distribution
+
+## Notes
+
+- Returns result as string
+- Works with the Math service's `modePrecise` method
+- For multimodal datasets, returns one of the modes

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

@@ -0,0 +1,66 @@
+# objectkeystoarray
+
+Extracts all keys from an object as an array.
+
+## Syntax
+
+```
+objectkeystoarray(object)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Object | The object to extract keys from |
+
+## Returns
+
+Array - Array of all keys from the object.
+
+## Description
+
+The `objectkeystoarray` function returns all property names (keys) from an object as an array. This is useful for iterating over object properties or analyzing object structure.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given object: { name: "John", age: 30, city: "NYC" }
+Result = OBJECTKEYSTOARRAY(Person)
+// Result: ["name", "age", "city"]
+```
+
+### With Histogram
+
+```expression
+// Get all category names from histogram
+Categories = OBJECTKEYSTOARRAY(CategoryCounts)
+```
+
+### Dynamic Property Access
+
+```expression
+Keys = OBJECTKEYSTOARRAY(ConfigObject)
+// Use keys for iteration or display
+```
+
+## Use Cases
+
+- **Object inspection**: List all properties
+- **Dynamic iteration**: Process unknown objects
+- **Validation**: Check expected properties exist
+- **Display**: Show object structure
+
+## Related Functions
+
+- [objectvaluestoarray](./objectvaluestoarray.md) - Extract values instead
+- [getvalue](./getvalue.md) - Get specific value by key
+- [flatten](./flatten.md) - Flatten arrays
+
+## Notes
+
+- Returns array of strings (key names)
+- Order may not be guaranteed
+- Uses the Math service's `objectKeysToArray` method

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

@@ -0,0 +1,65 @@
+# objectvaluessortbyexternalobjectarray
+
+Sorts object values based on an external ordering array.
+
+## Syntax
+
+```
+objectvaluessortbyexternalobjectarray(object, orderArray, keyProperty)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Object | Object to sort values from |
+| `orderArray` | Array | Array defining the sort order |
+| `keyProperty` | String | Property to match for ordering |
+
+## Returns
+
+Array - Values sorted according to external order.
+
+## Description
+
+The `objectvaluessortbyexternalobjectarray` function extracts values from an object and sorts them based on the order defined by an external array.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Data = { 'a': 10, 'b': 20, 'c': 30 }
+Order = [{ key: 'c' }, { key: 'a' }, { key: 'b' }]
+
+Result = OBJECTVALUESSORTBYEXTERNALOBJECTARRAY(Data, Order, "key")
+// Result: [30, 10, 20] (sorted: c, a, b)
+```
+
+### Custom Display Order
+
+```expression
+// Sort categories by custom priority
+CategoryData = { 'urgent': 5, 'normal': 10, 'low': 2 }
+Priority = [{ name: 'urgent' }, { name: 'normal' }, { name: 'low' }]
+
+Sorted = OBJECTVALUESSORTBYEXTERNALOBJECTARRAY(CategoryData, Priority, "name")
+```
+
+## Use Cases
+
+- **Custom ordering**: Sort by external criteria
+- **Display order**: Match specific sort order
+- **Prioritization**: Order by priority list
+- **Report generation**: Consistent ordering
+
+## Related Functions
+
+- [sorthistogram](./sorthistogram.md) - Sort by values
+- [sorthistogrambykeys](./sorthistogrambykeys.md) - Sort alphabetically
+- [objectvaluestoarray](./objectvaluestoarray.md) - Extract values
+
+## Notes
+
+- Maintains relationship between keys and values
+- Uses the Math service

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

@@ -0,0 +1,67 @@
+# objectvaluestoarray
+
+Extracts all values from an object as an array.
+
+## Syntax
+
+```
+objectvaluestoarray(object)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Object | The object to extract values from |
+
+## Returns
+
+Array - Array of all values from the object.
+
+## Description
+
+The `objectvaluestoarray` function returns all property values from an object as an array. This is useful for aggregating values without needing the keys.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given object: { name: "John", age: 30, city: "NYC" }
+Result = OBJECTVALUESTOARRAY(Person)
+// Result: ["John", 30, "NYC"]
+```
+
+### Sum Histogram Values
+
+```expression
+// Get all counts from histogram and sum them
+Values = OBJECTVALUESTOARRAY(CategoryCounts)
+Total = SUM(Values)
+```
+
+### Aggregate Processing
+
+```expression
+AllValues = OBJECTVALUESTOARRAY(DataObject)
+Average = AVG(AllValues)
+```
+
+## Use Cases
+
+- **Aggregation**: Sum or average all values
+- **Collection**: Get all values regardless of key
+- **Analysis**: Process all object values
+- **Display**: List all values
+
+## Related Functions
+
+- [objectkeystoarray](./objectkeystoarray.md) - Extract keys instead
+- [flatten](./flatten.md) - Flatten nested arrays
+- [sum](./sum.md) - Sum the extracted values
+
+## Notes
+
+- Returns array of values (any type)
+- Order corresponds to key order
+- Uses the Math service's `objectValuesToArray` method

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

@@ -0,0 +1,75 @@
+# percent
+
+Calculates what percentage one value is of another.
+
+## Syntax
+
+```
+percent(part, whole)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `part` | Number | The partial value |
+| `whole` | Number | The total value |
+
+## Returns
+
+String - The percentage as a decimal (multiply by 100 for traditional percentage).
+
+## Description
+
+The `percent` function calculates what percentage the first value is of the second value. The result is returned as a decimal ratio.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = PERCENT(25, 100)
+// Result: "0.25" (25%)
+```
+
+### Sales Percentage
+
+```expression
+// What percentage of goal was achieved?
+Achievement = PERCENT(ActualSales, SalesGoal)
+```
+
+### With Multiplication for Display
+
+```expression
+// Get traditional percentage value
+PercentValue = PERCENT(50, 200) * 100
+// Result: 25 (25%)
+```
+
+### Completion Rate
+
+```expression
+// Calculate completion percentage
+CompletionRate = PERCENT(CompletedTasks, TotalTasks)
+```
+
+## Use Cases
+
+- **Business metrics**: Calculate achievement percentages
+- **Data analysis**: Proportion calculations
+- **Progress tracking**: Completion percentages
+- **Financial reporting**: Ratio analysis
+
+## Related Functions
+
+- [compare](./compare.md) - Compare two values
+- [round](./round.md) - Round percentage results
+- [tofixed](./tofixed.md) - Format percentage with decimals
+
+## Notes
+
+- Returns decimal, not percentage (0.25 not 25%)
+- Multiply by 100 for traditional percentage display
+- Uses the Math service's `percentPrecise` method
+- Returns result as string for precision