pict-section-formeditor 1.0.0

package/user-documentation/solverfunctions/sortarray.md

@@ -0,0 +1,58 @@
+# sortarray
+
+Returns a sorted copy of the array.
+
+## Syntax
+
+```
+sortarray(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to sort |
+
+## Returns
+
+A new array with the elements sorted in ascending order.
+
+## Description
+
+The `sortarray` function takes an array and returns a new array with its elements sorted in ascending order. The original array is not modified. This is useful for ordering lists of values for display or further processing.
+
+## Examples
+
+### Sorting scores
+
+```expression
+Sorted = sortarray(Scores)
+// If Scores is [85, 42, 97, 63],
+// Sorted is [42, 63, 85, 97]
+```
+
+### Sorting names alphabetically
+
+```expression
+OrderedNames = sortarray(NameList)
+// Returns the names in alphabetical order
+```
+
+## Use Cases
+
+- **Ordering data for display**: Sort a list of values before presenting them to the user
+- **Ranking**: Arrange numeric values in order for ranking or comparison
+- **Alphabetizing**: Sort string values into alphabetical order
+
+## Related Functions
+
+- [uniquearray](./uniquearray.md) - Removes duplicates from an array
+- [unionarrays](./unionarrays.md) - Returns all unique values from both arrays
+- [differencearrays](./differencearrays.md) - Returns values in one array that are not in another
+
+## Notes
+
+- The input must be an array
+- The original array is not modified; a new sorted array is returned
+- Sorting behavior follows standard JavaScript sort ordering

package/user-documentation/solverfunctions/sorthistogram.md

@@ -0,0 +1,70 @@
+# sorthistogram
+
+Sorts a histogram object by its values.
+
+## Syntax
+
+```
+sorthistogram(histogram)
+sorthistogram(histogram, descending)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `histogram` | Object | The histogram object to sort |
+| `descending` | Boolean | If true, sort in descending order (optional) |
+
+## Returns
+
+Array - Array of [key, value] pairs sorted by value.
+
+## Description
+
+The `sorthistogram` function takes a histogram (object with keys and numeric values) and returns it as a sorted array of key-value pairs, ordered by the values.
+
+## Examples
+
+### Ascending Sort (Default)
+
+```expression
+// Given histogram: { 'A': 5, 'B': 2, 'C': 8 }
+Result = SORTHISTOGRAM(Histogram)
+// Result: [['B', 2], ['A', 5], ['C', 8]]
+```
+
+### Descending Sort
+
+```expression
+Result = SORTHISTOGRAM(Histogram, true)
+// Result: [['C', 8], ['A', 5], ['B', 2]]
+```
+
+### With Distribution Histogram
+
+```expression
+Distribution = DISTRIBUTIONHISTOGRAM("AppData.Orders", "status")
+SortedByCount = SORTHISTOGRAM(Distribution, true)
+// Most common statuses first
+```
+
+## Use Cases
+
+- **Rankings**: Rank categories by frequency
+- **Top N**: Find top categories
+- **Reports**: Ordered category lists
+- **Analysis**: Sorted distributions
+
+## Related Functions
+
+- [sorthistogrambykeys](./sorthistogrambykeys.md) - Sort by keys instead
+- [sortset](./sortset.md) - Sort simple arrays
+- [distributionhistogram](./distributionhistogram.md) - Create histogram
+- [aggregationhistogram](./aggregationhistogram.md) - Create aggregation histogram
+
+## Notes
+
+- Returns array of [key, value] pairs
+- Sorts by numeric value
+- Uses the Math service's `sortHistogram` method

package/user-documentation/solverfunctions/sorthistogrambykeys.md

