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

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

=head1 NAME

DiaColloDB::MultiMapFile - diachronic collocation db, integer->integer* multimap file, e.g. for expansion indices

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::MultiMapFile;
 
 ##========================================================================
 ## Constructors etc.
 
 $mmf = $CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## I/O: open/close (file)
 
 $mmf_or_undef = $mmf->open($base,$flags);
 $mmf_or_undef = $mmf->close();
 $bool = $mmf->opened();
 $bool = $mmf->dirty();
 $bool = $mmf->flush();
 \@a2b = $mmf->toArray();
 $mmf = $mmf->fromArray(\@a2b);
 $bool = $mmf->load();
 $mmf = $mmf->save();
 
 ##========================================================================
 ## I/O: header
 
 @keys = $coldb->headerKeys();
 $bool = $mmf->loadHeaderData($hdr);
 
 ##========================================================================
 ## I/O: text
 
 $mmf  = $CLASS_OR_OBJECT->loadTextFh($fh);
 $bool = $mmf->saveTextFh($fh,%opts);
 
 ##========================================================================
 ## Methods: population (in-memory only)
 
 $newsize = $mmf->addPairs($a,@bs);
 
 ##========================================================================
 ## Methods: lookup
 
 $bs_packed    = $mmf->fetchraw($a);
 \@bs_or_undef = $mmf->fetch($a);

=cut

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

=head1 DESCRIPTION

DiaColloDB::MultiMapFile provides an object-oriented interface for
static I<integer-E<gt>set(integer)> multi-maps
accessed via direct file I/O, used e.g.
by native equivalence class expansion indices.

=cut

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

=head2 Globals & Constants

=over 4

=item Variable: @ISA

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

=back

=cut

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

=head2 Constructors etc.

=over 4

=item new

 $mmf = CLASS_OR_OBJECT->new(%args);

%args, object structure:

 base => $base,       ##-- database basename; use files "${base}.ma", "${base}.mb", "${base}.hdr"
 perms => $perms,     ##-- default: 0666 & ~umask
 flags => $flags,     ##-- default: 'r'
 pack_i => $pack_i,   ##-- integer pack template (default='N')
 size => $size,       ##-- number of mapped , like scalar(@data)
 ##
 ##-- in-memory construction
 a2b => \@a2b,        ##-- maps source integers to (packed) target integer-sets: [$a] => pack("${pack_i}*", @bs)
 ##
 ##-- computed pack templates and lengths (after open())
 pack_a => $pack_a,   ##-- "($pack_i)[2]"
 pack_b => $pack_a,   ##-- "($pack_i)*"
 len_i => $len_i,     ##-- bytes::length(pack($pack_i,0))
 len_a => $len_a,     ##-- bytes::length(pack($pack_a,0))
 ##
 ##-- filehandles (after open())
 afh => $afh,         ##-- $base.ma : [$a]      => pack(${pack_a}, $bidx_a, $blen_a) : $byte_offset_in_bfh = $len_i*$bidx_a
 bfh => $bfh,         ##-- $base.mb : [$bidx_a] => pack(${pack_b}, @targets_for_a)   : $byte_length_in_bfh = $len_i*$blen_a

B<NOTE>: underlying file format changed from DiaColloDB v0.08.006 to v0.09.001; old-format files should be
autodetected and a backwards-compatible API is offered by the
L<DiaColloDB::MultiMapFile::v0_08|DiaColloDB::MultiMapFile::v0_08> class.

=item DESTROY

Destructor implicitly calls close().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::MultiMapFile: I/O: open/close (file)
=pod

=head2 I/O: open/close (file)

=over 4

=item open

 $mmf_or_undef = $mmf->open($base,$flags);
 $mmf_or_undef = $mmf->open($base);
 $mmf_or_undef = $mmf->open();

Open underlying files.
Attempts to autodetect obsolete file formats and may re-bless C<$mmf> into
an appropriate compatibility package.

=item close

 $mmf_or_undef = $mmf->close();

Close underlying files.
Implicitly calls flush() if opened for writing.

=item opened

 $bool = $mmf->opened();

Returns true iff underlying files are opened.

=item dirty

 $bool = $mmf->dirty();

Returns true iff some in-memory structures haven't been flushed to disk.

=item flush

 $bool = $mmf->flush();


=over 4

=item *

flush in-memory structures to disk

=item *

clobbers any old disk-file contents with in-memory maps

=item *

multimap must be opened in write-mode

=item *

invalidates any old references to {a2b} (but doesn't empty them if you need to keep a reference)

=back

=item toArray

 \@a2b = $mmf->toArray();

returns an in-memory dump of the multimap contents as a perl ARRAY-ref indexed by $a
whose values are packed strings of the $b items associated with $a:

 @bs = unpack("$mmf->{pack_i}*", $a2b[$a]);

=item fromArray

 $mmf = $mmf->fromArray(\@a2b);

Populate from perl array.
Clobbers $mmf contents, steals \@a2b.

=item load

 $bool = $mmf->load();

loads files to memory; must be opened.

=item save

 $mmf = $mmf->save();
 $mmf = $mmf->save($base);

saves multimap to $base; really just a wrapper for open() and flush().

=back

=cut

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

=head2 I/O: header

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

=over 4

=item headerKeys

 @keys = $coldb->headerKeys();

keys to save as header

=item loadHeaderData

 $bool = $mmf->loadHeaderData($hdr);

override.

=back

=cut

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

=head2 I/O: text

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

=over 4

=item loadTextFh

 $mmf = $CLASS_OR_OBJECT->loadTextFh($fh,%opts);

Loads from text file with lines of the form "A B1 B2...",
clobbering any pre-existing multimap contents.

=item saveTextFh

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

Save to text file with lines of the form "A B1 B2...".
%opts:

 a2s=>\&a2s  ##-- stringification code for A items, called as $s=$a2s->($bi)
 b2s=>\&b2s  ##-- stringification code for B items, called as $s=$b2s->($bi)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::MultiMapFile: Methods: population (in-memory only)
=pod

=head2 Methods: population (in-memory only)

=over 4

=item addPairs

 $newsize = $mmf->addPairs($a,@bs);
 $newsize = $mmf->addPairs($a,\@bs)

adds mappings $a=E<gt>$b foreach $b in @bs.
multimap must be loaded to memory.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::MultiMapFile: Methods: lookup
=pod

=head2 Methods: lookup

=over 4

=item fetchraw

 $bs_packed = $mmf->fetchraw($a);

Returns a packed array
C<$bs_packed = pack($mmf-E<gt>{pack_b}, @bs)>
of targets for $a, or undef if not found.
multimap must be opened.


=item fetch

 \@bs_or_undef = $mmf->fetch($a);

Returns array \@bs of targets for $a, or undef if not found.
multimap must be opened.

=back

=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::MultiMapFile::MMap(3pm)|DiaColloDB::MultiMapFile::MMap>,
L<DiaColloDB::MultiMapFile::v0_08(3pm)|DiaColloDB::MultiMapFile::v0_08>,
L<DiaColloDB::Persistent(3pm)|DiaColloDB::Persistent>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
