##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::PackedFile - diachronic collocation db: flat fixed-length record-oriented files

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::PackedFile;
 
 ##========================================================================
 ## Constructors etc.
 
 $pf = $CLASS_OR_OBJECT->new(%opts);
 
 ##========================================================================
 ## API: open/close
 
 $pf   = $pf->open();
 $bool = $pf->opened();
 $bool = $pf->close();
 $bool = $pf->setsize($nrecords);
 $bool = $pf->truncate();
 $bool = $pf->flush();
 
 ##========================================================================
 ## API: filters
 
 $pf = $pf->setFilters($packfmt);
 
 ##========================================================================
 ## API: positioning
 
 $nrecords = $pf->size();
 $bool  = $pf->seek($recno);
 $recno = $pf->tell();
 $bool  = $pf->reset();
 $bool  = $pf->seekend();
 $bool  = $pf->eof();
 
 ##========================================================================
 ## API: record access: read
 
 $bool = $pf->read(\$buf);
 $bool = $pf->readraw(\$buf, $nrecords);
 
 $value_or_undef = $pf->get();
 \$buf_or_undef  = $pf->getraw(\$buf);
 
 $value_or_undef = $pf->fetch($index);
 $buf_or_undef   = $pf->fetchraw($index,\$buf);
 
 ##========================================================================
 ## API: record access: write
 
 $bool = $pf->write($buf)
 
 $value_or_undef = $pf->set($value);
 $value_or_undef = $pf->store($index,$value);
 $value_or_undef = $pf->push($value);
 
 ##========================================================================
 ## API: batch I/O
 
 \@data = $pf->toArray(%opts);
 $pf    = $pf->fromArray(\@data,%opts);
 
 $pdl   = $pf->toPdl(%opts);
 
 ##========================================================================
 ## API: binary search
 
 $index_or_undef = $pf->bsearch($key, %opts);
 
 ##========================================================================
 ## disk usage, timestamp, etc
 
 @files = $obj->diskFiles();
 
 ##========================================================================
 ## I/O: header
 
 @keys = $coldb->headerKeys();
 
 ##========================================================================
 ## I/O: text
 
 $bool = $pf->loadTextFh($fh, %opts);
 $bool = $pf->saveTextFh($fh, %opts);
 
 ##========================================================================
 ## API: tie interface
 
 $tied = tie(@array, $CLASS, $file, $flags, %opts);
 $tied = $CLASS->TIEARRAY($file, $flags, %opts);

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::PackedFile provides an object-oriented interface
for static fixed-length record sets accessed via direct file I/O.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::PackedFile inherits from
L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $pf = CLASS_OR_OBJECT->new(%opts);

%opts, %$pf:

 ##-- user options
 file     => $filename,   ##-- default: undef (none)
 flags    => $flags,      ##-- fcntl flags or open-mode (default='r')
 perms    => $perms,      ##-- creation permissions (default=(0666 &~umask))
 reclen   => $reclen,     ##-- record-length in bytes: (default: guess from pack format if available)
 packas   => $packas,     ##-- pack-format or array; see DiaColloDB::Utils::packFilterStore();
 ##
 ##-- filters
 filter_fetch => $filter, ##-- DB_File-style filter for fetch
 filter_store => $filter, ##-- DB_File-style filter for store
 ##
 ##-- low-level data
 fh       => $fh,         ##-- underlying filehandle

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: open/close
=pod

=head2 API: open/close

=over 4

=item open

 $pf = $pf->open();
 $pf = $pf->open($file)
 $pf = $pf->open($file,$flags,%opts)

%opts are as for new();
$file defaults to $pf-E<gt>{file}.

=item opened

 $bool = $pf->opened();

returns true iff underlying file is opened.

=item close

 $bool = $pf->close();

close underlying file.
Implicitly calls flush() if opened for writing.

=item setsize

 $bool = $pf->setsize($nrecords);

set the size of the underlying file to contain $nrecords records.

=item truncate

 $bool = $pf->truncate();

truncates $pf-E<gt>{fh} or $pf-E<gt>{file}; otherwise a no-nop.

=item flush

 $bool = $pf->flush();

writes header-file
and attempts to flush underlying filehandle (may not work on all systems without subsequent close()).

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: filters
=pod

=head2 API: filters

=over 4

=item setFilters

 $pf = $pf->setFilters($packfmt);
 $pf = $pf->setFilters([$packfmt, $unpackfmt])
 $pf = $pf->setFilters([\&packsub,\&unpacksub])

