Search API

xlsgen > overview > Search API

As showcased here, xlsgen exposes a search API consumed by xlssearch to provide an easy to use and rather flexible search tool to everyone.

But search need not be performed through the user interface, developers might be interested in performing search their own way and gathering results differently. That's what the search API is for.

Search object model

The Search object model

As the object model shows, the search API performs search in an Excel workbook on a file-by-file basis. If you need support for entire folders, you need to add the file retrieval mechanism.

Since xlsgen is thread-safe, you can perform more than one search at a time. A typical scenario would create a separate worker thread, pass a pointer to xlsgen to each, and perform a search there. This is what xlssearch does by the way.

For more information on interfaces, see IXlsSearch, IXlsSearchOptions, IXlsSearchResults, IXlsSearchWorksheetResult and IXlsSearchResult.

A sample code

The following code shows how easy it is to use the search API. Developers interested in integration with other tools like Windows explorer, Google search engines or assimilated, might insulate the search object model exposed by xlsgen and expose their own.

VB code


  Dim engine As CoXlsEngine
  Set engine = CreateObject("ExcelGenerator.ARsTDesign")

  ' open Book10.xls and start a search session
  '
  Dim srch As IXlsSearch
  Set srch = engine.Search("C:\MyDocuments\Book10.xls")

  Dim options as IXlsSearchOptions
  Set options = srch.Options
  options.CaseSensitive = True
  options.UsesWildcards = True

  ' find he*o in cells
  '
  Dim results As IXlsSearchResults
  Set results = srch.SearchKeyword("he*o")

  ' results
  '
  nbWorksheetCount = results.WorksheetCount

  For i = 1 To nbWorksheetCount
    Dim wkshtresults As IXlsSearchWorksheetResult
    Set wkshtresults = results.WorksheetItem(i)

    cellcount = wkshtresults.Count
    For j = 1 To cellcount

      Dim result As IXlsSearchResult
	  Set result = wkshtresults.Item(j)

      row = result.row
      col = result.col

      ' if row == 0 and col == 0, the worksheet name itself is a match
      MsgBox "Match in r=" & row & ", c=" & col

    Next ' j
  Next ' i

  ' export the results into a tabular file
  '
  results.Export "results.txt"

  Set engine = nothing

C# code

  xlsgen.CoXlsEngine engine = new xlsgen.CoXlsEngine();

  // open Book10.xls and start a search session
  //
  xlsgen.IXlsSearch srch = engine.Search( @"C:\MyDocuments\Book10.xls" );

  xlsgen.IXlsSearchOptions options = srch.Options;
  options.CaseSensitive = 1;
  options.UsesWildcards = 1;

  // find he*o in cells
  //
  xlsgen.IXlsSearchResults results = srch.SearchKeyword("he*o");

  // results
  //
  int nbWorksheetCount = results.WorksheetCount;
  for (int i = 1; i <= nbWorksheetCount; i++)
  {
    xlsgen.IXlsSearchWorksheetResult wkshtresults;
    wkshtresults = results.get_WorksheetItem(i);

    int cellcount = wkshtresults.Count;
    for (int j = 1; j <= cellcount; j++)
    {
      xlsgen.IXlsSearchResult result = wkshtresults.get_Item(j);

      long row = result.row;
      long col = result.col;

      // if row == 0 and col == 0, the worksheet name itself is a match
      String s;
      s = String.Format("Match in r={0}, c={1}", row, col);
      System.Diagnostics.Debug.WriteLine(s);
    }
  }

  // export the results into a tabular file
  //
  results.Export("results.txt");

  engine = null;

C/C++ code

{ 
  xlsgen::IXlsEnginePtr engine( __uuidof(xlsgen::CoXlsEngine) );

  // open Book10.xls and start a search session
  //
  xlsgen::IXlsSearchPtr srch;
  srch = engine->Search(L"C:\\MyDocuments\\Book10.xls");

  xlsgen::IXlsSearchOptionsPtr options;
  options = srch->Options;
  options->CaseSensitive = TRUE;
  options->UsesWildcards = TRUE;

  // find he*o in cells
  //
  xlsgen::IXlsSearchResultsPtr results;
  results = srch->SearchKeyword(L"he*o");

  // results
  //
  long nbWorksheetCount = results->WorksheetCount;
  for (long i = 0; i < nbWorksheetCount; i++)
  {
    xlsgen::IXlsSearchWorksheetResultPtr wkshtresults;
    wkshtresults = results->WorksheetItem[1 + i];

    long cellcount = wkshtresults->Count;
    for (long j = 0; j < cellcount; j++)
    {
      xlsgen::IXlsSearchResultPtr result;
      result = wkshtresults->Item[1 + j];

      long row = result->row;
      long col = result->col;

      // if row == 0 and col == 0, the worksheet name itself is a match
      char s[64];
      sprintf(s,"Match in r=%d, c=%d\r\n", row, col);
      OutputDebugString(s);

    }
  }

  // export the results into a tabular file
  //
  results->Export(L"results.txt");
}