The built-in functions in the RecArray package allow you to create and manipulate values of type Record and RecArray. You can think of a RecArray as a table of information where each column has a name and each row is a Record. Records and RecArrays are frequently used together. If you just need a name-value association, you may want to use an Assoc instead. Fields (or columns) in a Record or RecArray can be referenced by name or by index. Records and RecArrays use one-based indexes. Records and RecArrays are both reference data types. For more information, including an example of using Records and RecArrays, please see the OScript Language Reference.

Class Attributes Index

o RecArrayType
Specifies a value of type RecArray.
o RecordType
Specifies a value of type Record.

Class Methods Index

o AddField( RecArray theRecArray, Dynamic fieldNames )
Adds a field to a RecArray if a field with the specified name does not exist.
o AddRecord( RecArray theRecArray, [List values] )
Adds a Record to the end of the RecArray.
o Allocate( RecArray theRecArray, Integer numRecords )
Allocates space into which a RecArray can expand.
o ColumnToList( RecArray theRecArray, Dynamic colRef )
Returns a List containing the values stored in a RecArray column.
o Copy( RecArray theRecArray )
Duplicates a RecArray.
o Create( [List fieldNames], [Integer numRecords] )
Creates a new RecArray.
o CreateRecord( [List fieldNames], [List values] )
Creates a Record containing the specified field names and values.
o DropField( RecArray theRecArray, Dynamic fieldName )
Removes the specified field from a RecArray.
o DropRecord( RecArray theRecArray, Integer index1, [Integer index2] )
Removes one or more Records from a RecArray.
o FieldNames( Dynamic theRecArray )
Returns the names of the fields in the specified RecArray or Record.
o GetRecord( Dynamic value, [Integer index] )
Returns a List containing the values stored in the specified Record.
o InsertRecordAt( RecArray theRecArray, Dynamic values, Integer position )
Inserts a Record into a RecArray at the specified position, moving all subsequent Records down.
o IsColumn( Dynamic value, String fieldName )
Returns the Integer (1-based) index of a field in a Record or RecArray.
o RenameField( RecArray theRecArray, Dynamic oldField, String newField )
Changes the name of a field in a RecArray.
o SetRecord( Dynamic toReplace, Dynamic values, [Integer position] )
Replaces the contents of the specified Record.
o Sort( RecArray theRecArray, Dynamic sortVal, [Boolean ignoreCase] )
Sorts a RecArray in place according to the specified fields.

Class Attributes

o RecArrayType 
 Integer RecArrayType

Specifies a value of type RecArray.

o RecordType 
 Integer RecordType

Specifies a value of type Record.

Class Methods

o AddField 
 Integer AddField(
              RecArray theRecArray,
              Dynamic fieldNames )

Adds a field to a RecArray if a field with the specified name does not exist.

Parameters:
theRecArray  -  The RecArray to which the field will be added.
fieldNames  -  Either a String indicating the name of the field to add or a List containing String elements indicating multiple fields to add.
Returns:
The index of the newly added field. If the field already exists, its index is returned. If more than one field is added, the index of the last field added is returned.
o AddRecord 
 Integer AddRecord(
              RecArray theRecArray,
             [List values] )

Adds a Record to the end of the RecArray.

If there are fewer elements in the values List than there are fields, the unspecified field values are set to Undefined. If there are more elements in the values List than there are fields, the extra elements in the List are ignored.

Parameters:
theRecArray  -  The RecArray to which the Record will be added.
values  -  An optional List of values to add, containing one value for each field in the Record. If not specified, a Record with Undefined values is added.
Returns:
The position of the added Record in the RecArray. For example, if there are four Records in the specified RecArray, the result of executing the RecArray.AddRecord function would be 5.
o Allocate 
 Integer Allocate(
               RecArray theRecArray,
               Integer numRecords )

Allocates space into which a RecArray can expand.

