Yioop_V9.5_Source_Code_Documentation

PackedTableTools
in package

A collection of methods to encode and decode records according to a signature.

Tags
author

Chris Pollett

Table of Contents

ADD_FILE_HANDLE  = 1
Constant used to indicate that add() should be adding row using a file handle
ADD_FILE_PATH  = 2
Constant used to indicate that add() should be append row row a specified file (not having a file handle to it yet)
ADD_MEM_TABLE  = 0
Constant used to indicate that add() should be adding row to an in memory table
ADD_MEM_TABLE_STRING  = 3
Constant used to indicate that add() should be adding row to an in memory table where then in memory table is kept as an encoded string rasther than as an array of key => data pairs.
APPEND_MODE  = 1
Constant used to indicate that add() should cluster the value if there already a row in the table with the same primary key
AS_STRING_MODE  = 2
Constant used to indicate that loading shouldn't try to decode the serialized disk format
DEFAULT_COMPRESSOR  = \seekquarry\yioop\configs\NS_COMPRESSORS . "NonCompressor"
If not specified when constructing the instance, than this will be the seekquarry\yioop\library\compressor\Compressor used to compress rows.
DEFAULT_KEY_LEN  = 16
If not specified by the format then this will be the assumed fixed length of the primary key
REPLACE_MODE  = 0
Constant used to indicate that add() should replace the value if there already a row in the table with the same primary key
TYPE_SYNONYMS  = ["BOOLEAN" => "BOOL", "BOOL" => "BOOL", "CLOB" => "TEXT", "DOUBLE" => "DOUBLE", "FLOAT" => "REAL", "INT" => "INT", "INTEGER" => "INT", "REAL" => "REAL", "TEXT" => "TEXT"]
Array of synonyms for the different possible column name types.
$compressor  : Compressor
A string compression algorithm used to compress rows represented as strings
$format  : array<string|int, mixed>
This is the signature of the records this PackedTableTools will manipulate. This should be an associative array of element of one of the forms: "PRIMARY KEY" => column_name, "PRIMARY KEY" => [column_name, length_of_primary_key], column_name => column_type pairs column_type's are from among BOOL, TEXT, DOUBLE, REAL or their synonyms as given in PackedTableTools::TYPE_SYNONYMS. There should be only one primary key pair and if its value is not an array the key length is assumed to be PackedTableTools::DEFAULT_KEY_LEN.
$key_field  : string
Name of the column used for the primary key.
$key_len  : int
Fixed number of bytes used to store the primary key.
$num_bool_columns  : int
Number of columns in a record that are of type BOOL
$num_int_columns  : int
Number of columns in a record that are of type INT
$num_text_columns  : int
Number of columns in a record that are of type TEXT
$table_cache  : array<string|int, mixed>
$table_entry_markers  : array<string|int, mixed>
__construct()  : mixed
Used to create an instance of a PackedTableTools according to the $format for record columns and $compressor_type to be used for row compression.
add()  : bool
Adds ($key, $table_row) as an entry into $table using the adding and replace methods specified
count()  : int
Given a table_row, which might represent several items grouped because share a key, returns the total number of items stored in the row
countTableEntries()  : int
Determines the number of items stored in the packed table stored as a file
delete()  : bool
Removes $key and any records associated with it from $table
find()  : array<string|int, mixed>
Return any records in $table associated with $key
findEntryAtIndexTableName()  : string|null
Returns the $index'th entry out of a string packed according to the current PackedTableTool.
findRowFromKeyTableString()  : string|null
Looks up the data associated with a key in a string formatted as series of rows of the given PackedTableTool type.
getEntryMarkers()  : array<string|int, mixed>
Determines the end of record marker positions for a packed table stored as a file
load()  : array<string|int, mixed>
Reads in the file $table_path and unpacks it according to this PackedTableTool's signature. Repeated values for a key are handled according to $mode.
mergeRowValues()  : string
Merges two rows of items packed according to this packed table tools into a single row of items.
pack()  : string
Packs as a string an array of records. Here each records should be an associative array of field items, with field names and types according to this packed table tools signature. The format of the packed records string is: output of bool columns as bit string in order of columns as appear in signature, bit data on sizes to use for each int column (for each column two bit code 00 - 1byte, 01 - 2byte, 10 - 4byte, 11 - 8byte), text column length (1byte/column saying how long the data stored in that column is), This is followed by the actual column data (except bool columns) in the order it is listed in the signature. Int's use their high order bit as a sign bit and are stored using the number of bytes give by their code in the int column bit data. Real/doubles are stored as 8byte doubles.
save()  : bool
Saves an associative array of key => packed_records to a file $table_path on disk. Here the packed_records should be packed according to this PackedTableTools signature. Each key value pair is concatenated if variable length keys are used by this packed table tool then the length of the key is stored as a char before the key. Records are then encoded by replacing \xFE => \xFE\xFD and \xFF => \xFE\xFE. The records are then concatenated separated by \xFF, and the result compressed using the PackedTableTool's compressor.
unpack()  : array<string|int, mixed>
Given a table_row, which might represent several items grouped because they share a key, unpacks and returns the $offset through $limit numbered items

