ILNumerics Ultimate VS

ConcreteArrayT1, LocalT, InT, OutT, RetT, StorageTExportValues Method

ILNumerics Ultimate VS Documentation
ILNumerics - Technical Application Development
(Expert API) Export (copy) values into System.Array.

[ILNumerics Core Module]

Namespace:  ILNumerics.Core.Arrays
Assembly:  ILNumerics.Core (in ILNumerics.Core.dll) Version: 5.4.0.0 (5.4.7431.3055)
Syntax

public virtual void ExportValues(
	ref T1[] result,
	StorageOrders layout = StorageOrders.ColumnMajor
)

Parameters

result
Type: T1
System.Array with a copy of all element values from this array.
layout (Optional)
Type: ILNumericsStorageOrders
[Optional] The storage layout of the elements to write to result.
Remarks

The System.Array can be predefined. If its length is sufficient, it will be used and its leading elements will be overwritten when function returns. If result is null or has too few elements, it will be recreated from the _GC managed heap_.

Excessive use of this method can be a hint of suboptimal design! Especially if no array /no sufficiently long array is provided in result the returned array will be created on the managed heap. This works around the ILNumerics memory management and may increases the pressure on the GC and can lead to frequent garbage collections and bad performance! Make sure to reuse the array result.

Iflayout is null orOther the storage layout of this array will be used to store the elements into result. Make sure that the array result is large enough, even if the current storage layout corresponds to non-continously stored elements and may contain holes! Use GetElementSpan to compute the absolute number of elements in result necessary to hold all elements of this storage in its current storage order. Note further, that any potential holes in the element storage will not be cleared!

Exporting values of Cell arrays gives a clone of the individual cell elements. Special care must be taken when working with arrays of type BaseArray. Its use is not recommended! Failing to handle BaseArray instances properly may result in additional memory pressure, increased GC activation and unexpected NullReferenceException when accessing (automatically) disposed BaseArray objects.

If - for some reasons - one needs to use ExportValues(T1, StorageOrders) on Cell arrays nevertheless the following hints may serve as a rough guideline:

  • Objects returned in result are return type objects or null. Return type objects will dispose their content and itself after the first use. Make sure to utilize each object exactly once!
  • Directly using an object in result multiple times may give an error or unwanted side effects.
  • In order to work with or to access a returned object multiple times it must be (immediately) converted to a local array of the corresponding kind: ArrayT, Logical, or Cell. This, if course, requires knowledge of the actual type of the object from within the cell.
  • Failing to use the array at least once may leaves references to other data arrays (memory handles) open. This may causes memory pressure on the GC and bad performance. However, in ILNumerics memory leaks (as for native languages) cannot happen.

[ILNumerics Core Module]

See Also

Reference