Running SuperFastDistinct! 
All it takes is one call to our SuperFastDistinct() function. Pass it the table and the index field name(s) that contain the distinct values you wish to retrieve. The function returns the number of distinct values found and the distinct values are returned either in a TString or a TTable (or 3rd party table). A TString makes it easy to put the distinct values in a TComboBox, TMemo, or any other TString compatible component. The TStrings.SaveToFile method makes it easy to write the results to a text file. SuperFastDistinct() can also save the distinct values to a table so they can be used in dataset controls or in other applications. Syntax: function SuperFastDistinct(DatasetIn : TDataset;
IndexFieldNamesIn : String;
OutObject : TObject=nil;
Options : String='';
OutTableFieldNames: String=''): Integer; DatasetIn
A TTable or 3rd party table such as TDBISAMTable (but not a query). The table does not have to be open or have the correct index set prior to calling SuperFastDistinct(). But it does have to point to a valid directory or database and be able to be opened without any errors. In other words, it has to point to a valid table.
Note: To activate support for 3rd party tables such as Advantage, DBISAM or NexusDb or kbmMemTable, see the Installation section. IndexFieldNamesIn
The index field name(s) used to find the distinct values you are looking for. The field name(s) must be part of an index but it does not have to be the active index. If there is more than one field in the index, then separate them with a semicolon ";".
If it is a compound index, use only enough fields that contain the distinct value(s) you are looking for. In other words you do not need to specify all the fields of a compound index. If the index is made up of the fields 'Country;State;City', then to get just the distinct countries use 'Country'. If you want distinct Country & State then use 'Country;State' or to get distinct Country & State & City use 'Country;State;City'.
If the last field of IndexFieldNames is in descending order, then you will need to add 'Desc' to the Options parameter (see below) to indicate the index is in descending order.
OutObject (Optional)
This is the TStrings or TDataset object that will receive the distinct values returned by SuperFastDistinct(). If this parameter is missing, then only the number of distinct values found will be returned by the function.
Example: |
ComboBox1.Items |
| |
Memo1.Lines |
| |
ListBox1.Items |
| |
CheckListBox1.Items |
| |
StringsList |
| |
Table1 |
| |
adsTable1 |
| |
nxTable1 |
| |
dbisamTable1 |
| |
kbmMemTable1 |
|
If OutObject is a table (we call this an "output table"), then it has to be already instantiated and the necessary table properties defined (the table fields do not need to be defined). This output table can use a different database engine from DatasetIn. For example, DatasetIn may be a Paradox table and OutObject can be a kbmMemTable memory table. The output table does not have to physically exist on the hard drive and it does not need to have any of its fields defined prior to calling SuperFastDistinct(). The fields for the table will be created automatically if you use 'BuildOutputTable' in the Options parameter (see Options below). By default any exisitng rows in the output table are deleted before any new distinct values are added. But they can be preserved if 'AppendOutputTable' option is used. Options (Optional)
This is a comma-delimited string that is used to pass options to the SuperFastDistinct() function. It does not matter which order these options appear.
'Desc' (optional)
If the last field of IndexFieldNames is part of an index that is in descending order, then you will need to specify 'Desc' in the options. This is necessary because there may be two indexes with the same field names, one index in ascending order and the other in descending order. By specifying "Desc" you are telling it which index to use. If you do not specify "Desc" then it is assumed the index is in ascending order. If you are using a descending index and forget to include 'Desc', you're likely to get only 1 distinct value returned. 'Delim=","' (optional)
This option is used only if OutObject is a TStrings object and IndexFieldNames is made up of more than 1 field (compound index). This parameter is ignored if OutObject is a table. This delim value is a string that is inserted between distinct values of a compound index, such as when IndexFieldNames is 'Country;State;City'. If IndexFieldNames is only one field, then this parameter is ignored.
Example: 'Delim="," ' (default value)
This will insert a comma between the distinct values returned as in "United States,Nevada,Las Vegas".
A "," is the default delimeter. To use no delimiter, use 'Delim="" '
Note: The comma had to be put inside of double quotes " " otherwise it would have been interpreted as an empty value because the comma delimits the options. The comma is the default delimiter so if you omit the Delim parameter, a "," is inserted between values of a compound index. To insert a Tab between fields, use 'Delim='#09
To insert a couple of dashes use 'Delim=--' or a slash use 'Delim=/'
'BuildOutputTable' (optional)
When the OutObject is a table, the 'BuildOutputTable' option will have SuperFastDistinct() rebuild the output table using the same field names and field types as specified by IndexFieldNamesIn. It is these fields in the output table that will hold the distinct values that were found in DatasetIn. A primary index will be built on these fields to allow for faster retrieval and sorting. Any existing rows of the output table will be deleted. The output table must use a database engine that we support (see 3rd Party Support above). Example: 'BuildOutputTable' AppendOutputTable (optional)
When the OutObject is a table and the AppendOutputTable option is not used (default), SuperFastDistinct() will delete the existing rows from the output table before the distinct values are added to it. This default behavior can be overridden so it keeps the existing rows that is already in the output table and will append the newly found distinct values onto the end of the table.
OutTableFieldNames (Optional)
This parameter is used only if OutObject is a table and the output table field names are not the same as IndexFieldNamesIn. OutTableFieldNames are the field names to be used in the output table (OutObject) to store the distinct values. The number of fields specified in OutTableFieldNames should match the number of the fields in the IndexFieldNamesIn parameter. Each field name is separated by a ';' as it is with IndexFieldNamesIn.
If this parameter is missing, then it is assumed the output table has the same field names as IndexFieldNamesIn. If the output table does not exist or it does not have these field names, then you must use 'BuildOutputTable' option to automatically delete the output table and rebuild it with these field names. Otherwise an exception will occur because the output table does not have the fields you specified in OutTableFieldNames. Examples
|