Constants

ADD_FILE_HANDLE

Constant used to indicate that add() should be adding row using a file handle

public mixed ADD_FILE_HANDLE = 1

ADD_FILE_PATH

Constant used to indicate that add() should be append row row a specified file (not having a file handle to it yet)

public mixed ADD_FILE_PATH = 2

ADD_MEM_TABLE

Constant used to indicate that add() should be adding row to an in memory table

public mixed ADD_MEM_TABLE = 0

ADD_MEM_TABLE_STRING

Constant used to indicate that add() should be adding row to an in memory table where then in memory table is kept as an encoded string rasther than as an array of key => data pairs.

public mixed ADD_MEM_TABLE_STRING = 3

APPEND_MODE

Constant used to indicate that add() should cluster the value if there already a row in the table with the same primary key

public mixed APPEND_MODE = 1

AS_STRING_MODE

Constant used to indicate that loading shouldn't try to decode the serialized disk format

public mixed AS_STRING_MODE = 2

DEFAULT_COMPRESSOR

If not specified when constructing the instance, than this will be the seekquarry\yioop\library\compressor\Compressor used to compress rows.

public mixed DEFAULT_COMPRESSOR = \seekquarry\yioop\configs\NS_COMPRESSORS . "NonCompressor"

DEFAULT_KEY_LEN

If not specified by the format then this will be the assumed fixed length of the primary key

public mixed DEFAULT_KEY_LEN = 16

REPLACE_MODE

Constant used to indicate that add() should replace the value if there already a row in the table with the same primary key

public mixed REPLACE_MODE = 0

TYPE_SYNONYMS

Array of synonyms for the different possible column name types.

public mixed TYPE_SYNONYMS = ["BOOLEAN" => "BOOL", "BOOL" => "BOOL", "CLOB" => "TEXT", "DOUBLE" => "DOUBLE", "FLOAT" => "REAL", "INT" => "INT", "INTEGER" => "INT", "REAL" => "REAL", "TEXT" => "TEXT"]

Properties

$compressor

A string compression algorithm used to compress rows represented as strings

public Compressor $compressor

$format

This is the signature of the records this PackedTableTools will manipulate. This should be an associative array of element of one of the forms: "PRIMARY KEY" => column_name, "PRIMARY KEY" => [column_name, length_of_primary_key], column_name => column_type pairs column_type's are from among BOOL, TEXT, DOUBLE, REAL or their synonyms as given in PackedTableTools::TYPE_SYNONYMS. There should be only one primary key pair and if its value is not an array the key length is assumed to be PackedTableTools::DEFAULT_KEY_LEN.

public array<string|int, mixed> $format

$key_field

Name of the column used for the primary key.

public string $key_field

$key_len

Fixed number of bytes used to store the primary key.

public int $key_len

$num_bool_columns

Number of columns in a record that are of type BOOL

public int $num_bool_columns

$num_int_columns

Number of columns in a record that are of type INT

public int $num_int_columns

$num_text_columns

Number of columns in a record that are of type TEXT

public int $num_text_columns

$table_entry_markers

public array<string|int, mixed> $table_entry_markers

Methods

__construct()

Used to create an instance of a PackedTableTools according to the $format for record columns and $compressor_type to be used for row compression.

public __construct(mixed $format[, mixed $compressor_type = self::DEFAULT_COMPRESSOR ]) : mixed
Parameters
$format : mixed
$compressor_type : mixed = self::DEFAULT_COMPRESSOR
Return values
mixed —

add()

Adds ($key, $table_row) as an entry into $table using the adding and replace methods specified

public add(mixed &$table, string $key, string $table_row[, int $add_method = self::ADD_MEM_TABLE ][, int $mode = self::REPLACE_MODE ]) : bool
Parameters
$table : mixed

either an associative array of key =>value pairs where the keys are strings of length matching this PackedTableTools sginature and the values have been packed according to this signature, or the file name of a file containing a serialized version of such a table, or a file handle to the end of such a file

$key : string

a key string of length given by the signature of this PackedTableTools

$table_row : string

a record packed according tot the signature of this PackedTableTools

$add_method : int = self::ADD_MEM_TABLE

one of self::ADD_MEM_TABLE, self::ADD_FILE_HANDLE, self::ADD_FILE_PATH indicating which of the three possibilities for $table we have

$mode : int = self::REPLACE_MODE

either self::APPEND_MODE or self::REPLACE_MODE If the former the table_row data will be appended to any data currently associated with the key, if the latter it will replace such data

Return values
bool —

whether or not adding was successful

count()

Given a table_row, which might represent several items grouped because share a key, returns the total number of items stored in the row

public count(string $table_row) : int
Parameters
$table_row : string

sequence of items packed according to this PackedTableTools signature

