fable 3.1.51 → 3.1.52

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

@@ -0,0 +1,85 @@
+# sqrt
+
+Calculates the square root of a number with arbitrary precision.
+
+## Syntax
+
+```
+sqrt(value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Number/String | The value to calculate the square root of |
+
+## Returns
+
+String - The square root of the input value with arbitrary precision.
+
+## Description
+
+The `sqrt` function computes the square root of a numeric value. It uses arbitrary precision arithmetic, so results are accurate for very large or very precise numbers.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = sqrt(16)
+// Result: "4"
+
+Result = sqrt(2)
+// Result: "1.41421356237309504880168872420969807856967187537694..."
+
+Result = sqrt(100)
+// Result: "10"
+```
+
+### In Complex Expressions
+
+```expression
+// Pythagorean theorem: c = sqrt(a² + b²)
+Hypotenuse = sqrt(X^2 + Y^2)
+// With X=3, Y=4: Result: "5"
+
+// Distance formula
+Distance = sqrt((X2 - X1)^2 + (Y2 - Y1)^2)
+```
+
+### With Variables
+
+```expression
+Result = sqrt(100 * (C + 30)) + sin(Depth - Width) / 10
+// With C=-13, Depth=100.203, Width=10.5
+// Result: "41.32965489638783839821"
+```
+
+### Nested in Other Functions
+
+```expression
+Result = 1.5 * sqrt(8 * 2.423782342^2) / 10
+// Result: "1.02832375808904701855"
+
+Result = 1 * sqrt(16)
+// Result: "4"
+```
+
+## Use Cases
+
+- **Geometry calculations**: Computing diagonals, distances, and hypotenuses
+- **Statistical analysis**: Used in standard deviation calculations
+- **Physics formulas**: Many physics equations involve square roots
+- **Financial calculations**: Volatility and other risk metrics
+
+## Related Functions
+
+- [abs](./abs.md) - Absolute value
+- [pow](./pow.md) - Power/exponentiation (use `^` operator)
+
+## Notes
+
+- Returns arbitrary precision results as strings
+- Input can be a number or a numeric string
+- Works with the Math service's `sqrtPrecise` method internally

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

