pict-section-formeditor 1.0.0

package/user-documentation/solverfunctions/abs.md

@@ -0,0 +1,84 @@
+# abs
+
+Returns the absolute value of a number.
+
+## Syntax
+
+```
+abs(value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Number/String | The value to get the absolute value of |
+
+## Returns
+
+String - The absolute value (non-negative) of the input.
+
+## Description
+
+The `abs` function returns the absolute value of a number, which is always non-negative. If the input is negative, it returns the positive equivalent. If already positive or zero, it returns the value unchanged.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = abs(-5)
+// Result: "5"
+
+Result = abs(5)
+// Result: "5"
+
+Result = abs(0)
+// Result: "0"
+
+Result = abs(-3.14159)
+// Result: "3.14159"
+```
+
+### With Variables
+
+```expression
+// Calculate the absolute difference between two values
+Difference = abs(Value1 - Value2)
+// With Value1=10, Value2=25
+// Result: "15"
+```
+
+### In Conditional Comparisons
+
+```expression
+// Check if two values are within a tolerance
+IsClose = IF(ABS(Expected - Actual), "LT", Tolerance, "yes", "no")
+```
+
+### In Complex Expressions
+
+```expression
+// Used in the unit tests to verify precision
+Result = abs(ComputedValue - ExpectedValue)
+// Check if within epsilon: abs(difference) < 0.00000000001
+```
+
+## Use Cases
+
+- **Error calculations**: Finding the magnitude of differences
+- **Distance calculations**: Distances are always positive
+- **Tolerance checking**: Verifying values are within acceptable ranges
+- **Data normalization**: Converting all values to positive
+
+## Related Functions
+
+- [sqrt](./sqrt.md) - Square root
+- [floor](./floor.md) - Floor value
+- [ceil](./ceil.md) - Ceiling value
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Returns a string representation of the result
+- Works with the Math service's `absPrecise` method internally

package/user-documentation/solverfunctions/aggregationhistogram.md

