/*
 * File:        Utilities.java
 * Author:      Justin Basilico
 * Course:      PO CS 152: Neural Networks
 * Assignment:  Final Project
 * Updated:     2001.12.18
 * Created:     2001.12.03
 *
 * Description:
 * This file contains the Utilities abstract class, which is a collection of
 * general utilities that are used by the program.
 *
 * Copyright:    Justin Basilico (2001).
 */

import java.io.File;
import java.text.NumberFormat;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.Random;

/**
 * Utilities abstract class
 *
 * This class is just a collection of static methods that provide general
 * utilities for doing various things such as simple array manipulations.
 * Since all of the methods are static, no instances of this class should
 * exist, so it is abstract.
 *
 * @author  Justin Basilico
 * @version 2001.12.18
 */
public abstract class Utilities
    extends Object
{
    /** NF1
     * This NumberFormat gives Strings of numbers with one decimal point. */
    public static NumberFormat  NF1 = NumberFormat.getNumberInstance();

    /** NF3
     * This NumberFormat gives Strings of numbers with three decimal points.
     */
    public static NumberFormat  NF3 = NumberFormat.getNumberInstance();

    /** NF7
     * This NumberFormat gives Strings of numbers with seven decimal points.
     */
    public static NumberFormat  NF7 = NumberFormat.getNumberInstance();

    // Initialize the number formatters.
    static
    {
        NF1.setMinimumFractionDigits(1);
        NF1.setMaximumFractionDigits(1);
        NF3.setMinimumFractionDigits(3);
        NF3.setMaximumFractionDigits(3);
        NF7.setMinimumFractionDigits(7);
        NF7.setMaximumFractionDigits(7);
    }

    /**
     * fileExists
     *
     * This method takes a String file name and returns true if that file
     * exists.
     *
     * @param  fileName The String name of a file.
     * @return True if a file of the given name exists. False otherwise.
     */
    public static boolean fileExists(
        String              fileName)           // The file's name.
    {
        return (new File(fileName)).exists();
    }

    /**
     * zeroArray
     *
     * This method takes an array and sets all of the elements in it to 0.0.
     * It returns nothing, the given array is just changed.
     *
     * @param  array The array of doubles to set all of the elements in to
     *         0.0.
     * @throws NullPointerException If the given array is null.
     */
    public static void zeroArray(
        double[]            array)              // Array to zero-out.
    {
        for (int i = 0; i < array.length; i++)
            array[i] = 0.0;
    }

    /**
     * zeroMatrix
     *
     * This method takes a matrix which is an array of arrays of doubles and
     * sets all elements in the matrix to 0.0.
     *
     * @param  array The array of arrays of doubles to set all of the elements
     *         in to 0.0.
     * @throws NullPointerException If the given array or any sub-arrays are
     *         null.
     */
    public static void zeroMatrix(
        double[][]          matrix)             // Matrix to zero-out.
    {
        for (int i = 0; i < matrix.length; i++)
            for (int j = 0; j < matrix[i].length; j++)
                matrix[i][j] = 0.0;
    }

    /**
     * randomizeArray
     *
     * This method takes an array of doubles, a Random object, and a minimum
     * and maximum value. It sets all of the values in the array to a random
     * double between the given minimum and maximum, uniformly distributed,
     * by using the given Random object's nextDouble() method. Nothing is
     * returned because the given array is changed.
     *
     * @param  array The array of doubles to randomize the elements of.
     * @param  random The Random object for generating random doubles.
     * @param  min The minimum value for the random doubles.
     * @param  max The maximum value for the random doubles.
     * @throws NullPointerException If the given array or Random is null.
     * @see    java.util.Random.nextDouble()
     */
    public static void randomizeArray(
        double[]            array,              // Array to randomize.
        Random              random,             // Random number generator.
        double              min,                // Minimum random value.
        double              max)                // Maximum random value.
    {
        // The scale is the amount to scale the random values by.
        double scale = max - min;

        for (int i = 0; i < array.length; i++)
                // The value is the scale plus the minimum value.
                array[i] = scale * random.nextDouble() + min;
    }

    /**
     * randomizeMatrix
     *
     * This method takes a matrix, which is an array of arrays of doubles, a
     * Random object, and a minimum and maximum value. It sets all of the
     * values in the matrix to a random double between the given minimum and
     * maximum, uniformly distributed, by using the given Random object's
     * nextDouble() method. Nothing is returned because the given matrix is
     * changed.
     *
     * @param  array The array of doubles to randomize the elements of.
     * @param  random The Random object for generating random doubles.
     * @param  min The minimum value for the random doubles.
     * @param  max The maximum value for the random doubles.
     * @throws NullPointerException If the given array, one of its sub-arrays,
     *         or Random is null.
     * @see    java.util.Random.nextDouble()
     */
    public static void randomizeMatrix(
        double[][]          matrix,             // Matrix to randomize.
        Random              random,             // Random number generator.
        double              min,                // Minimum random value.
        double              max)                // Maximum random value.
    {
        // The scale is the amount to scale the random values by.
        double scale = max - min;

        for (int i = 0; i < matrix.length; i++)
            for (int j = 0; j < matrix[i].length; j++)
                // The value is the scale plus the minimum value.
                matrix[i][j] = scale * random.nextDouble() + min;
    }

    /**
     * randomizeArray (boolean)
     *
     * This method takes an array of booleans and a Random object. It sets all
     * of the values in the array to a random boolean by using the Random
     * object's nextDouble() method and setting the value to true if the
     * double is greater than or equal to 0.5. No value is returned because
     * the given array itself is modified.
     *
     * It just calls the thresholded version of this method with a threshold
     * of 0.5.
     *
     * @param  array The array of booleans to randomize.
     * @param  random The Random object for generating random numbers.
     * @throws NullPointerException If the given array or Random is null.
     * @see    Utilities.randomizeArray(double[], Random, double)
     * @see    java.util.Random.nextDouble()
     */
    public static void randomizeArray(
        boolean[]           array,              // Array to randomize.
        Random              random)             // Random number generator.
    {
        // Just use a threshold of 0.5.
        randomizeArray(array, random, 0.5);
    }

    /**
     * randomizeArray (boolean)
     *
     * This method takes an array of booleans, a Random object, and a
     * threshold double between 0.0 and 1.0. It sets all of the values in the
     * array to a random boolean by using the Random object's nextDouble()
     * method and setting the value to true if the double is greater than or
     * equal to the given threshold value. No value is returned because the
     * given array itself is modified.
     *
     * @param  array The array of booleans to randomize.
     * @param  random The Random object for generating random numbers.
     * @throws NullPointerException If the given array or Random is null.
     * @see    java.util.Random.nextDouble()
     */
    public static void randomizeArray(
        boolean[]           array,              // Array to randomize.
        Random              random,             // Random number generator.
        double              threshold)          // Threshold for values.
    {
        for (int i = 0; i < array.length; i++)
            // Set the element to true if the random number is above the
            // threshold.
            array[i] = random.nextDouble() >= threshold;
    }

    /**
     * sumArray
     *
     * This method takes an array of integers and returns the sum of that
     * array.
     *
     * @param  array The array of integers to sum.
     * @return The integer sum of the array.
     * @throws NullPointerException If the given array is null.
     */
    public static int sumArray(
        int[]               array)              // Array to sum.
    {
        int sum = 0;

        // Add each element in the array to the sum.
        for (int i = 0; i < array.length; i++)
            sum += array[i];

        return sum;
    }

    /**
     * setArrayValue
     *
     * This method takes an array of booleans and a boolean value and sets
     * every element in that array to the given value.
     *
     * @param  array The array to set all of the elements of.
     * @param  value The boolean value to set all elements in the array to.
     * @throws NullPointerException If the given array is null.
     */
    public static void setArrayValue(
        boolean[]           array,              // Array to set the values in.
        boolean             value)              // Value to set in the array.
    {
        for (int i = 0; i < array.length; i++)
            array[i] = value;
    }

    /**
     * copyArray (boolean)
     *
     * This method takes an array of booleans and returns a copy of that array
     * of booleans.
     *
     * @param  array The array of booleans to copy.
     * @return A boolean array that is a copy of the given array.
     * @throws NullPointerException If the given array is null.
     */
    public static boolean[] copyArray(
        boolean[]           array)              // Array to copy.
    {
        boolean[] result = new boolean[array.length];

        // Use the System's array copying method.
        System.arraycopy(array, 0, result, 0, array.length);

        return result;
    }

    /**
     * integerListToArray
     *
     * This method takes a LinkedList of Integers and returns an array of
     * integers that are the values from the given list.
     *
     * @param  list The LinkedList of Integers to convert into an array.
     * @return An array of integers that contains the values from the given
     *         array.
     */
    public static int[] integerListToArray(
        LinkedList          list)               // List of Integer objects.
    {
        // Create the result array.
        int[] result = new int[list.size()];

        // Iterate through the whole list.
        Iterator it = list.iterator();
        for (int i = 0; it.hasNext(); i++)
            // Convert the ith Integer to an integer.
            result[i] = ((Integer) it.next()).intValue();

        // Return the result.
        return result;
    }

    /**
     * printArray (integer)
     *
     * This method takes an array of integers and prints it to System.out as
     * a list separated by spaces.
     *
     * @param  array The array of integers to print.
     */
    public static void printArray(
        int[]               array)              // Array to print.
    {
        for (int i = 0; i < array.length; i++)
            System.out.print(array[i] + " ");
    }

    /**
     * printArray (double)
     *
     * This method takes an array of doubles and prints it to System.out as
     * a list separated by spaces.
     *
     * @param  array The array of integers to print.
     */
    public static void printArray(
        double[]            array)              // Array to print.
    {
        for (int i = 0; i < array.length; i++)
            System.out.print(array[i] + " ");
    }

    /**
     * printArray (double, NumberFormat)
     *
     * This method takes an array of doubles using the given NumberFormat to
     * format the values in the array, it and prints it to System.out as a
     * list separated by spaces.
     *
     * @param  array The array of integers to print.
     * @param  nf The NumberFormat for formatting values in the array.
     */
    public static void printArray(
        double[]            array,              // Array to print.
        NumberFormat        nf)                 // Format for output.
    {
        for (int i = 0; i < array.length; i++)
            System.out.print(nf.format(array[i]) + " ");
    }
}