Page MenuHomePhabricator

abstract class LinesOfALarge
libphutil Technical Documentation (Filesystem)

Abstraction for processing large inputs without holding them in memory. This class implements line-oriented, buffered reads of some external stream, where a "line" is characterized by some delimiter character. This provides a straightforward interface for most large-input tasks, with relatively good performance.

If your stream is not large, it is generally more efficient (and certainly simpler) to read the entire stream first and then process it (e.g., with explode()).

This class is abstract. The concrete implementations available are:

For example:

foreach (new LinesOfALargeFile('/path/to/file.log') as $line) {
  // ...
}

By default, a line is delimited by "\n". The delimiting character is not returned. You can change the character with setDelimiter(). The last part of the file is returned as the last $line, even if it does not include a terminating character (if it does, the terminating character is stripped).

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

final public function current()

This method is not documented.
Return
wild

final public function key()

This method is not documented.
Return
wild

final public function next()

This method is not documented.
Return
wild

final public function rewind()

This method is not documented.
Return
wild

final public function valid()

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

final public function setDelimiter($character)

Change the "line" delimiter character, which defaults to "\n". This is used to determine where each line ends.

If you pass null, data will be read from source as it becomes available, without looking for delimiters. You can use this to stream a large file or the output of a command which returns a large amount of data.

Parameters
string|null$characterA one-byte delimiter character.
Return
this

abstract protected function willRewind()

Hook, called before rewind()(). Allows a concrete implementation to open resources or reset state.

Return
void

abstract protected function readMore()

Called when the iterator needs more data. The subclass should return more data, or empty string to indicate end-of-stream.

Return
stringData, or empty string for end-of-stream.