Functions
Abstract: Constructor
protected
function FFDB()
Abstract: Adds an entry to the database
protected
function add(&$record)
Parameters
| Name | Description |
|---|
| record | array - record to add to the database |
Result: bool - true on success, false on failure
Abstract: Adds a field to the database. Note that this is a fairly
expensive operation as the database has to be rebuilt.
WARNING: Do not call this method unless you are sure that no other
people are using the database at the same time. This will cause their
PHP scripts to fail. FFDB does not check to see if the database schema
has been changed while in use (too much overhead).
protected
function addfield($name, $type, $default, $iskey = false)
Parameters
| Name | Description |
|---|
| name | name of the new field -- must not already exist |
| type | type of the new field (FFDB_INT, FFDB_INT_AUTOINC,
FFDB_STRING, FFDB_ARRAY, FFDB_FLOAT, FFDB_BOOL) |
| default | default value for new field in all entries |
| iskey | true if the new field is to become the new primary key,
false otherwise. Not that this can only be TRUE if the database
is empty, otherwise we will have multiple records with the same (default)
key, which would make the database invalid. The primary key cannot be
an array or boolean type. |
Result: bool - true on success, false on failure
Abstract: Configures autoclean. When an edit or delete is made, the
record is normally not removed from the data file - only the index.
After repeated edits/deletions, the data file may become very big with
dirty (non-removed) records. A cleanup is normally done with the
cleanup() method. Autoclean will do this automatically, keeping the
number of dirty records to under the $threshold value.
To turn off autoclean, set $threshold to a negative value.
protected
function autoclean($threshold = -1)
Parameters
| Name | Description |
|---|
| threshold | - number of dirty records to have at any one time. |
Abstract: private function to clean up the database if the number of
dirty records have exceeded a threshold value.
protected
function automatic_cleanup()
Abstract: Converts a binary string to an int, low byte first
protected
function bin2dec(&$str, $len)
Parameters
| Name | Description |
|---|
| str | string - binary string to convert |
| len | int - length of the binary string to convert |
Result: the int version of the binary string
Abstract: Converts a 6 byte binary string to a single-precision
floating point number
protected
function bin2float(&$data)
Parameters
| Name | Description |
|---|
| data | string - the binary string to convert |
Result: the floating point number
Abstract: Private function to perform a binary search
protected
function bsearch(&$index, $left, $right, &$target)
Parameters
| Name | Description |
|---|
| index | file offsets into the .dat file, it must be ordered
by primary key. |
| left | the left most index to start searching from |
| right | the right most index to start searching from |
| target | the search target we're looking for |
Result: Returns -[insert pos+1] when not found, or the array index+1
when found. Note that we don't return the normal position, because we
can't differentiate between -0 and +0.
Abstract: Cleans up the database by removing deleted entries
from the flat file.
protected
function cleanup()
Result: true if successful, false otherwise
Abstract: Closes the currently opened database
protected
function close()
Abstract: Creates a new database
protected
function create($dbname, $schema)
Parameters
| Name | Description |
|---|
| dbname | string - name of the database |
| schema | array - name<->type array of fields for table.
Note that the key cannot be an array or boolean type field.
The key is given by a third attribute - a string "key". |
Result: bool - true if successful, false on failure
Abstract: Return the current record in the database. Note that the
current iterator pointer is not moved in any way.
protected
function current()
Result: the current database record, or false if there are no
more items left.
Abstract: Convers an int to a binary string, low byte first
protected
function dec2bin($num, $bytes)
Parameters
| Name | Description |
|---|
| num | int - number to convert |
| bytes | int - minimum number of bytes to covert to |
Result: the binary string form of the number
Abstract: Closes the current database then deletes it.
protected
function drop()
Result: bool - true on success
Abstract: Replaces an existing record with the same primary
key as the new record.
protected
function edit(&$record, $record_num = -1)
Parameters
| Name | Description |
|---|
| record | record that will replace an existing one |
| record_num | record number to replace: ONLY for databases without
a primary key. Ignored for databases WITH a primary key. |
Result: bool - true on success, false on failure
Abstract: Searches the database for an item, and returns true
if found, false otherwise.
protected
function exists($key)
Parameters
| Name | Description |
|---|
| key | primary key of record to search for, or the record
number (zero based) for databases without a primary key. |
Result: true if found, false otherwise
Abstract: Converts a single-precision floating point number
to a 6 byte binary string.
protected
function float2bin($num)
Parameters
| Name | Description |
|---|
| num | float - the float to convert |
Result: the binary string representing the float
Abstract: retrieves all records in the database, each record in an array
element.
protected
function getall($orderby = NULL, $includeindex = false)
Parameters
| Name | Description |
|---|
| orderby | order the results. Set to the field name to order by
(as a string). If left unset, sorting is not done and it is a lot faster.
If prefixed by "!", results will be ordered in reverse order.
If orderby is an array, the 1st element refers to the field to order by,
and the 2nd, a function that will take two take two parameters A and B
- two fields from two records - used to do the ordering. It is expected
that the function would return -ve if A < B and +ve if A > B, or zero
if A == B (to order in ascending order). |
| includeindex | if true, an extra field called 'FFDB_IFIELD' will
be added to each record returned. It will contain an int that specifies
the original position in the database (zero based) that the record is
positioned. It might be useful when an orderby is used, and an future
operation on a record is required, given it's index in the table. |
Result: all database records as an array
Abstract: retrieves records in the database whose field matches the
given regular expression.
protected
function getbyfield( $fieldname, $regex, $orderby = NULL, $includeindex = false)
Parameters
| Name | Description |
|---|
| fieldname | the field which to do matching on |
| regex | the regular expression to match a field on.
Note: you should include the delimiters ("/php/i" for example). |
| orderby | order the results. Set to the field name to order by
(as a string). If left unset, sorting is not done and it is a lot faster.
If prefixed by "!", results will be ordered in reverse order.
If orderby is an array, the 1st element refers to the field to order by,
and the 2nd, a function that will take two take two parameters A and B
- two fields from two records - used to do the ordering. It is expected
that the function would return -ve if A < B and +ve if A > B, or zero
if A == B (to order in ascending order). |
| includeindex | if true, an extra field called 'FFDB_IFIELD' will
be added to each record returned. It will contain an int that specifies
the original position in the database (zero based) that the record is
positioned. It might be useful when an orderby is used, and an future
operation on a record is required, given it's index in the table. |
Result: matching records in an array, or false on failure
Abstract: retrieves all records in the database, passing each record
into a given function. If that function returns true, then it is added
to the result (array) list.
protected
function getbyfunction($selectfn, $orderby = NULL, $includeindex = false)
Parameters
| Name | Description |
|---|
| selectfn | the function that accepts one argument (an array record),
and returns true or false. |
| orderby | order the results. Set to the field name to order by
(as a string). If left unset, sorting is not done and it is a lot faster.
If prefixed by "!", results will be ordered in reverse order.
If orderby is an array, the 1st element refers to the field to order by,
and the 2nd, a function that will take two take two parameters A and B
- two fields from two records - used to do the ordering. It is expected
that the function would return -ve if A < B and +ve if A > B, or zero
if A == B (to order in ascending order). |
| includeindex | if true, an extra field called 'FFDB_IFIELD' will
be added to each record returned. It will contain an int that specifies
the original position in the database (zero based) that the record is
positioned. It might be useful when an orderby is used, and an future
operation on a record is required, given it's index in the table. |
Result: all database records as an array
Abstract: retrieves a record based on the record number in the table
(zero based)
protected
function getbyindex($record_num)
Parameters
| Name | Description |
|---|
| record_num | zero based record number to retrieve |
Result: record if found, or false otherwise
Abstract: retrieves a record based on the specified key
protected
function getbykey($key, $includeindex = false)
Parameters
| Name | Description |
|---|
| key | primary key used to identify record to retrieve. For
databases without primary keys, it is the record number (zero based) in
the table. |
| includeindex | if true, an extra field called 'FFDB_IFIELD' will
be added to each record returned. It will contain an int that specifies
the original position in the database (zero based) that the record is
positioned. It might be useful when an orderby is used, and an future
operation on a record is required, given it's index in the table. |
Result: record if found, or false otherwise
Abstract: retrieves all keys in the database, each in an array.
protected
function getkeys()
Result: all database record keys as an array, in order, or false
if the database does not use keys.
Abstract: Returns the size of an item
protected
function item_size($type, &$data)
Parameters
| Name | Description |
|---|
| type | data type |
| data | actual data to size |
Result: int - size in bytes
Abstract: Tests to see if a key exists in a given array. This function
is defined to maintain some compatibility between various versions of PHP
protected
function key_exists_array(&$key, &$array)
Parameters
| Name | Description |
|---|
| key | - the key to search for |
| array | - the array in which to search |
Result: bool - true if the key exists; false otherwise
Abstract: lock the database for a read
protected
function lock_read($force = false)
Parameters
| Name | Description |
|---|
| force | force the lock to stick until unlocked by force |
Abstract: lock the database for a write
protected
function lock_write($force = false)
Parameters
| Name | Description |
|---|
| force | force the lock to stick until unlocked by force |
Abstract: Move the current iterator pointer to the next database item.
protected
function next()
Result: bool - true if advanced to a new item, false if there are
none left.
Abstract: Opens the given database
protected
function open($dbname)
Parameters
| Name | Description |
|---|
| dbname | string - The name of the database to open |
Result: bool - true if successful, false if failed
Abstract: private function to sort a result set by a particular field.
protected
function order_by(&$result, $orderby)
Parameters
| Name | Description |
|---|
| result | the result list to order |
| orderby | order the results. Set to the field name to order by
(as a string). If left unset, sorting is not done and it is a lot faster.
If prefixed by "!", results will be ordered in reverse order.
If orderby is an array, the 1st element refers to the field to order by,
and the 2nd, a function that will take two take two parameters A and B
- two fields from two records - used to do the ordering. It is expected
that the function would return -ve if A < B and +ve if A > B, or zero
if A == B (to order in ascending order). |
Result: array - input results ordered as required, or false on error.
Abstract: Reads a byte from a file
protected
function read_byte(&$fp)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
Result: the read byte as an int
Abstract: Reads a float (6 bytes) from a file
protected
function read_float(&$fp)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
Result: the read float
Abstract: private function to return the index values. We assume the
database has been locked before calling this function.
protected
function read_index()
Result: array - list of file offsets into the .dat file
Abstract: Reads an int (4 bytes) from a file
protected
function read_int(&$fp)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
Result: the read int
Abstract: Reads a data type from a file. Note that arrays can only
consist of other arrays, ints, and strings.
protected
function read_item(&$fp, $type)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to data file |
| type | data type to read |
Result: bool - data on success, false on failure
Abstract: Private function to read a record from the database
protected
function read_record(&$fp, $offset)
Parameters
| Name | Description |
|---|
| fp | the file pointer used to read a record from |
| offset | file offset into the .dat file |
Result: Returns false on error, or the record otherwise
Abstract: Private function to read a record KEY from the database. Note
that this function relies on the fact that they key is ALWAYS the first
item in the database record as stored on disk.
protected
function read_record_key(&$fp, $offset)
Parameters
| Name | Description |
|---|
| fp | the file pointer used to read a record from |
| offset | file offset into the .dat file |
Result: Returns false on error, or the key otherwise
Abstract: private function to read the database schema and other meta
information. We assume the database has been locked before calling
this function.
protected
function read_schema()
Abstract: Reads a string from a file
protected
function read_str(&$fp)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
Result: the read string
Abstract: Private function to determine the size (bytes) of a record
protected
function record_size(&$record)
Parameters
| Name | Description |
|---|
| record | the record to investigate |
Result: int - the size of the record.
Abstract: Removes entries from the database INDEX only, based on the
result of a regular expression match on a given field - records appear
deleted, but the actual data is only removed from the file when a
cleanup() is called.
protected
function removebyfield($fieldname, $regex)
Parameters
| Name | Description |
|---|
| fieldname | the field which to do matching on |
| regex | the regular expression to match a field on.
Note: you should include the delimiters ("/php/i" for example). |
Result: int - number of records removed (or bool/false on failure).
Abstract: Removes entries from the database INDEX only, based on the
result of a user-specified function - records appear deleted, but the
actual data is only removed from the file when a cleanup() is called.
protected
function removebyfunction($selectfn)
Parameters
| Name | Description |
|---|
| selectfn | the function that accepts one argument (an array record),
and returns true or false. |
Result: int - number of records removed (or bool/false on failure).
Abstract: Removes an entry from the database INDEX only - it appears
deleted, but the actual data is only removed from the file when a
cleanup() is called.
protected
function removebyindex($record_num)
Parameters
| Name | Description |
|---|
| record_num | The record number (zero based) in the table to remove. |
Result: bool - true on success, false on failure
Abstract: Removes an entry from the database INDEX only - it appears
deleted, but the actual data is only removed from the file when a
cleanup() is called.
protected
function removebykey($key)
Parameters
| Name | Description |
|---|
| key | primary key used to identify record to remove. For
databases without primary keys, it is the record number (zero based) in
the table. |
Result: bool - true on success, false on failure
Abstract: Removes a field from the database. Note that this is a fairly
expensive operation as the database has to be rebuilt.
WARNING: Do not call this method unless you are sure that no other
people are using the database at the same time. This will cause their
PHP scripts to fail. FFDB does not check to see if the database schema
has been changed while in use (too much overhead).
protected
function removefield($fieldname)
Parameters
| Name | Description |
|---|
| fieldname | name of the field to delete -- must currently exist |
Result: bool - true on success, false on failure
Abstract: Reset the internal pointer used for iterating over records
protected
function reset()
Abstract: Returns the current database schema in the same form
as that used in the parameter for the create(...) method.
protected
function schema()
Result: array - the database schema in the format used for the
create(...) method, or false if failure.
Abstract: Returns the number of records in the database
protected
function size()
Result: int - the number of records in the database
Abstract: Returns the number of dirty records in the database,
that would be removed if cleanup() is called.
protected
function sizedirty()
Result: int - the number of dirty records in the database
Abstract: unlock the database
protected
function unlock($force = false)
Parameters
| Name | Description |
|---|
| force | unlock a previously forced (sticky) lock |
Abstract: Writes a byte to a file
protected
function write_byte(&$fp, $num)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
| num | int - the byte to write |
Abstract: Writes a float (6 bytes) to a file
protected
function write_float(&$fp, $num)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
| num | float - the float to write |
Abstract: private function to write the index values. We assume the
database has been locked before calling this function.
protected
function write_index(&$index)
Parameters
| Name | Description |
|---|
| index | the index *data* to write out |
Abstract: Writes an int (4 bytes) to a file
protected
function write_int(&$fp, $num)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
| num | int - the int to write |
Abstract: Writes out a data type to a file. Note that arrays can only
consist of other arrays, ints, and strings.
protected
function write_item(&$fp, $type, &$data)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to data file |
| type | data type to write |
| data | actual data to write |
Result: bool - true on success, false on failure
Abstract: Private function to write a record to the END of the .dat file
protected
function write_record(&$fp, &$record, $size = -1)
Parameters
| Name | Description |
|---|
| fp | the file pointer used to write a record to |
| record | the record to write |
| size | the size of the record. |
| atoffset | the offset to write to, or -1 for the current position |
Result: Returns false on error, true otherwise
Abstract: private function to write the database schema and other meta
information. We assume the database has been locked before calling
this function.
protected
function write_schema()
Abstract: Writes a string to a file
protected
function write_str(&$fp, &$str)
Parameters
| Name | Description |
|---|
| fp | file pointer - pointer to an open file |
| str | string - the string to write |
© 2002 John Papandriopoulos. — (Last Updated 3/12/2002)