SalArray
Namespace: PPJ.Runtime
Assembly: PPJ.Runtime.50 (5.0.0.0)
Implements storage, bounds, conversion, and collection operations for SAL arrays.
- C#
- VB.NET
public class SalArray : IList, ICollection, IEnumerable, IXmlSerializable, ISalType
Public Class SalArray
Inherits IList
Implements ICollection, IEnumerable, IXmlSerializable, ISalType
Use SalArray<T> for typed arrays. Only the first dimension can be dynamic. Reading an uninitialized reference element creates its default instance; enumeration reads the backing storage directly.
Example:
using PPJ.Runtime;
SalArray values = new SalArray<SalNumber>();
values.Add((SalNumber)10);
values.Add((SalNumber)20);
SalNumber total = values.Sum(); // 30
Properties
Count
Int32: Gets the total logical number of elements as an integer.
Dimensions
SalNumber: Gets the number of dimensions.
IsDynamic
Boolean: Gets whether the first dimension can grow automatically.
IsEmpty
Boolean: Gets whether the logical array has no elements.
IsMultidimensional
Boolean: Gets whether the array has more than one dimension.
IsSynchronized
Boolean: Gets the backing array's synchronization indicator.
Item(indices)
Object: Gets or sets an element using SAL bounds and initialization rules.
For dynamic arrays, either access can extend the first dimension. Reading an uninitialized reference slot creates a default instance. Assignment converts compatible values to the element type; null is rejected for value types and SalString.
Length
SalNumber: Gets the total logical number of elements.
SyncRoot
Object: Gets the object exposed for collection synchronization.
Methods
Add(value)
Makes the array dynamic and stores a value at the current Count index.
| Parameter | Type | Description |
|---|---|---|
| value | Object | The element to store, converted to the array element type when supported. |
Returns: Int32. The index at which the value was stored.
Only one-dimensional arrays are supported. This method uses Count as an index, so conventional append behavior assumes a zero lower bound.
AddRange(collection)
Appends the supplied elements to a one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| collection | IEnumerable | The sequence of elements to append. |
Makes the array dynamic and repeatedly calls Add. Use zero-based arrays for conventional append behavior.
Avg()
Computes the arithmetic mean of values converted to decimal.
Returns: SalNumber. The sum divided by the total logical length, or zero for an empty array.
Null object references are skipped. SAL null values use their conversion behavior. Unsupported element conversions and decimal overflow propagate. Skipped null references remain part of the divisor.
Clear()
Clears a dynamic array by setting its first dimension length to zero.
Retains the first lower bound. Fixed arrays cause InvalidOperationException.
CopyTo(array, index)
Copies the logical elements to an existing array.
| Parameter | Type | Description |
|---|---|---|
| array | Array | The destination array with compatible element type and sufficient space. |
| index | Int32 | The first destination index. |
Copies from the backing array starting at its first SAL lower bound.
CreateInstance()
Creates a default element through runtime activation.
Returns: Object. A new instance of the configured element type.
Derived array types can override this to supply SAL-specific default values.
DimCount()
Returns the array rank.
Returns: SalNumber. The number of dimensions.
DimCount(nDim)
Retrieves the array rank.
| Parameter | Type | Description |
|---|---|---|
nDim  | SalNumber | Receives the number of dimensions. |
Returns: Boolean. True after assignment.
Fill(value, count)
Assigns one converted value to a one-dimensional array range.
| Parameter | Type | Description |
|---|---|---|
| value | Object | The value to convert once and assign to each element. |
| count | Int32 | The desired element count, starting at the lower bound. |
Returns: Boolean. True after processing.
Negative counts do nothing. A zero count leaves a fixed array unchanged. For positive counts, the upper bound is adjusted and each slot receives the same converted value, including the same reference for reference types.
Find(value, start)
Searches a one-dimensional array for a matching value.
| Parameter | Type | Description |
|---|---|---|
| value | Object | The value to find, using element-type conversion where supported. |
start  | Int32 | The first search index, or -1 to use the lower bound. |
Returns: Int32. The matching index, or -1 when absent.
Searches the logical array range using SAL-specialized comparisons for built-in SAL element types.
FromNativeArray(array)
Copies a CLR array into a SAL array.
| Parameter | Type | Description |
|---|---|---|
| array | Array | The source array, or null. |
Returns: SalArray. The converted array, or null for a null source.
Supports numeric, date/time, and string database types. Other types, including Boolean, cause NotSupportedException. Null and DBNull elements become the selected SAL null value.
FromNativeArray(array, dbType)
Copies a CLR array into a SAL array.
| Parameter | Type | Description |
|---|---|---|
| array | Array | The source array, or null. |
| dbType | DbType | The database type selecting numeric, date/time, or string SAL elements. |
Returns: SalArray. The converted array, or null for a null source.
Supports numeric, date/time, and string database types. Other types, including Boolean, cause NotSupportedException. Null and DBNull elements become the selected SAL null value.
GetArray(capacity)
Returns the backing array, optionally accessing an element first to ensure capacity.
| Parameter | Type | Description |
|---|---|---|
| capacity | Int32[] | The element indices to access, or null or an empty array to return storage without accessing an element. |
Returns: Array. The live underlying System.Array, including unused capacity.
Only a dynamic first dimension can grow automatically. Supplied values are indices, not lengths.
GetElementType()
Returns the runtime element type.
Returns: Type. The Type configured for this array.
GetEnumerator()
Returns an enumerator over the logical elements.
Returns: IEnumerator. An enumerator that traverses the last dimension fastest.
Reads backing storage without lazily constructing uninitialized elements. Spare capacity is excluded.
GetLength(dim)
Returns the logical length of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
Returns: Int32. The number of elements in that dimension, excluding spare capacity.
GetLowerBound(dim)
Retrieves the lower bound of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
Returns: SalNumber. The bound, or -1 for an invalid dimension.
GetLowerBound(dim, lbound)
Retrieves the lower bound of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
| lbound | SalNumber | Receives the bound on success. Set to -1 for a dimension below one; otherwise unchanged on failure. |
Returns: Boolean. True for a valid dimension; otherwise, false.
GetUpperBound(dim)
Retrieves the upper bound of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
Returns: SalNumber. The bound, or -1 for an invalid dimension.
An otherwise negative upper bound is reported as zero for a dynamic array.
GetUpperBound(dim, ubound)
Retrieves the upper bound of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
| ubound | SalNumber | Receives the bound on success. Set to -1 for a dimension below one; otherwise unchanged on failure. |
Returns: Boolean. True for a valid dimension; otherwise, false.
An otherwise negative upper bound is reported as zero for a dynamic array.
Insert(index)
Inserts a default element and shifts subsequent elements one position.
| Parameter | Type | Description |
|---|---|---|
| index | Int32 | The insertion index, from the lower bound through one past the upper bound. |
Only one-dimensional arrays are supported.
MakeDynamic()
Enables automatic growth of the first dimension.
Does not change existing bounds or element values.
Max()
Finds the greatest value after decimal conversion.
Returns: SalNumber. The maximum, or zero if no non-null elements are encountered.
Null object references are skipped. SAL null values use their conversion behavior. Unsupported element conversions and decimal overflow propagate.
Min()
Finds the least value after decimal conversion.
Returns: SalNumber. The minimum, or zero if no non-null elements are encountered.
Null object references are skipped. SAL null values use their conversion behavior. Unsupported element conversions and decimal overflow propagate.
QueryBounds(min, max)
Retrieves the first dimension bounds and total logical length.
| Parameter | Type | Description |
|---|---|---|
| min | SalNumber | Receives the first lower bound. |
| max | SalNumber | Receives the first upper bound. |
Returns: SalNumber. The total logical element count across all dimensions.
Remove(index)
Removes an element and shifts later elements toward the start.
| Parameter | Type | Description |
|---|---|---|
| index | Int32 | The index of the element to remove. |
Only one-dimensional arrays are supported. The logical length decreases by one.
Reset()
Clears a dynamic array by setting its first dimension length to zero.
Retains the first lower bound. Fixed arrays cause InvalidOperationException.
SetBounds(lower, upper)
Changes the bounds of the first dimension.
| Parameter | Type | Description |
|---|---|---|
| lower | Int32 | The lower index. A negative value retains the existing lower bound for a one-dimensional array. |
| upper | Int32 | The upper index, AC_Dynamic to enable growth, or -1 to request clearing a dynamic array. |
Returns: Boolean. True if the request is accepted; false for rejected bounds or an attempt to clear a fixed array.
For multidimensional arrays only the first dimension is affected.
Example:
using PPJ.Runtime;
SalArray<SalString> names = new SalArray<SalString>("2:4");
names[2] = "Ada"; // Valid indexes initially run from 2 through 4.
bool resized = names.SetBounds(2, 6);
int lastIndex = names.GetUpperBound(1); // 6
names.SetBounds(0, Sys.AC_Dynamic); // Enable growth; this does not reset the lower bound.
names.SetBounds(0, -1); // Clear the dynamic array.
SetLength(dim, length)
Changes the logical length of a dimension.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
| length | Int32 | The new dimension length. |
Resizes the backing storage as needed while retaining the configured lower bounds. Invalid dimensions or lengths cause exceptions.
SetLowerBound(dim, bound)
Changes a dimension's lower bound while retaining its length.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
| bound | Int32 | The new nonnegative lower index. |
Returns: Boolean. True if accepted; false for an invalid dimension or negative bound.
SetUpperBound(dim, bound)
Changes a dimension's upper bound.
| Parameter | Type | Description |
|---|---|---|
| dim | Int32 | The one-based dimension number. |
| bound | Int32 | The upper index, AC_Dynamic for the first dimension, or -1 to clear a dynamic array dimension. |
Returns: Boolean. True if accepted; false for an invalid dimension, rejected bound, or invalid dynamic request.
Example:
using PPJ.Runtime;
SalArray<SalNumber> matrix = new SalArray<SalNumber>(2, 3);
bool resized = matrix.SetUpperBound(2, 4); // Dimension 2, indexes 0 through 4.
int lastColumn = matrix.GetUpperBound(2); // 4
matrix[1, 4] = 42;
// Only the first dimension can be made dynamic.
bool dynamicRows = matrix.SetUpperBound(1, Sys.AC_Dynamic);
Sort(index, count, comparer)
Sorts a range of a one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| index | Int32 | The first array index to sort. |
| count | Int32 | The number of elements to sort. |
| comparer | IComparer | The comparer, or null to use the default element comparison. |
Empty arrays are unchanged. Nonempty multidimensional arrays are not supported.
Sort(comparer)
Sorts the logical elements beginning at index zero.
| Parameter | Type | Description |
|---|---|---|
| comparer | IComparer | The comparer, or null to use the default element comparison. |
For arrays with a nonzero lower bound, use the overload that accepts an index and count.
Sum()
Adds the elements after decimal conversion.
Returns: SalNumber. The sum, or zero if no non-null elements are encountered.
Null object references are skipped. SAL null values use their conversion behavior. Unsupported element conversions and decimal overflow propagate.
ToNativeArray()
Copies the logical elements into an array of CLR values.
Returns: Object. A new array with the corresponding element type and dimension lengths.
Maps SalNumber and SalBoolean to decimal, SalString to string, SalDateTime to DateTime, and SalWindowHandle to IntPtr. Other types are unsupported. Conversion does not preserve separate SAL null flags.
Inherited By
| Name | Description |
|---|---|
| SalArray<T> | Provides a typed SAL array with dynamic first-dimension growth and optional explicit bounds. |
Implements
| Name | Description |
|---|---|
| ISalType | Exposes a SAL value in the form used for database parameter binding. |