php-output.md

#Yothalot\Output

Yothalot\Output is a utility class that helps you to create files in the same format as Yothalot uses internally. In general you do not need to create a file like this since Yothalot can handle all types of files (with a little bit of your help). However, the Yothalot format has the cool property of being compressed while still being splittable. Therefore you may want to use this format for your own files as well.

There are five methods available for this class:

class Yothalot\Output
{
    public function __construct($filename);
    public function add($identifier, $fields);
    public function name();
    public function size();
    public function flush($recompress = false);
}

Constructor

The constructor takes one parameter, the file name. A file with this file name will be created if it does not exist. Otherwise the file will be opened.

/**
 * Create or open an output file
 */
$output = new Yothalot\Output("/path/to/file.yot");

where "/path/to/file.yot" is the path to the file you want to write to.

Member add()

add() is a member function that adds a record to the output file. A record exists of an identifier and fields. The identifier has to be numeric. The field can be an array of basic types.

/**
 * Add a record with key and value to output file
 */
$output->add(1, array('1', '2', '3'));

where: 1 is in this case the identifier and array('1', '2', '3') are the fields.

Member name()

name() returns the full name of the output file.

/**
 * Get the name of the output file
 */
echo($output->name());

##Member size() Yothalot\Output::size() returns the size (in bytes) of the output file. You may use it e.g. to determine if the file has become to large, so you can close it and create a new output file. However, note that the Yothalot formated files are splittable.

/**
 * Retrieve the size of the output file
 */
echo($output->size());

##Member flush() Yothalot\Output::flush() flushes the object to the file. In general you do not need this, only if your code can crash you may use it to be sure that your data is stored. Although it is better to fix the code.

This method accepts an optional (boolean) parameter, controlling whether to completely recompress the data in the output file. This is only useful in case you have done manual flushes earlier since many small flushes can reduce the effectiveness of the compression (and even make the compressed file bigger than the uncompressed version).

Recompressing the file is an intensive operation, both in terms of CPU as in terms of I/O (the whole file is rewritten!). Use it sparingly!

/**
 * flush the data to the output file
 *
 *  Not recompressing is the default, so it's not strictly necessary
 *  to provide the parameter in this case, it is only done for clarity
 */
$output->flush(false);