This function can be used to optimize performance during RecArray creation. The most efficient procedure for filling a RecArray is to create the RecArray, use the RecArray.Allocate function to allocate space for the desired number of Records, and then add the Records.

Note that the numRecords parameters specifies the desired size of the RecArray, irrespective of any existing records. For example, if theRecArray contains five Records and you Allocate 10, the RecArray will contain 10 Records, not 15. If you Allocate the same RecArray to three Records, the RecArray will be truncated so that it contains only three Records.

Parameters:
theRecArray  -  The RecArray in which to pre-allocate space.
numRecords  -  The desired size of the RecArray.
Returns:
The number of records in the RecArray.
o ColumnToList 
 List ColumnToList(
             RecArray theRecArray,
             Dynamic colRef )

Returns a List containing the values stored in a RecArray column.

Parameters:
theRecArray  -  The RecArray from which to retrieve the values.
colRef  -  Either a String containing the name or an Integer containing the (1-based) index of the desired column.
Returns:
A List of values stored in the specified column. If the colRef parameter is not a String or an Integer, if the field name is not found, or if the index is out of range, Undefined is returned. If the RecArray contains no Records, an empty List is returned.
o Copy 
 RecArray Copy(
             RecArray theRecArray )

Duplicates a RecArray.

Parameters:
theRecArray  -  The RecArray to duplicate.
Returns:
A new RecArray, identical in format and content to the original.
o Create 
 RecArray Create(
             [List fieldNames],
             [Integer numRecords] )

Creates a new RecArray.

Parameters:
fieldNames  -  An optional List of String names for the fields in the RecArray. If this parameter is not specified, a RecArray with no fields or Records is created. Fields can later be specified using the RecArray.AddField function; Records can be added using RecArray.AddRecord or RecArray.InsertRecordAt, or by using the index operator ([ ]).
numRecords  -  An optional Integer indicating the number of Records (containing Undefined field values) to add. No Records are added if this parameter is not specified.
Returns:
A new RecArray.
o CreateRecord 
 Record CreateRecord(
              [List fieldNames],
              [List values] )

Creates a Record containing the specified field names and values.

Parameters:
fieldNames  -  A List of String elements indicating the desired field names. Defaults to Undefined if not specified.
values  -  The values to be stored in the Record. The values will be inserted in the order in which they are contained in the List. Defaults to Undefined if not specified.
Returns:
A new Record.
o DropField 
 Boolean DropField(
              RecArray theRecArray,
              Dynamic fieldName )

Removes the specified field from a RecArray.

Parameters:
theRecArray  -  The RecArray from which the field will be removed.
fieldName  -  Either a String indicating the name or an Integer indicating the (1-based) index of the field to be dropped. If the specified field does not exist, the RecArray is not modified.
Returns:
TRUE if the specified field was removed from the RecArray.
o DropRecord 
 Boolean DropRecord(
               RecArray theRecArray,
               Integer index1,
              [Integer index2] )

Removes one or more Records from a RecArray.

Parameters:
theRecArray  -  The RecArray from which you want to drop the Record(s).
index1  -  The Integer (1-based) index of the first Record to drop.
index2  -  The Integer (1-based) index of the last Record to drop.
Returns:
TRUE if the specified Records were removed from the RecArray.
o FieldNames 
 List FieldNames(
            Dynamic theRecArray )

Returns the names of the fields in the specified RecArray or Record.

Parameters:
theRecArray  -  The Record or RecArray whose field names you want to retrieve.
Returns:
A List containing String field name elements.
o GetRecord 
 List GetRecord(
           Dynamic value,
          [Integer index] )

Returns a List containing the values stored in the specified Record.

Parameters:
value  -  Either a Record whose data will be returned or a RecArray from which a specified Record’s data will be returned.
index  -  An Integer (1-based) index of the Record to retrieve. Specify this parameter only if the value parameter is a RecArray.
Returns:
A List containing one element for each field in the specified Record.
o InsertRecordAt 
 Record InsertRecordAt(
                RecArray theRecArray,
                Dynamic values,
                Integer position )

