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     * A transformation from one object to another. For example, a string-to-integer function would
023     * implement {@code Function<String, Integer>} to convert integer values in text form into {@code
024     * Integer} form.
025     *
026     * <p>Implementations which may cause side effects upon evaluation are strongly encouraged to state
027     * this fact clearly in their API documentation.
028     *
029     * @param <F> the type of the function input
030     * @param <T> the type of the function output
031     * @author Kevin Bourrillion
032     * @author Scott Bonneau
033     * @since 2 (imported from Google Collections Library)
034     */
035    @GwtCompatible
036    public interface Function<F, T> {
037      /**
038       * Applies the function to an object of type {@code F}, resulting in an object of type {@code T}.
039       * Note that types {@code F} and {@code T} may or may not be the same.
040       *
041       * @param from the source object
042       * @return the resulting object
043       */
044      T apply(@Nullable F from);
045    
046      /**
047       * Indicates whether some other object is equal to this {@code Function}. This method can return
048       * {@code true} <i>only</i> if the specified object is also a {@code Function} and, for every
049       * input object {@code o}, it returns exactly the same value. Thus, {@code
050       * function1.equals(function2)} implies that either {@code function1.apply(o)} and {@code
051       * function2.apply(o)} are both null, or {@code function1.apply(o).equals(function2.apply(o))}.
052       *
053       * <p>Note that it is always safe <i>not</i> to override {@link Object#equals}.
054       */
055      boolean equals(@Nullable Object obj);
056    }