%opts : override (but don't clobber) $pf-E<gt>{packfmt}

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: positioning
=pod

=head2 API: positioning

=over 4

=item size

 $nrecords = $pf->size();

returns number of records in the underlying file.

=item seek

 $bool = $pf->seek($recno);

seek to record-number $recno

=item tell

 $recno = $pf->tell();

report current record-number

=item reset

 $bool = $pf->reset();

reset position to beginning of file

=item seekend

 $bool = $pf->seekend();

seek to end-of file

=item eof

 $bool = $pf->eof();

returns true iff current position is end-of-file

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: record access: read
=pod

=head2 API: record access: read

=over 4

=item read

 $bool = $pf->read(\$buf);

read a raw record into \$buf

=item readraw

 $bool = $pf->readraw(\$buf, $nrecords);

batch-reads $nrecords into \$buf

=item get

 $value_or_undef = $pf->get();

get (unpacked) value of current record, increments filehandle position to next record

=item getraw

 \$buf_or_undef = $pf->getraw(\$buf);

get (packed) value of current record, increments filehandle position to next record

=item fetch

 $value_or_undef = $pf->fetch($index);

get (unpacked) value of record $index

=item fetchraw

 $buf_or_undef = $pf->fetchraw($index,\$buf);

get (packed) value of record $index

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: record access: write
=pod

=head2 API: record access: write

=over 4

=item write

 $bool = $pf->write($buf);

write a raw record $buf to current position; increments position

=item set

 $value_or_undef = $pf->set($value);

set (packed) value of current record, increments filehandle position to next record

=item store

 $value_or_undef = $pf->store($index,$value);

store (packed) $value as record-number $index

=item push

 $value_or_undef = $pf->push($value);

store (packed) $value at end of record

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: batch I/O
=pod

=head2 API: batch I/O

=over 4

=item toArray

 \@data = $pf->toArray(%opts);

read entire file contents to an array.
%opts : override %$pf:

 packas => $packas

=item fromArray

 $pf = $pf->fromArray(\@data,%opts);

write file contents from a perl array.
%opts : override %$pf:

 packas => $packas


=item toPdl

 $pdl = $pf->toPdl(%opts);

Returns a flat PDL object representing $pf; currently only supports unary integer pack-templates.
Requires L<PDL|PDL> and L<PDL::IO::FastRaw|PDL::IO::FastRaw>.
Supported %opts:

 type => $pdl_type,    ##-- pdl type (default:'auto':guess)
 swap => $bool_or_sub, ##-- byte-swap? (default:'auto':guess)
 mmap => $bool,        ##-- mmap data? (default: 0)
 ...                   ##-- other options passed to DiaColloDB::Utils::readPdlFile()

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: binary search
=pod

=head2 API: binary search

=over 4

=item bsearch

 $index_or_undef = $pf->bsearch($key, %opts);

%opts:

 lo => $ilo,        ##-- index lower-bound for search (default=0)
 hi => $ihi,        ##-- index upper-bound for search (default=size)
 packas => $packas, ##-- key-pack template (default=$pf->{packas})

returns the minimum index C<$i> such that C<unpack($packas,$pf-E<gt>[$i]) == $key> and C<$ilo E<lt>= $j E<lt> $i>,
or C<undef> if no such C<$i> exists.

C<$key> must be a numeric value, and records must be stored in ascending order
by numeric value of key (as unpacked by C<$packas>) between C<$ilo> and C<$ihi>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: disk usage, timestamp, etc
=pod

=head2 disk usage, timestamp, etc

L<DiaColloDB::Persistent|DiaColloDB::Persistent> overrides.

=over 4

=item diskFiles

 @files = $obj->diskFiles();

returns disk storage files, used by du() and timestamp().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: I/O: header
=pod

=head2 I/O: header

=over 4

=item headerKeys

 @keys = $coldb->headerKeys();

keys to save as header

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: I/O: text
=pod

=head2 I/O: text

See also L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=over 4

=item saveTextFh

 $bool = $pf->saveTextFh($fh, %opts);

save from text file with lines of the form "KEY? VALUE(s)...".
%opts:

 keys=>$bool,    ##-- do/don't save keys (default=true)
 key2s=>$key2s,  ##-- code-ref for key formatting, called as $s=$key2s->($key)

=item loadTextFh

$bool = $pf->loadTextFh($fh, %opts);

Load from text file with lines of the form "KEY? VALUE(s)...".
%opts:

 keys=>$bool,     ##-- expect keys in input? (default=true)
 gaps=>$bool,     ##-- expect gaps or out-of-order elements in input? (default=false; implies keys=>1)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile: API: tie interface
=pod

=head2 API: tie interface

=over 4

=item TIEARRAY

 $tied = tie(@array, $CLASS, $file, $flags, %opts);
 $tied = $CLASS->TIEARRAY($file, $flags, %opts);

Transparently tie a DiaColloDB::PackedFile object to a perl array.

=back

=cut

##========================================================================
## TODO
=pod

=head1 TODO

write mmap subclass

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DiaColloDB::Persistent(3pm)|DiaColloDB::Persistent>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
