#!/usr/bin/perl -w

#
# dbcoluniqcount.pm
# Copyright (C) 1997-2025 by John Heidemann <johnh@isi.edu>
#
# This program is distributed under terms of the GNU general
# public license, version 2.  See the file COPYING
# in $dblibdir for details.
#


=head1 NAME

dbcoluniqcount - count rows with identicial fields

=head1 SYNOPSIS

dbrowuniq [-FLB] [uniquifying fields...]

=head1 DESCRIPTION

Count number rows grouped by each value of field (or fields).
Equivalent to the Fsdb L<dbrowuniq> command with C<-c>,
but does not require the lines to be adjacent.

Unlike L<dbrowuniq>, we do I<not> require rows to be adajcent.
By default we the number of unique rows is small and we cache them in memory,
running quickly (O(n) time).
Optionally in the future we will give up and fall back on external sorting,
but this feature is not yet implemented.

As with L<dbroquniq>,
by default, L<dbcoluniqcount> outputs the I<first> unique row.
Optionally, with C<-L>, it will output the I<last> unique row,
or with C<-B> it outputs both first and last.
(This choice only matters when uniqueness is determined by specific fields.)

Incremental counting, when the C<count> column already exists,
is possible with C<-I>.
With incremental counting, the existing count column is summed.

=head1 OPTIONS

=over 4

=item B<-c> or B<--count>

Create a new column (count) which counts the number of times
each line occurred.

The new column is named by the C<-N> argument, defaulting to C<count>.

=item B<-N> on B<--new-name>

Specify the name of the count column, if any.
Please specify the type with the name, if desired
(allowing one to pick sizes smaller than the default quad, if desired).
(Default is C<count:q>.)

=item B<-I> on B<--incremental>

Incremental counting.
If the count column exists, it is assumed to have a partial count
and the count accumulates.
If the count column doesn't exist, it is created.

=item B<-L> or B<--last>

Output the last unique row only.
By default, it outputs the first unique row.

=item B<-F> or B<--first>

Output the first unique row only. 
(This output is the default.)

=item B<-B> or B<--both>

Output both the first and last unique rows. 

=back

=for comment
begin_standard_fsdb_options

This module also supports the standard fsdb options:

=over 4

=item B<-d>

Enable debugging output.

=item B<-i> or B<--input> InputSource

Read from InputSource, typically a file name, or C<-> for standard input,
or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

=item B<-o> or B<--output> OutputDestination

Write to OutputDestination, typically a file name, or C<-> for standard output,
or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

=item B<--autorun> or B<--noautorun>

By default, programs process automatically,
but Fsdb::Filter objects in Perl do not run until you invoke
the run() method.
The C<--(no)autorun> option controls that behavior within Perl.

=item B<--header> H

Use H as the full Fsdb header, rather than reading a header from
then input.

=item B<--help>

Show help.

=item B<--man>

Show full manual.

=back

=for comment
end_standard_fsdb_options


=head1 SAMPLE USAGE

=head2 Input:

    #fsdb      event
    _null_getpage+128
    _null_getpage+128
    _null_getpage+128
    _null_getpage+4
    _null_getpage+4
    _null_getpage+4
    _null_getpage+128
    _null_getpage+128
    _null_getpage+128
    _null_getpage+4
    _null_getpage+4
    _null_getpage+4
    #  | /home/johnh/BIN/DB/dbcol event
    #  | /home/johnh/BIN/DB/dbsort event

=head2 Command:

    cat data.fsdb | dbrowuniq -c

=head2 Output:

    #fsdb	event	count
    _null_getpage+128	6
    _null_getpage+4	6
    #	2	/home/johnh/BIN/DB/dbcol	event
    #  | /home/johnh/BIN/DB/dbcoluniqcount

=head1 SAMPLE USAGE 2

Retaining the last unique row as an example.

=head2 Input:

	#fsdb event i
	_null_getpage+128 10
	_null_getpage+128 11
	_null_getpage+128 12
	_null_getpage+4 16
	_null_getpage+4 17
	_null_getpage+4 18
	_null_getpage+128 13
	_null_getpage+128 14
	_null_getpage+128 15
	_null_getpage+4 19
	_null_getpage+4 20
	_null_getpage+4 21
	#  | /home/johnh/BIN/DB/dbcol event
	#  | /home/johnh/BIN/DB/dbsort event

=head2 Command:

    cat data.fsdb | dbrowuniq -c -L event

=head2 Output:

	#fsdb event i count
	_null_getpage+128	15	6
	_null_getpage+4	21	6
	#  | /home/johnh/BIN/DB/dbcol event
	#  | /home/johnh/BIN/DB/dbsort event
	#   | dbcoluniqcount -L event


=head1 SEE ALSO

L<Fsdb>, L<dbrowuniq>.


=cut


# WARNING: This code is derived from dbcoluniqcount.pm; that is the master copy.

use Fsdb::Filter::dbcoluniqcount;
my $f = new Fsdb::Filter::dbcoluniqcount(@ARGV);
$f->setup_run_finish;  # or could just --autorun
exit 0;


=head1 AUTHOR and COPYRIGHT

Copyright (C) 1997-2025 by John Heidemann <johnh@isi.edu>

This program is distributed under terms of the GNU general
public license, version 2.  See the file COPYING
with the distribution for details.

=cut

1;
