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

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

=head1 NAME

DiaColloDB::Relation::Unigrams - diachronic collocation db, profiling relation: native unigram index

=cut

##========================================================================
## ALIASES
=pod

=head1 ALIASES

=over 4

=item DiaColloDB::Relation::Unigrams

=item DiaColloDB::Unigrams

=back

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Relation::Unigrams;
 
 ##========================================================================
 ## Constructors etc.
 
 $ug = $CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## API: disk usage
 
 @files = $obj->diskFiles();
 
 ##========================================================================
 ## Relation API: create
 
 $ug = $CLASS_OR_OBJECT->create($coldb,$tokdat_file,%opts);
 
 ##========================================================================
 ## Relation API: union
 
 $ug = $CLASS_OR_OBJECT->union($coldb, \@pairs, %opts);
 
 ##========================================================================
 ## Relation API: default: profiling
 
 $prf = $ug->subprofile(\@xids, %opts);
 
 ##========================================================================
 ## Relation API: default: query info
 
 \%qinfo = $rel->qinfo($coldb, %opts);

=cut


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

=head1 DESCRIPTION

DiaColloDB::Relation::Unigrams
is a L<DiaColloDB::Relation|DiaColloDB::Relation> subclass for
native indices over attribute-tuple unigrams
using the L<DiaColloDB::PackedFile|DiaColloDB::PackedFile> API
for low-level index data.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Relation::Unigrams inherits from
L<DiaColloDB::Relation|DiaColloDB::Relation>
and
L<DiaColloDB::PackedFile|DiaColloDB::PackedFile>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

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

%args, object structure:

 ##-- PackedFile: 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();  ##-- OVERRIDE default='N'
 ##
 ##-- PackedFile: filters
 filter_fetch => $filter, ##-- DB_File-style filter for fetch
 filter_store => $filter, ##-- DB_File-style filter for store
 ##
 ##-- PackedFile: low-level data
 fh       => $fh,         ##-- underlying filehandle
 ##
 ##-- Unigrams: high-level data
 N        => $N,          ##-- total frequency

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: API: disk usage
=pod

=head2 API: disk usage

=over 4

=item diskFiles

 @files = $obj->diskFiles();

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

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Relation API: create
=pod

=head2 Relation API: create

=over 4

=item create

 $ug = $CLASS_OR_OBJECT->create($coldb,$tokdat_file,%opts);

populates current database from $tokdat_file,
a tt-style text file containing 1 token-id perl line with optional blank lines.

%opts: clobber %$ug, also:

 size=>$size,  ##-- set initial size

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Relation API: union
=pod

=head2 Relation API: union

=over 4

=item union

 $ug = $CLASS_OR_OBJECT->union($coldb, \@pairs, %opts);

merge multiple unigram indices into new object.
@pairs is an array of pairs ([$ug,\@xi2u],...)
of unigram-objects $ug and tuple-id maps \@xi2u for $ug.
implicitly flushes the new index.

%opts: clobber %$ug

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Relation API: default: profiling
=pod

=head2 Relation API: default: profiling

=over 4

=item subprofile

 $prf = $ug->subprofile(\@xids, %opts);

get frequency profile for @xids (index must be opened).
%opts:

 groupby => \&gbsub,  ##-- key-extractor $key2_or_undef = $gbsub->($i2)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::Unigrams: Relation API: default: query info
=pod

=head2 Relation API: default: query info

=over 4

=item qinfo

 \%qinfo = $rel->qinfo($coldb, %opts);

get query-info hash for profile administrivia (ddc hit links)
%opts: as for profile(), additionally:

 qreqs => \@qreqs,      ##-- as returned by $coldb->parseRequest($opts{query})
 gbreq => \%groupby,    ##-- as returned by $coldb->groupby($opts{groupby})

=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<dcdb-create.per(1)|dcdb-create.perl>,
L<dcdb-query.perl(1)|dcdb-query.perl>,
L<dcdb-info.perl(1)|dcdb-info.perl>,
L<dcdb-export.perl(1)|dcdb-export.perl>,
L<dcdb-dump.perl(1)|dcdb-dump.perl>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
