# The lines from here to the =cut are part of Perl's
# internal documentation system.  If you want 
# view the documentation use the command:
#
#	pod2text <script>
#
=pod

=head1 NAME

average - Package to compute a moving average

=head1 SYNOPSIS

    use average;

    use vars qw(@raw_data);

    my $status = read_data($file_name);

    my @result = moving_average($increment);


=head1 DESCRIPTION

The I<average> package reads in a set of numbers from a give file
and computes a moving average on it.

=head1 FUNCTIONS

=over 4

=item B<$status = read_date($file_name);>

Read in a data file and store it in B<@raw_data>.  The file format is one number
per line.  The file name of the input file is specified in B<$file_name>.
The status returned is 1 if everything went ok and B<undef> if there was an 
error.

=item B<@raw_data>

Global variable containing the raw data read in through B<read_data>.

=item B<@result = moving_average($increment);>

Return a moving average.  This is an average of the data in
B<$increment> sets.  The result is an array where each element is the
average of B<$increment> points.

=back

=head1 AUTHOR

Steve Oualline, E<lt>oualline@www.oualline.comE<gt>.

=head1 COPYRIGHT

Copyright 2002 Steve Oualline.
This program is distributed under the GPL.  

=cut
use strict;
package average;
#
# Comments explaining how to use the package
# should be put here.
#
use vars qw(@ISA @EXPORT @raw_data);
require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(&read_data @raw_data moving_average);

################################################
# read_data($file_name) -- Read the data
#	from the file.  Data is stored in the 
#	global variable @raw_data
#
# Returns:
#	undef -- Error
#	1 -- Success
################################################
sub read_data($)
{
    my $file = shift;	# The file to read

    open DATA_FILE, "<$file" or 
        return (undef);
    @raw_data = <DATA_FILE>;
    chomp(@raw_data);
    close(DATA_FILE);
    return (1);	# Success
}

################################################
# sum(@array) -- Sum the elements of an array
#	and return the result
################################################
sub sum(@)
{
    my @array = @_;	# The array to sum
    my $the_sum = 0;	# Result so far

    foreach my $element (@array) {
        $the_sum += $element;
    }
    return ($the_sum);
}
################################################
# moving_averge($increment)
#
# Compute a moving average
#
# Returns:
#	Array containing the moving average
################################################
sub moving_average($)
{
    my $increment = shift;	# Increment for average
    my $index;			# Current item for average
    my @result;			# Averaged data

    for ($index = 0; 
        $index <= $#raw_data - $increment; 
        $index++) {
        my $total = sum(@raw_data[$index..$index + $increment -1]);
        push (@result, $total / $increment);
    }
    return(@result);
}

# Tell Perl we loaded successfully
1;