pict-section-formeditor 1.0.0

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

@@ -0,0 +1,58 @@
+# hidesections
+
+Hides the specified form sections.
+
+## Syntax
+
+```
+hidesections(sectionHashes)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHashes` | Array or String | An array of section hash strings, or a single section hash string |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `hidesections` function hides one or more form sections from the page. You can pass either an array of section hash strings to hide multiple sections at once, or a single string to hide one section. Hidden sections are not visible to the user but remain part of the form state. This is commonly used in conjunction with solver logic to conditionally hide parts of a form based on user input or other state.
+
+## Examples
+
+### Hiding multiple sections from an array
+
+```expression
+hidesections(HiddenSectionList)
+// Where HiddenSectionList is an array like ["S2", "S4"]
+// Hides sections S2 and S4
+```
+
+### Hiding a single section
+
+```expression
+hidesections("OptionalDetails")
+// Hides the OptionalDetails section
+```
+
+## Use Cases
+
+- **Conditional form display**: Hide sections of a form that are not relevant based on user selections
+- **Simplifying forms**: Remove unnecessary sections to reduce visual clutter
+- **Workflow gating**: Hide sections until prerequisite conditions are met
+
+## Related Functions
+
+- [showsections](./showsections.md) - Makes the specified form sections visible
+- [setsectionvisibility](./setsectionvisibility.md) - Sets a specific section's visibility with a boolean
+- [setgroupvisibility](./setgroupvisibility.md) - Sets a specific group's visibility within a section
+
+## Notes
+
+- Accepts either an array of section hash strings or a single string
+- Section hashes must match the hashes defined in the form configuration
+- Hidden sections retain their data in the application state

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

package/user-documentation/solverfunctions/join.md

@@ -0,0 +1,75 @@
+# join
+
+Joins array elements into a string with a specified separator.
+
+## Syntax
+
+```
+join(array, separator)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array of values to join |
+| `separator` | String | The separator to place between elements |
+
+## Returns
+
+String - All array elements joined with the specified separator.
+
+## Description
+
+The `join` function combines all elements of an array into a single string, placing the specified separator between each element.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = JOIN(["a", "b", "c"], ", ")
+// Result: "a, b, c"
+```
+
+### With Data Array
+
+```expression
+// Join city names with semicolons
+CityList = JOIN(FLATTEN(AppData.Cities.name), "; ")
+// Result: "New York; Los Angeles; Chicago"
+```
+
+### Creating CSV Line
+
+```expression
+CSVLine = JOIN(DataRow, ",")
+// Result: "value1,value2,value3"
+```
+
+### Path Building
+
+```expression
+FilePath = JOIN(PathParts, "/")
+// Result: "home/user/documents"
+```
+
+## Use Cases
+
+- **Display lists**: Format lists for display
+- **CSV generation**: Build CSV lines
+- **Path construction**: Build file paths
+- **Report generation**: Format data for output
+
+## Related Functions
+
+- [joinraw](./joinraw.md) - Join without separator
+- [concat](./concat.md) - Concatenate with spaces
+- [flatten](./flatten.md) - Flatten nested arrays before joining
+
+## Notes
+
+- Separator is placed between elements only
+- Empty arrays return empty string
+- Uses the DataFormat service internally
+- Converts all elements to strings

package/user-documentation/solverfunctions/joinraw.md

@@ -0,0 +1,64 @@
+# joinraw
+
+Joins array elements into a string without any separator.
+
+## Syntax
+
+```
+joinraw(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array of values to join |
+
+## Returns
+
+String - All array elements joined with no separator.
+
+## Description
+
+The `joinraw` function combines all elements of an array into a single string without placing any separator between elements.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = JOINRAW(["H", "e", "l", "l", "o"])
+// Result: "Hello"
+```
+
+### Building Identifiers
+
+```expression
+Code = JOINRAW([Prefix, Number, Suffix])
+// Result: "ABC123XYZ"
+```
+
+### Character Array to String
+
+```expression
+Word = JOINRAW(Characters)
+// Result: combined string
+```
+
+## Use Cases
+
+- **String reconstruction**: Rebuild strings from character arrays
+- **Code generation**: Build identifiers
+- **Data transformation**: Combine array into string
+
+## Related Functions
+
+- [join](./join.md) - Join with custom separator
+- [concat](./concat.md) - Concatenate with spaces
+- [concatraw](./concatraw.md) - Concatenate without spaces
+
+## Notes
+
+- No separator between elements
+- Uses the DataFormat service internally
+- Useful when working with character arrays

package/user-documentation/solverfunctions/largestinset.md

@@ -0,0 +1,63 @@
+# largestinset
+
+Returns the largest value from a set/array.
+
+## Syntax
+
+```
+largestinset(set)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `set` | Array | The array of values |
+
+## Returns
+
+String - The largest value in the set.
+
+## Description
+
+The `largestinset` function finds and returns the largest (maximum) value from an array. This is an alternative to the `max` function specifically designed for set operations.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = LARGESTINSET([5, 2, 8, 1, 9])
+// Result: "9"
+```
+
+### With Data
+
+```expression
+HighestScore = LARGESTINSET(FLATTEN(AppData.Students.score))
+```
+
+### Sales Data
+
+```expression
+TopSale = LARGESTINSET(MonthlySales)
+```
+
+## Use Cases
+
+- **Analysis**: Find maximum values
+- **Rankings**: Determine top values
+- **Comparisons**: Find highest in category
+- **Limits**: Check maximum constraints
+
+## Related Functions
+
+- [smallestinset](./smallestinset.md) - Find minimum value
+- [max](./max.md) - Alternative maximum function
+- [sortset](./sortset.md) - Sort to find extremes
+
+## Notes
+
+- Returns result as string
+- Works with numeric values
+- Uses the Math service's `largestInSet` method

package/user-documentation/solverfunctions/leastsquares.md

@@ -0,0 +1,66 @@
+# leastsquares
+
+Performs linear least squares regression.
+
+## Syntax
+
+```
+leastsquares(xValues, yValues)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `xValues` | Array | Array of x-coordinates (independent variable) |
+| `yValues` | Array | Array of y-coordinates (dependent variable) |
+
+## Returns
+
+Object - Regression results including slope, intercept, and statistics.
+
+## Description
+
+The `leastsquares` function performs linear regression to find the best-fit line through a set of data points. It returns the slope, intercept, and other statistical measures.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = LEASTSQUARES([1, 2, 3, 4, 5], [2, 4, 6, 8, 10])
+// Returns: { slope: 2, intercept: 0, ... }
+```
+
+### Sales Trend
+
+```expression
+// Analyze sales trend over time
+SalesTrend = LEASTSQUARES(Months, SalesData)
+```
+
+### Temperature Analysis
+
+```expression
+TempRegression = LEASTSQUARES(Years, AvgTemperatures)
+// slope indicates rate of change
+```
+
+## Use Cases
+
+- **Trend analysis**: Find linear trends
+- **Forecasting**: Project future values
+- **Correlation**: Measure linear relationship
+- **Scientific analysis**: Linear modeling
+
+## Related Functions
+
+- [linest](./linest.md) - Alternative linear estimation
+- [polynomialregression](./polynomialregression.md) - Higher-order regression
+- [predict](./predict.md) - Predict using regression results
+
+## Notes
+
+- Also available as `linest`
+- Returns comprehensive statistics
+- Uses the Math service's `leastSquares` method