|
RETURN TO INDEX
codiphone.com
BASIC
LESSON 4 - GROUP IV functions
MyLittleBase 2.0 API is divided into 7 groups of
functions
1- Initialization functions
2-Fields functions
3-Rows functions
4-Navigation functions
5-Data management functions
6-File management functions
7-Utils
This lesson deals with the
fourth group (Navigation functions)
and all what you can do with them.
This fourth group contains functions
BeginningOfFile (4.1)
EndOfFile (4.1)
Go (4.2)
GoFirst (4.2)
GoLast (4.2)
GoNext (4.2)
GoPrevious (4.2)
SavePosition (4.3)
RestorePosition (4.3)
GetPosition (4.3)
BeginSeek (4.4)
EndSeek (4.4)
SeekData (4.4)
SeekFloat (4.4)
MatchData (4.4)
MatchFloat (4.4)
| BeginningOfFile, EndOfFile
are boolean properties to test if the Beginning of the table or the End
of the table have been reached. |
| DELPHI |
C++ |
To test if the
beginning of a table has been reached
use the BeginningOfFile property:
if myinstance.BeginningOfFile then begin
Caption := 'beginning';
end else begin
Caption := 'not beginning';
end;
To test if the end of a table has been reached
use the EndOfFile property:
if myinstance.EndOfFile then begin
Caption := 'end';
end else begin
Caption := 'not end';
end;
When does it
apply ?
Beginning of file:
1- when one tries to reach a row less than the
first row.
sample: mlb.GoFirst;
mlb.GoPrevious; {now BeginningOfFile is true
because we tryed to overpass the first row}
2- when the table is empty.
End of file:
1- when one tries to reach a row greater than
the last row.
sample: {the table
mytable is made of 4 rows}
mlb.Go(15); {we try to reach the 15th row
which does not exits, so BeginningOf File and EndOfFile are now true}
2- when the table is empty. |
To test if the
beginning of a table has been reached
use the BeginningOfFile property:
return myinstance->BeginningOfFile;
To
test if the end of a table has been reached
use the EndOfFile property:
return myinstance->EndOfFile;
|
| |
|
| Go functions (Go, GoFirst, GoNext, GoPrevious,
GoLast) are used to navigate into rows. GoFirst sets the current row to
the first row, GoNext to the next reachable row, GoPrevious to the
previous reachable row, GoLast to the last row. |
| DELPHI |
C++ |
To set the current
row as the first row
use the GoFirst API:
myinstance.GoFirst;
{GetCurrentRow returns now 1};
To set the
current row as the last row
use the GoLast API:
myinstance.GoLast;
{GetCurrentRow returns now RowCount};
To set the
current row as the next row
use the GoNext API:
myinstance.GoNext;
{goes to the next row}
To set the current row as the next row
use the GoPrevious API:
myinstance.GoPrevious;
{goes to the previous row}
To set the current row to any other
use the GoPrevious API:
myinstance.Go(8);
{GetCurrentRow returns now 8}
If case of success these functions return TRUE, else
they return FALSE.
GoNext and GoPrevious return False when they
have reached the End of the File or the Beginning of the file, so this
information can be used to stop a navigation.
Sample:
myinstance.GoFirst;
while not myinstance.GoNext do begin
end;
|
To set the current
row as the first row
use the GoFirst API:
myinstance->GoFirst();
To set the
current row as the last row
use the GoLast API:
myinstance->GoLast();
To set the
current row as the next row
use the GoNext API:
myinstance->GoNext();
To set the current row as the next row
use the GoPrevious API:
myinstance->GoPrevious();
To set the current row to any other
use the GoPrevious API:
myinstance->Go(1);
/* same as GoFirst */
If case of success
these functions return TRUE,
else they return FALSE.
GoNext and GoPrevious
return False when they have reached the End of the File or the
Beginning of the file, so this information can be used to stop a
navigation.
Sample:
myinstance->GoFirst();
while (!myinstance->GoNext());
|
| SavePosition, RestorePosition and GetPosition
are used to save, restore and get the position of the current row. This
can be used to recover a position after some navigations with the Go
functions. |
| DELPHI |
C++ |
To save and
restore a position
SavePosition and RestorePosition API:
myinstance.Go(11);
myinstance.SavePosition;
myinstance.Go(4);
Caption := IntToStr(myinstance.GetPosition);
{must print 4}
Caption := IntToStr(myinstance.GetCurrentRow);
{must print 11}
...
myinstance.RestorePosition;
Caption := IntToStr(myinstance.GetPosition);
{must print 11} |
To save and
restore a position
SavePosition and RestorePosition API:
myinstance->Go(11);
myinstance->SavePosition();
myinstance->Go(4);
printf("%d",myinstance->GetPosition());
printf("%d",myinstance->GetCurrentRow());
...
myinstance->RestorePosition();
printf("%d",myinstance->GetPosition());
{must print 11} |
| Seek and Match functions (BeginSeek, EndSeek,
SeekData, SeekFloat, MatchData, MatchFloat) are used to seek for a
particular type of data along records. |
| DELPHI |
C++ |
To seek for a
string data
SeekData function seeks for a string matching
a criteria along one fields' records.
To choose the direction to search (to the beginning or to the end), the
BeginSeek function must be used with the MLB_FORWARD constant as
parameter to search from the current position to the end of the table,
and MLB_BACKWARD to search from the current row to the first row.
SeekData returns true if the match has been completed, else it returns
false.
Samples:
1- You want to seek for a record of field city
equal to 'London':
{This code Seeks for rows having London as
city ...}
myinstance.GoFirst;
myinstance.BeginSeek(MLB_FORWARD);
while myinstance.SeekData('city', '=',
'London') do begin
end;
myinstance.EndSeek;
2- To seek for a
string from the end:
myinstance.GoLast;
myinstance.BeginSeek(MLB_BACKWARD);
while myinstance.SeekData('city', '=',
'London') do begin
end;
myinstance.EndSeek;
3- To seek for a
string like another string:
{searches for all city records beginning with L}
myinstance.GoFirst;
myinstance.BeginSeek(MLB_FORWARD);
while myinstance.SeekData('city', 'LIKE',
'L*') do begin
end;
myinstance.EndSeek;
{valid comparison operators for string
matching are '=', 'LIKE', '<', '>', '<=', '>='}
To
seek for a float data along a field
Floats (or integers) can be searched along a
field just like string datas except the LIKE operator is not valid for
float seeking.
{valid comparison operators for float matching
are '=', '<', '>', '<=', '>='}
Sample:
You want to seek for a percentage least or
equal to 80.0%:
myinstance.GoFirst;
myinstance.BeginSeek(MLB_FORWARD);
while myinstance.SeekFloat('percents',
'<=', 80.0) do begin
end;
myinstance.EndSeek;
To
check if a row matches a criteria
Now we are going to study
Match functions, which are the same as Seek functions, but that applies
only to the current row, and are not seeking for a criteria along rows.
Sample:
You want to go to the 5th row and to check if
this row's city matches London, and if this row's percentage if greater
than 71.5%:
var r: boolean;
myinstance.Go(5);
r := myinstance.MatchData('city', '=',
'London') and myinstance.MatchFloat('percents', '>', 71.5);
{r is true only if the record city of the 5th
row is London and the percents record of the same row is > 71.5%}
|
To seek for a
string data
Samples:
1- You want to seek for a record of field city
equal to 'London':
/*This code Seeks for rows having London as
city ...*/
myinstance->GoFirst();
myinstance->BeginSeek(MLB_FORWARD);
while (myinstance->SeekData("city", "=",
"London")) {
}
myinstance->EndSeek();
2- To seek for a
string from the end:
myinstance->GoLast();
myinstance->BeginSeek(MLB_BACKWARD);
while (myinstance->SeekData("city", "=",
'London')) {
}
myinstance->EndSeek();
3- To seek for a
string like another string:
/*searches for all city records beginning with
or containing L*/
myinstance->GoFirst();
myinstance->BeginSeek(MLB_FORWARD);
while (myinstance->SeekData("city", "LIKE",
"*L*")) {
}
myinstance->EndSeek();
/*The following
code searches for all records beginning with A, followed by any
character, and by a character in between x and z (x, y or z), for
sample AVx is a valid match*/
myinstance->GoFirst();
myinstance->BeginSeek(MLB_FORWARD);
while (myinstance->SeekData("field1",
"LIKE", "A?[x-z]")) {
/*insert here you action*/
}
myinstance->EndSeek();
/*valid comparison operators for string
matching are '=', 'LIKE', '<', '>', '<=', '>='*/
To
seek for a float data along a field
Floats (or integers) can be searched along a
field just like string datas except the LIKE operator is not valid for
float seeking.
/*valid comparison operators for float
matching are '=', '<', '>', '<=', '>='*/
Sample:
You want to seek for a percentage least or
equal to 80.0%:
myinstance->GoLast();
myinstance->BeginSeek(MLB_BACKWARD);
while (myinstance->SeekFloat("percents",
"<=", 80.0)) {
}
myinstance->EndSeek();
To
check if a row matches a criteria
Now we are going to study
Match functions, which are the same as Seek functions, but that applies
only to the current row, and are not seeking for a criteria along rows.
Sample:
You want to go to the 2nd row and to check if
this row's city matches cities beginning with Lond and ending with n or
N, and if this row's price if equal to 1500 dollars:
int r;
myinstance->GoFirst();
myinstance->GoNext();
r = myinstance->MatchData("city", "=",
"Lond*[n,N]") && myinstance->MatchFloat("price", "=", 1500);
/*r is true (1), if the matching is a success,
else r is false (0)*/
|
|