H5StringDatasetSet Method (BaseArrayString, StringPadding, BaseArray)

public void Set(
	BaseArray<string> A,
	StringPadding padding = StringPadding.NULLTERM,
	params BaseArray[] range
)

Public Sub Set ( 
	A As BaseArray(Of String),
	Optional padding As StringPadding = StringPadding.NULLTERM,
	ParamArray range As BaseArray()
)

Dim instance As H5StringDataset
Dim A As BaseArray(Of String)
Dim padding As StringPadding
Dim range As BaseArray()

instance.Set(A, padding, range)

Parameters

A

Type: ILNumericsBaseArrayString
Data to overwrite the existing element values with.

padding (Optional)

Type: ILNumerics.IO.HDF5StringPadding
[Optional] The padding method for the new strings in memory. For fixed length strings only. Default: NULLTERM.

range

Type: ILNumericsBaseArray
[optional] Definition of the area in the existing data to overwrite. A good subset of the full ILNumerics subarray feature set is allowed.

If the optional argument range is omitted, A will replace the whole existing data and the size of the existing array is adjusted to match the size of A.

While the rank of range (i.e. the number of dimensions addressed by range) must match the rank of the array stored, the size of A does not need to have the same rank. However, the number of elements addressed by range must be lower than or equal to the number of elements stored in A. If A contains more elements than addresseb by range, subsequent elements in A will be ignored.

If range fully or partly addresses an area of the dataset which lays outside of the current dimension size(s) of the dataset, the dataset will be expanded just as much that A can be stored in the addressed region. The length of dimensions not affected by the expansion will stay untouched.

If range is given, it is used to describe that part of the existing array in the file which will be overwritten with the values in A. The HDF5 hyperslab feature is used for that. Therefore, the range specification must be compatible with the capabilities of the HDF5 hyperslab feature. Otherwise, an ArgumentException is thrown. Consult the ILNumerics HDF5 online manual for all options of valid range specifications.

Note that the requirements on the range parameter are higher than for Get(BaseArray) since using hyperslabs is the only way of dealing with partial writes to HDF datasets here: for Get(BaseArray), if the range was not compatible, we could fetch the complete array and derive the subarray in memory using the full spectrum of ILNumerics subarray features. For [!:Set(InArray<string>, StringPadding, BaseArray[])] one might argue that we could go the same way: fetch the whole array, manipulate in memory and write it back to the dataset. However, this is not easily applicable, since in order to fetch the array, we would need to define a type for its elements. Set, on the other side does not request/provide a type. This limitation might get removed in a future version of ILNumerics.IO.HDF5 by constructing the element type out of the actual type stored in the dataset.

The optional padding parameter specifies the padding method for the new strings in memory. This parameter is ignored on variable length strings. For fixed length strings, with Length <= 0 allows to create full roundtrips even for such strings which are not null-terminated in the managed heap. Example: New strings in A were read from a FORTRAN source. Those strings commonly retain trailing spaces ("one    ") instead of cutting the string's remaining characters up to the fixed length ("one"). The [!:Set(BaseArray, BaseArray[])] function would not be able to distinguish those trailing characters from useful string content - especially if the padding parameters for both, the dataset and the new strings in memory do not match. In such situations the padding parameter can be used to adjust the padding to the method used in the memory strings. Here: SPACEPAD. An alternative here would be to use Trim on each element of A, matching the padding with the default padding of NULLTERM.

[ILNumerics HDF5 Module]

Reference

Other Resources