001    /*
002     * Copyright (C) 2007 Google Inc.
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     */
014    
015    package com.google.common.base;
016    
017    import com.google.common.annotations.GwtCompatible;
018    
019    import javax.annotation.Nullable;
020    
021    /**
022     * Determines an output value based on an input value.
023     *
024     * @author Kevin Bourrillion
025     * @since 2 (imported from Google Collections Library)
026     */
027    @GwtCompatible
028    public interface Function<F, T> {
029      /**
030       * Returns the result of applying this function to {@code input}. This method is <i>generally
031       * expected</i>, but not absolutely required, to have the following properties:
032       *
033       * <ul>
034       * <li>Its execution does not cause any observable side effects.
035       * <li>The computation is <i>consistent with equals</i>; that is, {@link Objects#equal
036       *     Objects.equal}{@code (a, b)} implies that {@code Objects.equal(function.apply(a),
037       *     function.apply(b))}.
038       * </ul>
039       *
040       * @throws NullPointerException if {@code input} is null and this function does not accept null
041       *     arguments
042       */
043      T apply(@Nullable F input);
044    
045      /**
046       * Indicates whether another object is equal to this function.
047       *
048       * <p>Most implementations will have no reason to override the behavior of {@link Object#equals}.
049       * However, an implementation may also choose to return {@code true} whenever {@code object} is a
050       * {@link Function} that it considers <i>interchangeable</i> with this one. "Interchangeable"
051       * <i>typically</i> means that {@code Objects.equal(this.apply(f), that.apply(f))} is true for all
052       * {@code f} of type {@code F}). Note that a {@code false} result from this method does not imply
053       * that the functions are known <i>not</i> to be interchangeable.
054       */
055      boolean equals(@Nullable Object object);
056    }