001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math3.analysis.function;
019
020import java.util.Arrays;
021import org.apache.commons.math3.analysis.UnivariateFunction;
022import org.apache.commons.math3.exception.DimensionMismatchException;
023import org.apache.commons.math3.exception.NonMonotonicSequenceException;
024import org.apache.commons.math3.exception.NullArgumentException;
025import org.apache.commons.math3.exception.NoDataException;
026import org.apache.commons.math3.util.MathArrays;
027
028/**
029 * <a href="http://en.wikipedia.org/wiki/Step_function">
030 *  Step function</a>.
031 *
032 * @since 3.0
033 */
034public class StepFunction implements UnivariateFunction {
035    /** Abscissae. */
036    private final double[] abscissa;
037    /** Ordinates. */
038    private final double[] ordinate;
039
040    /**
041     * Builds a step function from a list of arguments and the corresponding
042     * values. Specifically, returns the function h(x) defined by <pre><code>
043     * h(x) = y[0] for all x < x[1]
044     *        y[1] for x[1] <= x < x[2]
045     *        ...
046     *        y[y.length - 1] for x >= x[x.length - 1]
047     * </code></pre>
048     * The value of {@code x[0]} is ignored, but it must be strictly less than
049     * {@code x[1]}.
050     *
051     * @param x Domain values where the function changes value.
052     * @param y Values of the function.
053     * @throws NonMonotonicSequenceException
054     * if the {@code x} array is not sorted in strictly increasing order.
055     * @throws NullArgumentException if {@code x} or {@code y} are {@code null}.
056     * @throws NoDataException if {@code x} or {@code y} are zero-length.
057     * @throws DimensionMismatchException if {@code x} and {@code y} do not
058     * have the same length.
059     */
060    public StepFunction(double[] x,
061                        double[] y)
062        throws NullArgumentException, NoDataException,
063               DimensionMismatchException, NonMonotonicSequenceException {
064        if (x == null ||
065            y == null) {
066            throw new NullArgumentException();
067        }
068        if (x.length == 0 ||
069            y.length == 0) {
070            throw new NoDataException();
071        }
072        if (y.length != x.length) {
073            throw new DimensionMismatchException(y.length, x.length);
074        }
075        MathArrays.checkOrder(x);
076
077        abscissa = MathArrays.copyOf(x);
078        ordinate = MathArrays.copyOf(y);
079    }
080
081    /** {@inheritDoc} */
082    public double value(double x) {
083        int index = Arrays.binarySearch(abscissa, x);
084        double fx = 0;
085
086        if (index < -1) {
087            // "x" is between "abscissa[-index-2]" and "abscissa[-index-1]".
088            fx = ordinate[-index-2];
089        } else if (index >= 0) {
090            // "x" is exactly "abscissa[index]".
091            fx = ordinate[index];
092        } else {
093            // Otherwise, "x" is smaller than the first value in "abscissa"
094            // (hence the returned value should be "ordinate[0]").
095            fx = ordinate[0];
096        }
097
098        return fx;
099    }
100}