/*
* Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.functions;
/**
* Reduce an input object by combining with a base object.
*
*
All reducer implementations are expected to:
*
* - Provide stable results such that for any {@code a} and {@code b} the
* result of two {@code reduce} operations are always equivalent. ie.
* Foo one = reducer.reduce(a,b);
* Foo two = reducer.reduce(a,b);
*
* assert one.equals(two) && two.equals(one);
*
* - The reducer should not modify the input object in any way that would
* change the result.
* - When used for aggregate operations upon many elements reducers
* should not assume that the {@code reduce} operation will be called upon
* elements in any specific orderie.
* Foo one = reducer.reduce(a,reducer.reduce(b,c));
* Foo two = reducer.reduce(b,reducer.reduce(a,c));
*
* assert one.equals(two) && two.equals(one);
*
/li>
*
* @param the type of input objects provided to {@code reduce}.
* @param the type of the base value and output objects from {@code reduce}.
* This may be the same type as {@code }.
*/
public interface Reducer {
/**
* Produce a reduced output using the provided input and base objects.
*
* @param base the reduction base.
* @param t the input object.
* @return reduced output.
*/
U reduce(U base, T t);
/**
* Returns a reducer which conditionally performs reduce on the input from
* {@code } to {@code }. The reduce is only performed if the provided
* predicate returns {@code true} for the input {@code }.
* @param predicate A Predicate for {@code } values.
* @return A reducer which conditionally performing reduction from {@code } to
* {@code } if the {@code } input value satisfies a predicate.
*/
Reducer compose(Predicate super T> predicate) default Reducers.compose;
/**
* Returns a reducer which performs a mapping of inputs from {@code } to
* {@code } before reducing to the result.
* @param Type of input objects.
* @param mapper A mapper from {@code } to {@code }.
* @return A reducer which performing a mapping from {@code } to
* {@code }prior to reducing from {@code } to {@code }.
*/
Reducer compose(Mapper super V, ? extends T> mapper) default Reducers.compose;
}