123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231 |
- #------------------------------------------------------------------------------
- # 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
|