Inserts a Record into a RecArray at the specified position, moving all subsequent Records down.

If the values parameter is a List, and too few values are passed, the remaining values in the Record are Undefined. If too many values are passed, the extra values are ignored.

If the values parameter is a Record, it should have the same format (same name and number of fields) as the RecArray into which it will be inserted. If it has a different format, a new Record is created with the proper format, and filled with values from the specified Record (the value in the first field of the specified Record is copied to the first field of the new Record, and so on). If there are too few fields in the specified Record, the new Record is padded with Undefined values. If there are too many fields in the specified Record, the extra fields are ignored.

If the value of the position parameter is greater than the length of the RecArray, Records with all Undefined values will automatically be added to the RecArray, expanding it to include the number of Records as specified by the position parameter.

Parameters:
theRecArray  -  The RecArray to modify.
values  -  A Record or List of values to insert.
position  -  An Integer (1-based) index indicating the desired position of the new Record.
Returns:
The inserted Record.
o IsColumn 
 Integer IsColumn(
              Dynamic value,
              String fieldName )

Returns the Integer (1-based) index of a field in a Record or RecArray.

Note: it is more efficient to reference a field by its Integer index than by its String name.

Parameters:
value  -  TheRecord or RecArray in which to look for the field.
fieldName  -  The field name for which to search.
Returns:
The 1-based field index if found, 0 otherwise.
o RenameField 
 Boolean RenameField(
               RecArray theRecArray,
               Dynamic oldField,
               String newField )

Changes the name of a field in a RecArray.

Parameters:
theRecArray  -  The RecArray containing the field to rename.
oldField  -  Either a String indicating the name or an Integer indicating the (1-based) index of the field to rename.
newField  -  The new field name.
Returns:
TRUE if the field was renamed.
o SetRecord 
 Record SetRecord(
             Dynamic toReplace,
             Dynamic values,
            [Integer position] )

Replaces the contents of the specified Record.

If the values parameter is a List, and too few values are passed, the remaining values in the Record are Undefined. If too many values are passed, the extra values are ignored.

If the values parameter is a Record, it should have the same format (same name and number of fields) as the RecArray in which it will be inserted. If it has a different format, a new Record is created with the proper format, and filled with values from the specified Record (the value in the first field of the specified Record is copied to the first field of the new Record, and so on). If there are too few fields in the specified Record, the new Record is padded with Undefined values. If there are too many fields in the specified Record, the extra fields are ignored and the specified Record is left unchanged.

If the value of the position parameter is out of range, the RecArray will not be modified and Undefined will be returned.

Parameters:
toReplace  -  the RecArray or Record on which to operate.
values  -  a Record or List of values for the replacement Record.
position  -  an Integer (1-based) index of the Record to replace. Do not specify if the toReplace parameter is a Record.
Returns:
The replacement Record if successful; otherwise Undefined.
o Sort 
 RecArray Sort(
             RecArray theRecArray,
             Dynamic sortVal,
            [Boolean ignoreCase] )

Sorts a RecArray in place according to the specified fields.

The maximum number of sort values the sortVal parameter can contain is 10.

This function sorts in ascending order by default. If a negative sort index is specified, this function sorts in descending order.

The sortVal parameter can only contain Strings or Integers. If the sortVal parameter contains other data types, the RecArray does not sort and a runtime error is generated.

Parameters:
theRecArray  -  The RecArray to sort.
sortVal  -  A String, Integer, or List indicating the fields by which to sort. If sortVal is a String field name or Integer field index, the RecArray is sorted by the specified column. If sortVal is a List, it can contain field names (Strings), field indices (Integers), or both.
ignoreCase  -  Specifies whether the sort is case-insensitive for all String values, where TRUE indicates a case-insensitive sort.
Returns:
A reference to the sorted RecArray.