filter_read_exact#

Pull exactly $size bytes from the filter chain into $_, looping over short reads until the request is satisfied or the stream ends.

Synopsis#

my $status = filter_read_exact($size);

What you get back#

An integer status using the same convention as filter_read:

> 0 - a full $size-byte block was read into $_.
= 0 - EOF reached with no pending data, or EOF reached with a partial block (the partial block is still in $_, and the status returned to the caller is 1 in that specific case to signal “there is data to process”). See the note below.
< 0 - a read error occurred.

filter_read_exact keeps calling filter_read internally until it has accumulated $size bytes or the chain reports EOF / error. It is the right choice for filters that operate on fixed-size frames (for example, a binary decoder).

Examples#

Read 16-byte records until end of file:

sub filter {
    my $status = filter_read_exact(16);
    decode_record($_) if $status > 0;
    $status;
}

Edge cases#

$size must be strictly positive. Calling filter_read_exact(0) or with a negative argument croaks with "filter_read_exact: size parameter must be > 0".
On EOF with a partially-filled $_, the returned status is 1, not 0 - this lets the filter process the tail of the stream before the next call reports true EOF.

Differences from upstream#

Fully compatible with upstream Filter::Util::Call 1.65.