Finding Data

Finding Data

IXFile provides search capabilities for most of commonly used types of data: integral and floating point numbers, ANSI and Unicode texts, variants and binary structures. With FindByte, FindShort, FindLong, FindFloat, FindDouble, FindText, FindUnicodeText, FindVariant and FindBinary methods, you can search currently attached file for a data sequence of specified length. File region can be defined with its starting position and length to limit range of search. Search options can be also specified to determine direction of search and other parameters depending on type of data. Data is searched in specified region 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, which means that 'matching' sequence which starts within search region but ends beyond it, is not recognized as matching.

Text search supports both ANSI and Unicode character sets, length-prefixed and raw strings, as well as case insensitivity. IXFile represents text as length-prefixed by default. Actual text data in file is preceeded with a long number specifying length of the text in characters (single- or double-byte). Text is searched for the same way - both text data and its length prefix must match, which means that you cannot search for a subpart of length-prefixed text. To search for a substring (or texts stored as a raw character strings without length prefix), IXF_FIND_TEXT_STRING flag should be specified in search options. With this option enabled, text is searched for as a raw sequence of characters ignoring length prefix and any matching sequence successfully finishes processing.

IXFile also supports searching for structured data containing fields of various types. With FindBinary method you can search for binary block of data which can represent arbitrary data structure. In such case entire structure should be treated as a sequence of bytes whose length is equal to total size of the structure. File data must be, however, in machine (little-endian) byte order because there is no way to determine structure of data and types of fields for big-endian conversion. In other words method does not interpret data and therefore it is user responsibility to correctly build search sequence. Method can be also used for searching data of simple types that are not directly supported like Boolean, Date, Currency or Decimal. In such case number of elements in searched sequence must be specified as well as size of each element to properly handle big-endian conversion.

Visual Basic developers would preferably use FindVariant method for the purpose of searching structured data. Big advantage of this method relies on known structure of searched data; each data field is of known type and therefore can be correctly handled by IXFile, relieving developers of technical details of data storage. Searched 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. With such possibilities you can create really complex data to be searched for; the only limitation is that all arrays must be one dimensional. Text in variant is always represented by IXFile as length-prefixed Unicode string and therefore it is not possible to search for structures containing partial texts. Method also allows to specify number of elements of variant that constitute searched sequence; by default all elements are used but you can specify that only some initial fields should be recognized. Please note, however, that number of elements always specifies total number of elements in data sequence regardless of its structure; in other words, if variant consists of nested subarrays, it specifies number of elements counted recursively through all subarrays and not elements in most outer array.

Examples

C++


// error handling is omitted for clarity


  int main(int, char**)
  {
   IFile ixf;
   struct
   {
    short shrt[2];
    char txt[100];
   } data;
   long lng, pos;
   short shrt;
   char txt[10];

   ixf.SetLicenseKey("YOURLICENSEKEY");

// default initialization 
// read/write access, auto file closing, 16KB buffer

   ixf.Initialize(); 

// open file and truncate to zero size; create if does not exist
// mode of operation forces read/write access to the file

   ixf.Open("test.bin", TRUE, TRUE); 

// initialize structure members
  
   memset(&data, 0, sizeof(data));
   data.shrt[0] = 7;
   data.shrt[1] = 0;
   strcpy(data.txt, "This is a test");

// write enire structute at once
// starting from beginning of file
// 104 bytes are written
  
   ixf.PutBinary(&data, sizeof(data), 1);	

// search for short integer 0
// should be found on position 1 because
// second and third byte form short integer
  
   shrt = 0;
   pos = ixf.FindShort(&shrt, 1);

// search for long integer 7
// should be found on position 0 because
// first and second short integer form long integer
  
   lng = 7;
   pos = ixf.FindLong(&lng, 1);

// search for ANSI text stored as a fixed length string
// search region is 100 bytes starting from end of file
// should be found on position 14
  
   strcpy(txt, "TEST");
   pos = ixf.FindText(txt, -1, 0, 100, IXF_FIND_TEXT_STRING | IXF_FIND_TEXT_REVERSE);

// search for ANSI text stored as a length-prefixed string
// should be found on position 0 because
// first and second short integer (7) form correct length prefix
  
   strcpy(txt, "This is");
   pos = ixf.FindText(txt, -1, 0, -1, IXF_FIND_TEXT_MATCHCASE);

// search for first 8 bytes of structure
// 2 short integers + 4 characters
// should be found on position 0
  
   memset(&data, 0, sizeof(data));
   data.shrt[0] = 7;
   data.shrt[1] = 0;
   strcpy(data.txt, "This");
   pos = ixf.FindBinary(&data, 8, 1);

   .
   .
   .

   return(0);

  }

BASIC


' error handling is omitted for clarity


  Sub Main()

   Dim ixf As IXFile
   Dim data(1) As Variant
   Dim shrt(1) As Integer
   Dim txt As String
   Dim pos As Long, lng As Long

   Set ixf = New IXFile
   ixf.SetLicenseKey "YOURLICENSEKEY"

' default initialization 
' read/write access, auto file closing, 16KB buffer

   ixf.Initialize

' open file and truncate to zero size; create if does not exist
' mode of operation forces read/write access to the file

   ixf.Open "test.bin", True, True 

' initialize structure members
  
   shrt(0) = 0
   shrt(1) = 7
   txt = "This is a test"
   data(0) = shrt
   data(1) = txt

' write enire structute at once
' starting from beginning of file
' 36 bytes are written
' text is written as a length-prefixed Unicode string
  
   ixf.PutVariant data	

' search for short integer 7
' should be found on position 2 
  
   shrt(0) = 7
   pos = ixf.FindShort(shrt(0))

' search for long integer 14
' should be found on position 4 because
' length prefix of text is matching
  
   lng = 14
   pos = ixf.FindLong(lng)

' search for Unicode text stored as a fixed length string
' search region is 10 bytes starting from end of file
' case-insensitive search
' should be found on position 28
  
   txt = "TEST"
   pos = ixf.FindUnicodeText(txt, -1, 0, 10, IXF_FIND_TEXT_STRING Or IXF_FIND_TEXT_REVERSE)

' search for Unicode text stored as a length-prefixed string
' case-sensitive search
' should be found on position 4
  
   txt = "This is a test"
   pos = ixf.FindUnicodeText(txt, -1, 0, -1, IXF_FIND_TEXT_MATCHCASE)

' search for entire variant
' variant text search is always case insensitive
' should be found on position 0 
  
   data(0)(0) = 0
   data(0)(1) = 7
   data(1) = "THIS IS A TEST"
   pos = ixf.FindVariant(data)

   .
   .
   .

  End Sub

Examples

C++

BASIC

See Also