#------------------------------------------------------------------------------
# File:         RandomAccess.pod -- Documentation for File::RandomAccess
#
# Description:  Buffer to support random access reading of sequential file
#
# Legal:        Copyright (c) 2004-2006 Phil Harvey (phil at owl.phy.queensu.ca)
#               This library is free software; you can redistribute it and/or
#               modify it under the same terms as Perl itself.
#------------------------------------------------------------------------------

=head1 NAME

File::RandomAccess - Random access reads of sequential file or scalar

=head1 SYNOPSIS

    use File::RandomAccess;

    $raf = new File::RandomAccess(\*FILE, $disableSeekTest);

    $raf = new File::RandomAccess(\$data);

    $err = $raf->Seek($pos);
    $num = $raf->Read($buff, $bytes);

=head1 DESCRIPTION

Allows random access to sequential file by buffering the file if necessary.
Also allows access to data in memory to be accessed as if it were a file.

=head1 METHODS

=over 4

=item B<new>

Creates a new RandomAccess object given a file reference or
reference to data in memory.

    # Read from open file or pipe
    $raf = new File::RandomAccess(\*FILE);

    # Read from data in memory
    $raf = new File::RandomAccess(\$data);

=over 4

=item Inputs:

0) Reference to RandomAccess object.

1) File reference or scalar reference.

2) flag set if file is already random access (disables automatic SeekTest).

=item Returns:

Reference to RandomAccess object.

=back

=item B<SeekTest>

Performs test seek() on file to determine if buffering is necessary.  If
the seek() fails, then the file is buffered to allow random access.
B<SeekTest>() is automatically called from B<new> unless specified.

    $result = $raf->SeekTest();

=over 4

=item Inputs:

0) Reference to RandomAccess object.

=item Returns:

1 if seek test passed (ie. no buffering required).

=item Notes:

Must be called before any other i/o.

=back

=item B<Tell>

Get current position in file

    $pos = $raf->Tell();

=over 4

=item Inputs:

0) Reference to RandomAccess object.

=item Returns:

Current position in file

=back

=item B<Seek>

Seek to specified position in file.  When buffered, this doesn't quite
behave like seek() since it returns success even if you seek outside the
limits of the file.

    $success = $raf->Seek($pos, 0);

=over 4

=item Inputs:

0) Reference to RandomAccess object.

1) Position.

2) Whence (0=from start, 1=from cur pos, 2=from end).

=item Returns:

1 on success, 0 otherwise

=back

=item B<Read>

Read data from the file.

    $num = $raf->Read($buff, 1024);

=over 4

=item Inputs:

0) Reference to RandomAccess object.

1) Buffer.

2) Number of bytes to read.

=item Returns:

Number of bytes actually read.

=back

=item B<ReadLine>

Read a line from file (end of line is $/).

=over 4

=item Inputs:

0) Reference to RandomAccess object.

1) Buffer.

=item Returns:

Number of bytes read.

=back

=item B<Slurp>

Read whole file into buffer, without changing read pointer.

=over 4

=item Inputs:

0) Reference to RandomAccess object.

=item Returns:

Nothing.

=back

=item B<BinMode>

Set binary mode for file.

=over 4

=item Inputs:

0) Reference to RandomAccess object.

=item Returns:

Nothing.

=back

=item B<Close>

Close the file and free the buffer.

=over 4

=item Inputs:

0) Reference to RandomAccess object.

=item Returns:

Nothing.

=back

=back

=head1 AUTHOR

Copyright 2004-2006 Phil Harvey (phil at owl.phy.queensu.ca)

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=head1 SEE ALSO

L<Image::ExifTool(3pm)|Image::ExifTool>

=cut

# end