FindVariant

The FindVariant method searches file for specified variant data and returns position of matching data in file.
C++
long FindVariant(
  VARIANT *VariantData,               // variant containing searched data
  long NumberOfElements = -1,         // number of elements in data sequence
  long StartingPosition = 0,          // starting position of search
  long Range = -1,                    // search range
  long Options = 0                    // search options
);
BASIC
FindVariant(
  VariantData As Variant,             // variant containing searched data
  NumberOfElements As Long = -1,      // number of elements in data sequence
  StartingPosition As Long = 0,       // starting position of search
  Range As Long = -1,                 // search range
  Options As SearchOptions = 0        // search options
) As Long

Parameters

VariantData
Variant containing data sequence to be searched for.
Variant can be of any allowed type; it can be either single variable or one-dimensional array.
NumberOfElements
Number of elements in data sequence to be matched.
If this parameter is -1, length of searched sequence is determined by the number of elements in VariantData.
StartingPosition
Starting position of search in file.
If this parameter is -1 search begins at current file position.
If this parameter is 0 and Options have IXF_FIND_REVERSE flag set, search begins from the end of file.
Range
Length of file region to be searched, in bytes.
If this parameter is -1 search is continued until end of file or beginning of file depending on search direction.
Options
Search options, specified as a combination of the following values:
IXF_FIND_REVERSE backward search (towards beginning of file).

Return Values

If the method succeeds, the return value is the position of matching sequence in file.
The return value is IXF_FAILURE_NOTFOUND if specified data sequence has not been found.
If the method fails, the return value is failure code and error code is set. Call GetError to get error code.

Remarks

Data is searched in file starting from StartingPosition and continuing until matching sequence is found or search region has ended. File data must match entire sequence and must be positioned entirely within search region; it means that 'matching' sequence which starts within search region but ends beyond it is not recognized as matching.

StartingPosition always specifies absolute starting position in file regardless of direction of search. The only exception is when this parameter is 0 and Options have IXF_FIND_REVERSE flag set; in such situation search begins from the end of file.

VariantData variant can be a single variable or one dimensional array (possibly with nested subarrays) of one of allowed types: Byte, Integer, Long, Single, Double, String, Boolean, Date, Currency, Decimal and Variant. The array of variants is especially interesting because it allows searching for complex structured data with fields of various types. The only limitation is that all arrays must be one dimensional. As mentioned above, VariantData can contain String data; it should be noted, however, that text in variant is always represented by IXFile as length-prefixed Unicode and search is not case sensitive.

NumberOfElements parameter always specifies total number of elements in data sequence regardless of its structure. It means that if VariantData consists of nested subarrays, NumberOfElements specifies number of elements counted recursively through all subarrays - not elements in most outer array.

See Also

FindByte, FindShort, FindLong, FindFloat, FindDouble, FindText, FindUnicodeText, FindBinary, Finding Data