@@ -0,0 +1,69 @@
+# sorthistogrambykeys
+
+Sorts a histogram object by its keys.
+
+## Syntax
+
+```
+sorthistogrambykeys(histogram)
+sorthistogrambykeys(histogram, descending)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `histogram` | Object | The histogram object to sort |
+| `descending` | Boolean | If true, sort in descending order (optional) |
+
+## Returns
+
+Array - Array of [key, value] pairs sorted by key.
+
+## Description
+
+The `sorthistogrambykeys` function takes a histogram (object with keys and values) and returns it as a sorted array of key-value pairs, ordered alphabetically or numerically by the keys.
+
+## Examples
+
+### Alphabetical Sort (Default)
+
+```expression
+// Given histogram: { 'Charlie': 5, 'Alice': 2, 'Bob': 8 }
+Result = SORTHISTOGRAMBYKEYS(Histogram)
+// Result: [['Alice', 2], ['Bob', 8], ['Charlie', 5]]
+```
+
+### Descending Sort
+
+```expression
+Result = SORTHISTOGRAMBYKEYS(Histogram, true)
+// Result: [['Charlie', 5], ['Bob', 8], ['Alice', 2]]
+```
+
+### State Data
+
+```expression
+PopulationByState = AGGREGATIONHISTOGRAM("AppData.Cities", "state", "population")
+SortedByState = SORTHISTOGRAMBYKEYS(PopulationByState)
+// Alphabetically by state name
+```
+
+## Use Cases
+
+- **Alphabetical ordering**: Sort categories alphabetically
+- **Consistent display**: Predictable key ordering
+- **Reports**: Ordered by category name
+- **Lookups**: Binary search preparation
+
+## Related Functions
+
+- [sorthistogram](./sorthistogram.md) - Sort by values instead
+- [sortset](./sortset.md) - Sort simple arrays
+- [distributionhistogram](./distributionhistogram.md) - Create histogram
+
+## Notes
+
+- Returns array of [key, value] pairs
+- Sorts by key (alphabetically/numerically)
+- Uses the Math service's `sortHistogramByKeys` method

package/user-documentation/solverfunctions/sortset.md

@@ -0,0 +1,75 @@
+# sortset
+
+Sorts an array of values in ascending or descending order.
+
+## Syntax
+
+```
+sortset(array)
+sortset(array, descending)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to sort |
+| `descending` | Boolean | If true, sort in descending order (optional) |
+
+## Returns
+
+Array - The sorted array.
+
+## Description
+
+The `sortset` function sorts an array of values. By default, it sorts in ascending order. Pass `true` as the second parameter to sort in descending order.
+
+## Examples
+
+### Ascending Sort (Default)
+
+```expression
+Result = SORTSET([3, 1, 4, 1, 5, 9, 2, 6])
+// Result: [1, 1, 2, 3, 4, 5, 6, 9]
+```
+
+### Descending Sort
+
+```expression
+Result = SORTSET([3, 1, 4, 1, 5, 9, 2, 6], true)
+// Result: [9, 6, 5, 4, 3, 2, 1, 1]
+```
+
+### With Data
+
+```expression
+SortedScores = SORTSET(FLATTEN(AppData.Students.score), true)
+// Highest to lowest scores
+```
+
+### Top N Values
+
+```expression
+TopThree = SLICE(SORTSET(Values, true), 0, 3)
+```
+
+## Use Cases
+
+- **Rankings**: Create leaderboards
+- **Analysis**: Sorted data examination
+- **Selection**: Find top/bottom values
+- **Display**: Ordered presentation
+
+## Related Functions
+
+- [sorthistogram](./sorthistogram.md) - Sort histogram by values
+- [sorthistogrambykeys](./sorthistogrambykeys.md) - Sort histogram by keys
+- [max](./max.md) - Find maximum value
+- [min](./min.md) - Find minimum value
+- [slice](./slice.md) - Extract portion after sorting
+
+## Notes
+
+- Returns new sorted array
+- Original array unchanged
+- Uses the Math service's `sortSet` method

package/user-documentation/solverfunctions/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/user-documentation/solverfunctions/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/user-documentation/solverfunctions/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/user-documentation/solverfunctions/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/user-documentation/solverfunctions/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