Return values
int —

number of items sctored in the table row

countTableEntries()

Determines the number of items stored in the packed table stored as a file

public countTableEntries(string $table_name) : int
Parameters
$table_name : string

name of file with packed data

Return values
int —

number of entries in table

delete()

Removes $key and any records associated with it from $table

public delete(array<string|int, mixed> &$table, string $key) : bool
Parameters
$table : array<string|int, mixed>

array of key => records pairs where the key is a string of length given by this PackedTableTool's signature and the records are packed according this PackedTableTool's signature

$key : string

to remove records for

Return values
bool —

success or failure of removal

find()

Return any records in $table associated with $key

public find(array<string|int, mixed> $table, string $key) : array<string|int, mixed>
Parameters
$table : array<string|int, mixed>

array of key => records pairs where the key is a string of length given by this PackedTableTool's signature and the records are packed according this PackedTableTool's signature

$key : string

to return records for

Return values
array<string|int, mixed> —

of records that have been packed according to this PackedTableTool's signature

findEntryAtIndexTableName()

Returns the $index'th entry out of a string packed according to the current PackedTableTool.

public findEntryAtIndexTableName(mixed $table_name, int $index) : string|null
Parameters
$table_name : mixed
$index : int

the entry to find

Return values
string|null —

the $index'th key value entry if it exists null otherwise

findRowFromKeyTableString()

Looks up the data associated with a key in a string formatted as series of rows of the given PackedTableTool type.

public findRowFromKeyTableString(string $table_string, string $key, int $offset) : string|null
Parameters
$table_string : string

table as a string of this PackedTableTool type

$key : string

key field of this PackedTableTool type

$offset : int

byte offset to start search from

Return values
string|null —

just the value portion of the key value entry associated with the given key if it exists null otherwise

getEntryMarkers()

Determines the end of record marker positions for a packed table stored as a file

public getEntryMarkers(string $table_name) : array<string|int, mixed>
Parameters
$table_name : string

name of file with packed data

Return values
array<string|int, mixed> —

of integer record marker locations

load()

Reads in the file $table_path and unpacks it according to this PackedTableTool's signature. Repeated values for a key are handled according to $mode.

public load(string $table_path[, int $mode = self::REPLACE_MODE ][, bool $cache_table = false ]) : array<string|int, mixed>
Parameters
$table_path : string

path to file containing PackedTableTool's records

$mode : int = self::REPLACE_MODE

one of self::REPLACE_MODE (replace previous value), self::APPEND_MODE (make an array of all values with same key), self::AS_STRING_MODE read in string of file but don't decode

$cache_table : bool = false

whether to cache the file string of the loaded table

Return values
array<string|int, mixed> —

of key => packed_records pairs

mergeRowValues()

Merges two rows of items packed according to this packed table tools into a single row of items.

public mergeRowValues(string $row_values1, string $row_values2) : string
Parameters
$row_values1 : string

a row (less key) packed according according to this packed tabled tools

$row_values2 : string

a second row (less key) packed according according to this packed tabled tools

Return values
string —

a merged row consisting of the items in the first row followed by those in the second.

pack()

Packs as a string an array of records. Here each records should be an associative array of field items, with field names and types according to this packed table tools signature. The format of the packed records string is: output of bool columns as bit string in order of columns as appear in signature, bit data on sizes to use for each int column (for each column two bit code 00 - 1byte, 01 - 2byte, 10 - 4byte, 11 - 8byte), text column length (1byte/column saying how long the data stored in that column is), This is followed by the actual column data (except bool columns) in the order it is listed in the signature. Int's use their high order bit as a sign bit and are stored using the number of bytes give by their code in the int column bit data. Real/doubles are stored as 8byte doubles.

public pack(array<string|int, mixed> $items) : string
Parameters
$items : array<string|int, mixed>

array of records to pack

Return values
string —

records packed into the string format used by PackedTableTools

save()

Saves an associative array of key => packed_records to a file $table_path on disk. Here the packed_records should be packed according to this PackedTableTools signature. Each key value pair is concatenated if variable length keys are used by this packed table tool then the length of the key is stored as a char before the key. Records are then encoded by replacing \xFE => \xFE\xFD and \xFF => \xFE\xFE. The records are then concatenated separated by \xFF, and the result compressed using the PackedTableTool's compressor.

public save(string $table_path, mixed $table) : bool
Parameters
$table_path : string

filename to save to

$table : mixed
Return values
bool —

success or not

unpack()

Given a table_row, which might represent several items grouped because they share a key, unpacks and returns the $offset through $limit numbered items

public unpack(string $table_row, int $offset[, int $limit = -1 ]) : array<string|int, mixed>
Parameters
$table_row : string

sequence of items packed according to this PackedTableTools signature

$offset : int

index of item to begin with

$limit : int = -1

maximum number of items to return starting at offset

Return values
array<string|int, mixed> —

unplacked items


        

        
    




    

    

                

    

        

            
Search results