@@ -0,0 +1,81 @@
+# stdev / stdeva
+
+Calculates the sample standard deviation of a set of values.
+
+## Syntax
+
+```
+stdev(array)
+stdeva(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | An array of numeric values |
+
+## Returns
+
+String - The sample standard deviation.
+
+## Description
+
+The `stdev` and `stdeva` functions calculate the sample standard deviation, which measures how spread out the values are from the mean. Sample standard deviation divides by (n-1) rather than n, providing an unbiased estimate when working with a sample of a larger population.
+
+## Examples
+
+### Basic Usage
+
+```expression
+StDev = STDEV(Values)
+// With Values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+// Result: approximately "3.3166"
+```
+
+### Financial Risk Analysis
+
+```expression
+// Calculate volatility of returns
+Volatility = STDEV(DailyReturns)
+```
+
+### Quality Control
+
+```expression
+// Measure variation in measurements
+ProcessVariation = STDEV(Measurements)
+```
+
+## Formula
+
+Sample Standard Deviation (s):
+```
+s = sqrt(Σ(xi - x̄)² / (n - 1))
+```
+
+Where:
+- xi = each value
+- x̄ = mean of all values
+- n = number of values
+
+## Use Cases
+
+- **Finance**: Measuring volatility and risk
+- **Quality control**: Process variation analysis
+- **Research**: Data variability measurement
+- **Statistics**: Confidence intervals, hypothesis testing
+
+## Related Functions
+
+- [stdevp](./stdevp.md) - Population standard deviation
+- [var](./var.md) - Sample variance
+- [varp](./varp.md) - Population variance
+- [avg](./avg.md) / [mean](./mean.md) - Average
+
+## Notes
+
+- `stdev` and `stdeva` are aliases
+- Uses (n-1) in denominator (Bessel's correction)
+- For population data, use [stdevp](./stdevp.md) instead
+- Works with the Math service's `standardDeviationPrecise` method

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

@@ -0,0 +1,58 @@
+# stdeva
+
+Calculates standard deviation including text and boolean values.
+
+## Syntax
+
+```
+stdeva(value1, value2, ...)
+stdeva(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Any | Values including numbers, text, and booleans |
+
+## Returns
+
+String - The standard deviation including converted text/boolean values.
+
+## Description
+
+The `stdeva` function calculates sample standard deviation while treating text as 0 and boolean TRUE as 1, FALSE as 0. This is similar to Excel's STDEVA function.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = STDEVA(1, 2, true, false, "text")
+// Text = 0, true = 1, false = 0
+```
+
+### With Mixed Data
+
+```expression
+StdDev = STDEVA(MixedDataArray)
+```
+
+## Use Cases
+
+- **Mixed data**: Standard deviation with non-numeric values
+- **Spreadsheet compatibility**: Excel-like behavior
+- **Survey data**: Handle mixed responses
+
+## Related Functions
+
+- [stdev](./stdev.md) - Numeric-only standard deviation
+- [stdevp](./stdevp.md) - Population standard deviation
+- [vara](./vara.md) - Variance with text/boolean
+
+## Notes
+
+- Text values treated as 0
+- TRUE = 1, FALSE = 0
+- Uses sample formula (n-1)
+- Uses the Math service's `stdevaPrecise` method

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

@@ -0,0 +1,83 @@
+# stdevp
+
+Calculates the population standard deviation of a set of values.
+
+## Syntax
+
+```
+stdevp(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | An array of numeric values |
+
+## Returns
+
+String - The population standard deviation.
+
+## Description
+
+The `stdevp` function calculates the population standard deviation, which measures how spread out the values are from the mean. Population standard deviation divides by n (not n-1), and is used when you have data for the entire population, not just a sample.
+
+## Examples
+
+### Basic Usage
+
+```expression
+StDevP = STDEVP(Values)
+// With Values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+// Result: approximately "3.1623"
+```
+
+### Comparing Sample vs Population
+
+```expression
+// Sample standard deviation (divides by n-1)
+SampleStDev = STDEV(Values)   // ≈ 3.3166
+
+// Population standard deviation (divides by n)
+PopStDev = STDEVP(Values)     // ≈ 3.1623
+```
+
+## Formula
+
+Population Standard Deviation (σ):
+```
+σ = sqrt(Σ(xi - μ)² / n)
+```
+
+Where:
+- xi = each value
+- μ = population mean
+- n = population size
+
+## When to Use STDEVP vs STDEV
+
+| Use STDEVP when... | Use STDEV when... |
+|-------------------|-------------------|
+| You have the entire population | You have a sample |
+| Census data | Survey data |
+| All possible outcomes | Subset of outcomes |
+
+## Use Cases
+
+- **Census data**: When you have measurements from everyone
+- **Theoretical analysis**: Known distributions
+- **Complete datasets**: When no inference is needed
+
+## Related Functions
+
+- [stdev](./stdev.md) - Sample standard deviation
+- [var](./var.md) - Sample variance
+- [varp](./varp.md) - Population variance
+- [avg](./avg.md) / [mean](./mean.md) - Average
+
+## Notes
+
+- Uses n in denominator (no Bessel's correction)
+- Results are slightly smaller than sample standard deviation
+- For sample data, use [stdev](./stdev.md) instead
+- Works with the Math service's `populationStandardDeviationPrecise` method

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

@@ -0,0 +1,66 @@
+# stringcountsegments
+
+Counts the number of segments in a string when split by a delimiter.
+
+## Syntax
+
+```
+stringcountsegments(text, delimiter)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | String | The string to count segments in |
+| `delimiter` | String | The delimiter to split by |
+
+## Returns
+
+String - The number of segments.
+
+## Description
+
+The `stringcountsegments` function splits a string by a delimiter and returns the count of resulting segments.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = STRINGCOUNTSEGMENTS("a,b,c,d,e", ",")
+// Result: "5"
+```
+
+### Path Segments
+
+```expression
+PathDepth = STRINGCOUNTSEGMENTS("/home/user/documents", "/")
+// Result: "4" (empty first segment + 3 folders)
+```
+
+### Word Count
+
+```expression
+WordCount = STRINGCOUNTSEGMENTS("Hello World Everyone", " ")
+// Result: "3"
+```
+
+## Use Cases
+
+- **Validation**: Check expected number of parts
+- **Path analysis**: Count path segments
+- **Data parsing**: Validate delimited data
+- **Text analysis**: Count words or phrases
+
+## Related Functions
+
+- [stringgetsegments](./stringgetsegments.md) - Get the actual segments
+- [concat](./concat.md) - Combine strings
+- [join](./join.md) - Join with delimiter
+
+## Notes
+
+- Returns count as string
+- Empty string returns "1" (one empty segment)
+- Uses the Utility service

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

@@ -0,0 +1,74 @@
+# stringgetsegments
+
+Splits a string into segments by a delimiter.
+
+## Syntax
+
+```
+stringgetsegments(text, delimiter)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | String | The string to split |
+| `delimiter` | String | The delimiter to split by |
+
+## Returns
+
+Array - Array of string segments.
+
+## Description
+
+The `stringgetsegments` function splits a string by a specified delimiter and returns an array of the resulting segments.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = STRINGGETSEGMENTS("a,b,c,d,e", ",")
+// Result: ["a", "b", "c", "d", "e"]
+```
+
+### Path Parsing
+
+```expression
+PathParts = STRINGGETSEGMENTS("/home/user/documents", "/")
+// Result: ["", "home", "user", "documents"]
+```
+
+### Data Extraction
+
+```expression
+Fields = STRINGGETSEGMENTS(CSVLine, ",")
+// Returns array of field values
+```
+
+### Get Specific Segment
+
+```expression
+// Get second segment
+Segments = STRINGGETSEGMENTS(Data, ",")
+SecondItem = Segments[1]
+```
+
+## Use Cases
+
+- **CSV parsing**: Split delimited lines
+- **Path processing**: Extract path components
+- **Data parsing**: Split structured strings
+- **Text processing**: Tokenize text
+
+## Related Functions
+
+- [stringcountsegments](./stringcountsegments.md) - Count segments
+- [join](./join.md) - Reverse operation (join segments)
+- [slice](./slice.md) - Get subset of segments
+
+## Notes
+
+- Returns array of strings
+- Empty between delimiters creates empty string
+- Uses the Utility service

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

@@ -0,0 +1,66 @@
+# subtractingsummation
+
+Generates a subtracting running total from an array of values.
+
+## Syntax
+
+```
+subtractingsummation(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of numeric values |
+
+## Returns
+
+Array - Array of running differences.
+
+## Description
+
+The `subtractingsummation` function creates an array where each element is the result of subtracting subsequent values from a running total. This is the opposite of cumulative summation.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = SUBTRACTINGSUMMATION([100, 20, 30, 10])
+// Result: [100, 80, 50, 40]
+// 100, 100-20=80, 80-30=50, 50-10=40
+```
+
+### Budget Tracking
+
+```expression
+// Start with budget, subtract expenses
+RemainingBudget = SUBTRACTINGSUMMATION([1000, 250, 150, 75, 200])
+// Shows remaining after each expense
+```
+
+### Inventory Depletion
+
+```expression
+InventoryLevels = SUBTRACTINGSUMMATION([500, 50, 30, 100, 25])
+```
+
+## Use Cases
+
+- **Budget tracking**: Remaining funds after expenses
+- **Inventory**: Stock levels after withdrawals
+- **Resource depletion**: Tracking consumption
+- **Countdown**: Decreasing totals
+
+## Related Functions
+
+- [cumulativesummation](./cumulativesummation.md) - Running total (adding)
+- [sum](./sum.md) - Simple sum
+- [iterativeseries](./iterativeseries.md) - Custom iterative calculation
+
+## Notes
+
+- First element is starting value
+- Each subsequent element subtracts from running total
+- Uses the Math service's `subtractingSummation` method

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

@@ -0,0 +1,78 @@
+# sum
+
+Calculates the sum of all values in a set.
+
+## Syntax
+
+```
+sum(array)
+sum(value1, value2, ...)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | An array of numeric values |
+| `values` | Numbers | Individual values to sum |
+
+## Returns
+
+String - The sum of all values with arbitrary precision.
+
+## Description
+
+The `sum` function adds up all numeric values in an array or set of arguments. It uses arbitrary precision arithmetic for accurate calculations.
+
+## Examples
+
+### Basic Array Sum
+
+```expression
+TotalCost = SUM(ItemCosts)
+// With ItemCosts = [100, 200, 50, 45, 5]
+// Result: "400"
+```
+
+### Sum with Flattened Arrays
+
+```expression
+// Sum population from nested data
+PopSum = sum(flatten(AppData.Cities[].population))
+// Sums all population values from the Cities array
+```
+
+### Sum of Histogram Values
+
+```expression
+// Sum aggregated values
+Total = SUM(FLATTEN(AppData.DestinationObject.AggregationResult))
+```
+
+### Combining with Other Functions
+
+```expression
+// Sum a computed series
+IntegratedSeries = SUM(FLATTEN(AppData.SeriesFromCoefficients))
+```
+
+## Use Cases
+
+- **Financial totals**: Sum of transactions, costs, revenues
+- **Inventory**: Total quantity of items
+- **Statistics**: First step in many statistical calculations
+- **Aggregation**: Combining values from multiple sources
+
+## Related Functions
+
+- [avg](./avg.md) / [mean](./mean.md) - Calculate average
+- [count](./count.md) - Count elements
+- [min](./min.md) / [max](./max.md) - Find extremes
+- [cumulativesummation](./cumulativesummation.md) - Running total
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Returns "0" for empty arrays
+- Non-numeric values may be treated as 0
+- Works with the Math service's `sumPrecise` method

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

@@ -0,0 +1,78 @@
+# tan
+
+Calculates the tangent of an angle (in radians).
+
+## Syntax
+
+```
+tan(radians)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `radians` | Number/String | The angle in radians |
+
+## Returns
+
+String - The tangent of the angle.
+
+## Description
+
+The `tan` function calculates the tangent of an angle, which equals sin(angle)/cos(angle). The input must be in radians. Use the `rad()` function to convert degrees to radians if needed.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = tan(0)
+// Result: "0"
+
+Result = tan(0.7853981633974483)  // π/4 (45 degrees)
+// Result: "1" (approximately)
+```
+
+### Converting from Degrees
+
+```expression
+// Tangent of 45 degrees
+Result = tan(rad(45))
+// Result: "1"
+
+// Tangent of 30 degrees
+Result = tan(rad(30))
+// Result: "0.5773502691896257"
+```
+
+### Slope Calculations
+
+```expression
+// Calculate slope from angle
+Slope = tan(rad(AngleDegrees))
+
+// Rise over run
+Rise = Run * tan(Angle)
+```
+
+## Use Cases
+
+- **Trigonometry**: Slope and angle calculations
+- **Surveying**: Elevation changes
+- **Physics**: Incline problems
+- **Graphics**: Perspective calculations
+
+## Related Functions
+
+- [sin](./sin.md) - Sine
+- [cos](./cos.md) - Cosine
+- [rad](./rad.md) - Convert degrees to radians
+- [pi](./pi.md) - Pi constant
+
+## Notes
+
+- Input must be in radians, not degrees
+- Use `rad(degrees)` to convert from degrees
+- Tangent is undefined at 90°, 270°, etc. (π/2, 3π/2, ...)
+- Uses JavaScript's `Math.tan()` internally