SalSafeArray
Namespace: PPJ.Runtime.Com
Assembly: PPJ.Runtime.50 (5.0.0.0)
Wraps a managed array with SAL-compatible safe-array creation, bounds, and typed element access.
- C#
- VB.NET
public class SalSafeArray : SalFunctionalClass
Public Class SalSafeArray
Inherits SalFunctionalClass
Dimension numbers used by the bounds methods start at one. Element indices use the actual lower bounds of the wrapped array. Typed access returns false when no array is assigned or its SAL element category differs; invalid indices and conversion failures can still throw exceptions. Assigning Value wraps the supplied array without copying it.
Example:
var values = new PPJ.Runtime.Com.SalSafeArray(new int[] { 10, 20 });
PPJ.Runtime.SalNumber item = 0;
if (values.GetNumber(ref item, 1))
values.PutNumber(item + 5, 1); // The second element is now 25.
Constructors
SalSafeArray()
Initializes a safe-array wrapper without an underlying array.
SalSafeArray(array)
Wraps the supplied managed array and detects its element type.
| Name | Type | Description |
|---|---|---|
| array | Array | The array to wrap without copying, or null for an empty wrapper. |
Properties
Value
Array: Gets or sets the managed array and updates the cached SAL and COM element-type codes when assigned.
Methods
Create(vt, elements, lowerBound)
Creates a new one-dimensional managed array and replaces the wrapped value.
| Parameter | Type | Description |
|---|---|---|
| vt | SalNumber | A defined COM VarEnum element type that maps to a managed type. |
| elements | SalNumber | The number of elements. |
| lowerBound | SalNumber | The first valid element index. |
Returns: SalBoolean. True after creating the array; false if the COM type is undefined or has no managed type mapping.
Array allocation and invalid dimension errors propagate to the caller.
Create2D(vt, elements1, elements2, lowerBound1, lowerBound2)
Creates a new two-dimensional managed array and replaces the wrapped value.
| Parameter | Type | Description |
|---|---|---|
| vt | SalNumber | A defined COM VarEnum element type that maps to a managed type. |
| elements1 | SalNumber | The length of the first dimension. |
| elements2 | SalNumber | The length of the second dimension. |
| lowerBound1 | SalNumber | The lower bound of the first dimension. |
| lowerBound2 | SalNumber | The lower bound of the second dimension. |
Returns: SalBoolean. True after creating the array; false if the COM type is undefined or has no managed type mapping.
Array allocation and invalid dimension errors propagate to the caller.
CreateMD(vt, elements, lowerBounds)
Creates a new multidimensional managed array and replaces the wrapped value.
| Parameter | Type | Description |
|---|---|---|
| vt | SalNumber | A defined COM VarEnum element type that maps to a managed type. |
| elements | SalArray<SalNumber> | A zero-based SAL array containing the length of each dimension. |
| lowerBounds | SalArray<SalNumber> | A zero-based SAL array containing the lower bound of each corresponding dimension. |
Returns: SalBoolean. True after creating the array; false if the COM type is undefined or has no managed type mapping.
Array allocation and invalid dimension errors propagate to the caller.
GetBoolean(boolean, index)
Reads a Boolean element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
boolean  | SalBoolean | Receives the converted element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetBoolean2D(boolean, index1, index2)
Reads a Boolean element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| boolean | SalBoolean | Receives the converted element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetBooleanMD(boolean, indices)
Reads a Boolean element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| boolean | SalBoolean | Receives the converted element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetDate(date, index)
Reads a date/time element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | Receives the converted element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetDate2D(date, index1, index2)
Reads a date/time element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | Receives the converted element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetDateMD(date, indices)
Reads a date/time element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | Receives the converted element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetLowerBound()
Gets the lower element bound of the first dimension.
Returns: SalNumber. The array bound, or -1 if no array is assigned.
GetLowerBound2D(nDim)
Gets the lower element bound of the specified dimension.
| Parameter | Type | Description |
|---|---|---|
| nDim | SalNumber | The one-based dimension number. |
Returns: SalNumber. The array bound, or -1 if no array is assigned.
Throws:
- IndexOutOfRangeException An array is assigned and the dimension number is outside its rank.
GetLowerBoundMD(nDim)
Gets the lower element bound of the specified dimension.
| Parameter | Type | Description |
|---|---|---|
| nDim | SalNumber | The one-based dimension number. |
Returns: SalNumber. The array bound, or -1 if no array is assigned.
Throws:
- IndexOutOfRangeException An array is assigned and the dimension number is outside its rank.
GetNumber(num, index)
Reads a numeric element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | Receives the converted element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetNumber2D(num, index1, index2)
Reads a numeric element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | Receives the converted element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetNumberMD(num, indices)
Reads a numeric element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | Receives the converted element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetObject(obj, index)
Reads a object element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | An existing wrapper whose Value receives the array element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetObject2D(obj, index1, index2)
Reads a object element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | An existing wrapper whose Value receives the array element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetObjectMD(obj, indices)
Reads a object element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | An existing wrapper whose Value receives the array element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetString(str, index)
Reads a string element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | Receives the converted element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetString2D(str, index1, index2)
Reads a string element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | Receives the converted element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetStringMD(str, indices)
Reads a string element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | Receives the converted element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetUpperBound()
Gets the upper element bound of the first dimension.
Returns: SalNumber. The array bound, or -1 if no array is assigned.
GetUpperBound2D(nDim)
Gets the upper element bound of the specified dimension.
| Parameter | Type | Description |
|---|---|---|
| nDim | SalNumber | The one-based dimension number. |
Returns: SalNumber. The array bound, or -1 if no array is assigned.
Throws:
- IndexOutOfRangeException An array is assigned and the dimension number is outside its rank.
GetUpperBoundMD(nDim)
Gets the upper element bound of the specified dimension.
| Parameter | Type | Description |
|---|---|---|
| nDim | SalNumber | The one-based dimension number. |
Returns: SalNumber. The array bound, or -1 if no array is assigned.
Throws:
- IndexOutOfRangeException An array is assigned and the dimension number is outside its rank.
GetVariant(variant, index)
Reads a variant element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | Receives the converted element on success; unchanged on a false return. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetVariant2D(variant, index1, index2)
Reads a variant element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | Receives the converted element on success; unchanged on a false return. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
GetVariantMD(variant, indices)
Reads a variant element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | Receives the converted element on success; unchanged on a false return. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutBoolean(boolean, index)
Writes a Boolean element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| boolean | SalBoolean | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutBoolean2D(boolean, index1, index2)
Writes a Boolean element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| boolean | SalBoolean | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutBooleanMD(boolean, indices)
Writes a Boolean element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| boolean | SalBoolean | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_BOOLEAN.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutDate(date, index)
Writes a date/time element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutDate2D(date, index1, index2)
Writes a date/time element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutDateMD(date, indices)
Writes a date/time element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| date | SalDateTime | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_DATE.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutNumber(num, index)
Writes a numeric element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutNumber2D(num, index1, index2)
Writes a numeric element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutNumberMD(num, indices)
Writes a numeric element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| num | SalNumber | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_NUMBER.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutObject(obj, index)
Writes a object element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutObject2D(obj, index1, index2)
Writes a object element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutObjectMD(obj, indices)
Writes a object element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| obj | SalObject | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_OBJECT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutString(str, index)
Writes a string element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutString2D(str, index1, index2)
Writes a string element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutStringMD(str, indices)
Writes a string element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| str | SalString | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_STRING.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutVariant(variant, index)
Writes a variant element in the one-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | The value whose underlying managed value is stored in the array. |
| index | SalNumber | The element index within the array's actual bounds. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutVariant2D(variant, index1, index2)
Writes a variant element in the two-dimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | The value whose underlying managed value is stored in the array. |
| index1 | SalNumber | The index in the first dimension. |
| index2 | SalNumber | The index in the second dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.
PutVariantMD(variant, indices)
Writes a variant element in the multidimensional array.
| Parameter | Type | Description |
|---|---|---|
| variant | SalVariant | The value whose underlying managed value is stored in the array. |
| indices | SalArray<SalNumber> | A zero-based SAL array containing one element index for each dimension. |
Returns: SalBoolean. True after accessing the element; false if no array is assigned or its SAL type is not Sys.SAL_VARIANT.
Invalid indices, rank mismatches, and value-conversion errors propagate to the caller.