232 lines
3.6 KiB
Plaintext
Executable File
232 lines
3.6 KiB
Plaintext
Executable File
#------------------------------------------------------------------------------
|
|
# File: RandomAccess.pod -- Documentation for File::RandomAccess
|
|
#
|
|
# Description: Buffer to support random access reading of sequential file
|
|
#
|
|
# Legal: Copyright (c) 2003-2016 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 or RandomAccess class name.
|
|
|
|
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 2003-2016 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
|