@@ -0,0 +1,83 @@
+# aggregationhistogram
+
+Generates a histogram by aggregating values grouped by a key.
+
+## Syntax
+
+```
+aggregationhistogram(dataPath, keyProperty, valueProperty)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dataPath` | String | Path to the data array (quoted string) |
+| `keyProperty` | String | Property name to group by |
+| `valueProperty` | String | Property name containing values to sum |
+
+## Returns
+
+Object - A histogram object with keys and their aggregated values.
+
+## Description
+
+The `aggregationhistogram` function creates a histogram by grouping records by a key property and summing the values of another property for each group. This is useful for aggregating totals by category.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given AppData.Teams:
+// [
+//   { Team: 'Mariners', States: 'Washington', Score: 100 },
+//   { Team: 'Yankees', States: 'New York', Score: 200 },
+//   { Team: 'Mets', States: 'New York', Score: 50 },
+//   { Team: 'Giants', States: 'California', Score: 45 },
+//   { Team: 'Dodgers', States: 'California', Score: 5 },
+//   { Team: 'Astros', States: 'Texas', Score: 75 }
+// ]
+
+Result = aggregationhistogram("AppData.Teams", "States", "Score")
+// Result: {
+//   'Washington': '100',
+//   'New York': '250',    // 200 + 50
+//   'California': '50',   // 45 + 5
+//   'Texas': '75'
+// }
+```
+
+### Population by State
+
+```expression
+// Aggregate city populations by state
+AggregationResult = aggregationHistogram("AppData.Cities", "state", "population")
+// Result: { 'Alabama': '1279813', 'Colorado': '...', ... }
+```
+
+### With Further Processing
+
+```expression
+// Sum all aggregated values
+Total = SUM(FLATTEN(AppData.DestinationObject.AggregationResult))
+```
+
+## Use Cases
+
+- **Sales by region**: Sum revenue by territory
+- **Population statistics**: Aggregate population by state/country
+- **Inventory**: Total items by category
+- **Financial reporting**: Sum transactions by account
+
+## Related Functions
+
+- [aggregationhistogrambyobject](./aggregationhistogrambyobject.md) - Takes object directly instead of path
+- [distributionhistogram](./distributionhistogram.md) - Count occurrences instead of sum
+- [sum](./sum.md) - Simple sum of values
+
+## Notes
+
+- The data path must be a quoted string
+- Uses arbitrary precision arithmetic for summing
+- Works with the Math service's `histogramAggregationByExactValueFromInternalState` method

package/user-documentation/solverfunctions/aggregationhistogrambyobject.md

@@ -0,0 +1,64 @@
+# aggregationhistogrambyobject
+
+Generates an aggregation histogram from an object directly.
+
+## Syntax
+
+```
+aggregationhistogrambyobject(object, keyProperty, valueProperty)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Array | Array of objects to aggregate |
+| `keyProperty` | String | Property name to group by |
+| `valueProperty` | String | Property name containing values to sum |
+
+## Returns
+
+Object - A histogram object with keys and their aggregated values.
+
+## Description
+
+The `aggregationhistogrambyobject` function is similar to `aggregationhistogram` but takes an object/array directly instead of a data path string. This is useful when working with data that's already in a variable.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given array of team data
+Teams = [
+  { Team: 'Mariners', State: 'WA', Score: 100 },
+  { Team: 'Yankees', State: 'NY', Score: 200 },
+  { Team: 'Mets', State: 'NY', Score: 50 }
+]
+
+Result = AGGREGATIONHISTOGRAMBYOBJECT(Teams, "State", "Score")
+// Result: { 'WA': '100', 'NY': '250' }
+```
+
+### With Variable Data
+
+```expression
+SalesByRegion = AGGREGATIONHISTOGRAMBYOBJECT(FilteredData, "region", "amount")
+```
+
+## Use Cases
+
+- **Dynamic data**: Aggregate data already in variables
+- **Filtered data**: Aggregate after filtering
+- **Chained operations**: Use in expression chains
+
+## Related Functions
+
+- [aggregationhistogram](./aggregationhistogram.md) - Uses data path string
+- [distributionhistogrambyobject](./distributionhistogrambyobject.md) - Count by object
+- [sum](./sum.md) - Simple sum
+
+## Notes
+
+- Takes array directly, not path string
+- Uses the Math service's `histogramAggregationByExactValue` method

package/user-documentation/solverfunctions/arrayconcat.md

@@ -0,0 +1,64 @@
+# arrayconcat
+
+Concatenates multiple arrays into one.
+
+## Syntax
+
+```
+arrayconcat(array1, array2, ...)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `arrays` | Array(s) | Arrays to concatenate |
+
+## Returns
+
+Array - Combined array with elements from all inputs.
+
+## Description
+
+The `arrayconcat` function combines multiple arrays into a single array by appending them in order.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = ARRAYCONCAT([1, 2], [3, 4], [5, 6])
+// Result: [1, 2, 3, 4, 5, 6]
+```
+
+### Two Arrays
+
+```expression
+Combined = ARRAYCONCAT(FirstHalf, SecondHalf)
+```
+
+### Multiple Sources
+
+```expression
+AllData = ARRAYCONCAT(Source1, Source2, Source3)
+```
+
+## Use Cases
+
+- **Data merging**: Combine multiple arrays
+- **Report building**: Aggregate data sections
+- **Collection**: Gather from multiple sources
+- **Batch processing**: Combine batches
+
+## Related Functions
+
+- [setconcatenate](./setconcatenate.md) - Concatenate two sets
+- [flatten](./flatten.md) - Flatten nested arrays
+- [join](./join.md) - Join as string
+
+## Notes
+
+- Accepts multiple arrays
+- Order is preserved
+- Does not remove duplicates
+- Uses the Math service's `arrayConcat` method

package/user-documentation/solverfunctions/avg.md

@@ -0,0 +1,81 @@
+# avg / mean
+
+Calculates the arithmetic average (mean) of values in a set.
+
+## Syntax
+
+```
+avg(array)
+mean(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | An array of numeric values |
+
+## Returns
+
+String - The arithmetic mean of all values.
+
+## Description
+
+The `avg` and `mean` functions are identical - both calculate the arithmetic average of a set of values. The average is computed as the sum of all values divided by the count of values.
+
+## Examples
+
+### Basic Usage
+
+```expression
+TotalCost = MEAN(ItemCosts)
+// With ItemCosts = [100, 200, 50, 45, 5]
+// Result: "80"
+
+// Using avg (same result)
+Average = AVG(ItemCosts)
+// Result: "80"
+```
+
+### Average of Computed Values
+
+```expression
+MadeUpValueArray = ROUND(AVG(createarrayfromabsolutevalues(100, 10, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100)),2)
+// Result: "550.83"
+```
+
+### With Cleaned Data
+
+```expression
+// Average excluding invalid values
+MadeUpValueArray = ROUND(AVG(cleanvaluearray(createarrayfromabsolutevalues(AppData.Value1, AppData.Value2, AppData.Value3, AppData.Value4, AppData.Value5), 1)),2)
+// Result: "2421.54"
+```
+
+### Combined with Other Functions
+
+```expression
+// Average from flattened nested data
+AvgPopulation = AVG(FLATTEN(Cities[].population))
+```
+
+## Use Cases
+
+- **Statistics**: Central tendency measurement
+- **Performance metrics**: Average response time, throughput
+- **Financial**: Average transaction value, mean return
+- **Scientific data**: Mean measurements
+
+## Related Functions
+
+- [sum](./sum.md) - Sum of values
+- [median](./median.md) - Middle value
+- [mode](./mode.md) - Most frequent value
+- [count](./count.md) - Count elements
+
+## Notes
+
+- `avg` and `mean` are aliases for the same function
+- Uses arbitrary precision arithmetic
+- Returns the arithmetic mean (sum / count)
+- Works with the Math service's `meanPrecise` and `averagePrecise` methods

package/user-documentation/solverfunctions/bucketset.md

@@ -0,0 +1,69 @@
+# bucketset
+
+Groups values into buckets based on specified boundaries.
+
+## Syntax
+
+```
+bucketset(values, buckets)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Array | Array of numeric values to bucket |
+| `buckets` | Array | Array of bucket boundaries |
+
+## Returns
+
+Object - Histogram with bucket ranges as keys and counts as values.
+
+## Description
+
+The `bucketset` function groups numeric values into buckets (ranges) based on specified boundaries. This is useful for creating histograms of continuous data.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Group scores into ranges
+Scores = [45, 62, 78, 85, 92, 55, 73, 88]
+Buckets = BUCKETSET(Scores, [0, 50, 70, 90, 100])
+// Result: { '0-50': 1, '50-70': 2, '70-90': 3, '90-100': 2 }
+```
+
+### Age Groups
+
+```expression
+Ages = [25, 32, 45, 18, 67, 55, 42, 29]
+AgeGroups = BUCKETSET(Ages, [0, 18, 30, 50, 65, 100])
+// Groups: Under 18, 18-30, 30-50, 50-65, 65+
+```
+
+### Price Ranges
+
+```expression
+Prices = FLATTEN(AppData.Products.price)
+PriceRanges = BUCKETSET(Prices, [0, 25, 50, 100, 500])
+```
+
+## Use Cases
+
+- **Analytics**: Group continuous data into ranges
+- **Reporting**: Create distribution charts
+- **Demographics**: Age/income brackets
+- **Grading**: Score ranges
+
+## Related Functions
+
+- [distributionhistogram](./distributionhistogram.md) - Count by exact values
+- [sorthistogram](./sorthistogram.md) - Sort bucketed results
+- [count](./count.md) - Simple count
+
+## Notes
+
+- Bucket boundaries define range edges
+- Values fall into the appropriate range
+- Uses the Math service's `bucketSet` method

package/user-documentation/solverfunctions/ceil.md

@@ -0,0 +1,70 @@
+# ceil
+
+Returns the smallest integer greater than or equal to a number.
+
+## Syntax
+
+```
+ceil(value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Number/String | The value to ceiling |
+
+## Returns
+
+String - The smallest integer greater than or equal to the input.
+
+## Description
+
+The `ceil` function rounds a number up to the nearest integer. For positive numbers, this rounds away from zero. For negative numbers, it rounds toward zero (less negative).
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = ceil(3.2)
+// Result: "4"
+
+Result = ceil(3.7)
+// Result: "4"
+
+Result = ceil(3.0)
+// Result: "3"
+
+Result = ceil(-2.7)
+// Result: "-2" (rounds toward zero)
+```
+
+### With Expressions
+
+```expression
+// Calculate pages needed
+PagesNeeded = ceil(TotalItems / ItemsPerPage)
+
+// Calculate containers required
+ContainersNeeded = ceil(TotalVolume / ContainerCapacity)
+```
+
+## Use Cases
+
+- **Resource allocation**: Calculating minimum containers/pages needed
+- **Time calculations**: Rounding up to next hour/day
+- **Inventory planning**: Ensuring sufficient stock
+- **Pricing**: Rounding up prices
+
+## Related Functions
+
+- [floor](./floor.md) - Round down
+- [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, ceil(-2.7) = -2, not -3

package/user-documentation/solverfunctions/cleanvaluearray.md

@@ -0,0 +1,66 @@
+# cleanvaluearray
+
+Gets a value from an array with default for missing values.
+
+## Syntax
+
+```
+cleanvaluearray(array, index, defaultValue)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to retrieve from |
+| `index` | Number | Zero-based index |
+| `defaultValue` | Any | Value to return if index is out of bounds or value is undefined |
+
+## Returns
+
+Any - The value at the index, or the default value.
+
+## Description
+
+The `cleanvaluearray` function retrieves a value from an array at the specified index, returning a default value if the index is out of bounds or the value is undefined/null.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = CLEANVALUEARRAY(["a", "b", "c"], 5, "default")
+// Result: "default" (index 5 is out of bounds)
+```
+
+### Safe Access
+
+```expression
+Value = CLEANVALUEARRAY(Items, Index, 0)
+// Returns 0 if index invalid
+```
+
+### With Empty Array
+
+```expression
+First = CLEANVALUEARRAY(MaybeEmptyArray, 0, "No items")
+```
+
+## Use Cases
+
+- **Safe access**: Avoid undefined errors
+- **Default values**: Provide fallbacks
+- **Data processing**: Handle missing data
+- **Display**: Show placeholder for missing
+
+## Related Functions
+
+- [getvaluearray](./getvaluearray.md) - Get without default
+- [cleanvalueobject](./cleanvalueobject.md) - Clean get from object
+- [if](./if.md) - Conditional logic
+
+## Notes
+
+- Returns default for undefined/null
+- Returns default for out-of-bounds
+- Uses the Logic service's `cleanValueArray` method

package/user-documentation/solverfunctions/cleanvalueobject.md

@@ -0,0 +1,68 @@
+# cleanvalueobject
+
+Gets a value from an object with default for missing values.
+
+## Syntax
+
+```
+cleanvalueobject(object, key, defaultValue)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Object | The object to retrieve from |
+| `key` | String | The property key |
+| `defaultValue` | Any | Value to return if key is missing or value is undefined |
+
+## Returns
+
+Any - The property value, or the default value.
+
+## Description
+
+The `cleanvalueobject` function retrieves a value from an object by key, returning a default value if the key doesn't exist or the value is undefined/null.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given object: { name: "John" }
+Result = CLEANVALUEOBJECT(Person, "email", "no-email@example.com")
+// Result: "no-email@example.com" (key doesn't exist)
+```
+
+### Safe Configuration
+
+```expression
+Timeout = CLEANVALUEOBJECT(Config, "timeout", 30)
+// Returns 30 if timeout not configured
+```
+
+### Histogram Lookup
+
+```expression
+Count = CLEANVALUEOBJECT(Histogram, "MissingCategory", 0)
+// Returns 0 if category doesn't exist
+```
+
+## Use Cases
+
+- **Configuration**: Default settings
+- **Data processing**: Handle missing data
+- **Display**: Show placeholder text
+- **Calculations**: Default numeric values
+
+## Related Functions
+
+- [getvalueobject](./getvalueobject.md) - Get without default
+- [cleanvaluearray](./cleanvaluearray.md) - Clean get from array
+- [getvalue](./getvalue.md) - Get from data state
+
+## Notes
+
+- Returns default for undefined/null
+- Returns default for missing keys
+- Uses the Logic service's `cleanValueObject` method