metatable

API

Constants

`READONLY`

Passed to open() to open table readonly. Only get() is allowed.

$table = metatable::open('foo', metatable::READONLY);

`READWRITE`

Passed to open() to open table in readwrite mode. All operations can be peformed.

$table = metatable::open('foo', metatable::READWRITE);

`STRINGS_GC`

Passed to open() to perform strings garbage collection, when table is close()ed.

Garbage collection can very slow down closing process. It is turned on by default, but it is wise to disable it and garbage collect strings only, for example, each 30 opens, each 1 day etc.

$table = metatable::open('foo', metatable::STRINGS_GC);

`AUTOCLOSE`

Passed to open().

Table is automatically closed (if opened in readwrite mode, data are saved).

Discouraged to use.

$table = metatable::open('foo', metatable::AUTOCLOSE);

Static methods

`metatable open(string $filename, int $flags)`

$filename: filename of metatable. If does not exist and metatatable opened in readwrite mode, file is created on close()ing.
$flags: or-ed combination of flag constants. For example, when I want metatable opened in readwrite mode, to have strings garbage collected and autoclosing instance:
```
$table = metatable::open('foo', metatable::READWRITE | metatable::STRINGS_GC | metatable::AUTOCLOSE);
```

Returns: newly create instance of metatable or FALSE on failure.

metatables have to be opened with open(). Other way are not possible.

IMPORTANT: do not ever open more instances of same file – dead-lock.

Instance methods

`array get(string $row, string $col)`

$row: row name. Wildcard * can be used.
$col: column name. Wilcard * can be used.

Returns: array of found values. Each key is row name and value array of matched columns.

get() is probably the most powerful method that metatable has (because metatable is mostly-read storage).

If you want to read single value:

$table->get('foo', 'bar');

For reading one row:

$table->get('foo', '*');

Rows that has some column:

$rows = array_keys($table->get('*', 'bar'));

Selected rows has to be read manually (maybe instance for feature request?).

And whole table:

$table->('*', '*');

`bool set(string $row, string $col, mixed $value)`

$row: row name.
$col: column name.
$value: value to be set. Currently supported types are: string, integer, boolean. Other types may be set in their serialized form as string.

Returns: TRUE if everything went OK, FALSE elsewhere.

Setting NULL means deleting (row, col) pair.

`bool index(string $start)`

$start: row name or first letters of row name.

Returns: TRUE if index was created, FALSE elsewhere.

Indexes are useful only on big table. They do not provide much speed up with small ones. They even can slow down small tables on insertion, because all indexes have to be recomputed on insertion.

`void unindex(string $start)`

$start: index name

After calling this method, index with given name does not exists anymore.

`bool close(void)`

Returns: TRUE if successfully closed, FALSE elsewhere.

If metatable opened in readwrite mode, data are saved.