/*
   ###########################################################################
   This function computes the arithmetic mean value of a set of numbers
   to a specified number of decimals up to a limit of 100 decimals.

   The numbers are given in the form of a text string or table of numbers
   separated by spaces, semicolons or commas as delimiters.  All elements
   must be strictly numeric values.

   Example data string    : '110.17 112.72 115.71 111.08 110.89 111.47'
   Result, to 24 decimals :  112.006666666666666666666667

   The returned value is the arithmetic mean (average) of the given numbers.

   ERRORS:
   FALSE is returned on invalid argument.

   NO DEPENDENCIES
   ###########################################################################
*/

   function BC_Arith_Mean ($xDataTableStr, $Decimals=16)
{
   $xData = trim($xDataTableStr);
   $q     = trim($Decimals);
   $Q     = 110;

/* Remove default (, ; |) delimiters from the data
   table replacing them with blank spaces and then
   removing any redundant white space afterward.
*/
   $w = Str_Replace(',', ' ', $xData);
   $w = Str_Replace(';', ' ', $w);
   $w = Str_Replace('|', ' ', $w);
   $xData = PReg_Replace("/\s+/", ' ', trim($w));

// -------------------------------------
// Store data elements in working array.

   $xArray = PReg_Split("[ ]", $xData);
   $xcount = count($xArray);

   $sum = '0';

// ---------------------------
// Compute sum of the numbers.

   for ($i=0;   $i < $xcount;   $i++)
  {
   $CurrLine = trim($xArray[$i]);

   if (!Is_Numeric($CurrLine)) {return FALSE;}

   $sum = bcAdd($sum, $CurrLine, $Q);
  }

// --------------------------------------
// Compute arithmetic mean of given data.

   $mean = bcDiv($sum, $xcount, $Q);

// Account for numerical sign of computed mean.
   $s    = ($mean < 0)? '-' : '';
   $mean = Str_Replace('-', '', $mean);
   $mean = $s.bcAdd($mean, '0.' . Str_Repeat('0', $q) . '5', $q);

// Done.
   return Rtrim(Rtrim($mean, '0'), '.');

} // End of  BC_Arith_Mean (...)