Triple.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      https://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.lang3.tuple;

  18. import java.io.Serializable;
  19. import java.util.Objects;

  20. import org.apache.commons.lang3.builder.CompareToBuilder;

  21. /**
  22.  * A triple consisting of three elements.
  23.  *
  24.  * <p>This class is an abstract implementation defining the basic API.
  25.  * It refers to the elements as 'left', 'middle' and 'right'.</p>
  26.  *
  27.  * <p>Subclass implementations may be mutable or immutable.
  28.  * However, there is no restriction on the type of the stored objects that may be stored.
  29.  * If mutable objects are stored in the triple, then the triple itself effectively becomes mutable.</p>
  30.  *
  31.  * @param <L> the left element type.
  32.  * @param <M> the middle element type.
  33.  * @param <R> the right element type.
  34.  * @since 3.2
  35.  */
  36. public abstract class Triple<L, M, R> implements Comparable<Triple<L, M, R>>, Serializable {

  37.     /** Serialization version */
  38.     private static final long serialVersionUID = 1L;

  39.     /**
  40.      * An empty array.
  41.      * <p>
  42.      * Consider using {@link #emptyArray()} to avoid generics warnings.
  43.      * </p>
  44.      *
  45.      * @since 3.10
  46.      */
  47.     public static final Triple<?, ?, ?>[] EMPTY_ARRAY = {};

  48.     /**
  49.      * Returns the empty array singleton that can be assigned without compiler warning.
  50.      *
  51.      * @param <L> the left element type.
  52.      * @param <M> the middle element type.
  53.      * @param <R> the right element type.
  54.      * @return the empty array singleton that can be assigned without compiler warning.
  55.      * @since 3.10
  56.      */
  57.     @SuppressWarnings("unchecked")
  58.     public static <L, M, R> Triple<L, M, R>[] emptyArray() {
  59.         return (Triple<L, M, R>[]) EMPTY_ARRAY;
  60.     }

  61.     /**
  62.      * Obtains an immutable triple of three objects inferring the generic types.
  63.      *
  64.      * <p>This factory allows the triple to be created using inference to
  65.      * obtain the generic types.</p>
  66.      *
  67.      * @param <L> the left element type.
  68.      * @param <M> the middle element type.
  69.      * @param <R> the right element type.
  70.      * @param left  the left element, may be null.
  71.      * @param middle the middle element, may be null.
  72.      * @param right  the right element, may be null.
  73.      * @return a triple formed from the three parameters, not null.
  74.      */
  75.     public static <L, M, R> Triple<L, M, R> of(final L left, final M middle, final R right) {
  76.         return ImmutableTriple.of(left, middle, right);
  77.     }

  78.     /**
  79.      * Obtains an immutable triple of three non-null objects inferring the generic types.
  80.      *
  81.      * <p>This factory allows the triple to be created using inference to
  82.      * obtain the generic types.</p>
  83.      *
  84.      * @param <L> the left element type.
  85.      * @param <M> the middle element type.
  86.      * @param <R> the right element type.
  87.      * @param left  the left element, may not be null.
  88.      * @param middle  the middle element, may not be null.
  89.      * @param right  the right element, may not be null.
  90.      * @return a triple formed from the three parameters, not null.
  91.      * @throws NullPointerException if any input is null.
  92.      * @since 3.13.0
  93.      */
  94.     public static <L, M, R> Triple<L, M, R> ofNonNull(final L left, final M middle, final R right) {
  95.         return ImmutableTriple.ofNonNull(left, middle, right);
  96.     }

  97.     /**
  98.      * Constructs a new instance.
  99.      */
  100.     public Triple() {
  101.         // empty
  102.     }

  103.     /**
  104.      * Compares the triple based on the left element, followed by the middle element,
  105.      * finally the right element.
  106.      * The types must be {@link Comparable}.
  107.      *
  108.      * @param other  the other triple, not null.
  109.      * @return negative if this is less, zero if equal, positive if greater.
  110.      */
  111.     @Override
  112.     public int compareTo(final Triple<L, M, R> other) {
  113.       return new CompareToBuilder().append(getLeft(), other.getLeft())
  114.           .append(getMiddle(), other.getMiddle())
  115.           .append(getRight(), other.getRight()).toComparison();
  116.     }

  117.     /**
  118.      * Compares this triple to another based on the three elements.
  119.      *
  120.      * @param obj  the object to compare to, null returns false.
  121.      * @return true if the elements of the triple are equal.
  122.      */
  123.     @Override
  124.     public boolean equals(final Object obj) {
  125.         if (obj == this) {
  126.             return true;
  127.         }
  128.         if (obj instanceof Triple<?, ?, ?>) {
  129.             final Triple<?, ?, ?> other = (Triple<?, ?, ?>) obj;
  130.             return Objects.equals(getLeft(), other.getLeft())
  131.                 && Objects.equals(getMiddle(), other.getMiddle())
  132.                 && Objects.equals(getRight(), other.getRight());
  133.         }
  134.         return false;
  135.     }

  136.     /**
  137.      * Gets the left element from this triple.
  138.      *
  139.      * @return the left element, may be null.
  140.      */
  141.     public abstract L getLeft();

  142.     /**
  143.      * Gets the middle element from this triple.
  144.      *
  145.      * @return the middle element, may be null.
  146.      */
  147.     public abstract M getMiddle();

  148.     /**
  149.      * Gets the right element from this triple.
  150.      *
  151.      * @return the right element, may be null.
  152.      */
  153.     public abstract R getRight();

  154.     /**
  155.      * Returns a suitable hash code.
  156.      * <p>
  157.      * The hash code is adapted from the definition in {@code Map.Entry}.
  158.      * </p>
  159.      *
  160.      * @return the hash code.
  161.      */
  162.     @Override
  163.     public int hashCode() {
  164.         // See Map.Entry API specification
  165.         return Objects.hashCode(getLeft()) ^ Objects.hashCode(getMiddle()) ^ Objects.hashCode(getRight());
  166.     }

  167.     /**
  168.      * Returns a String representation of this triple using the format {@code (left,middle,right)}.
  169.      *
  170.      * @return a string describing this object, not null.
  171.      */
  172.     @Override
  173.     public String toString() {
  174.         return "(" + getLeft() + "," + getMiddle() + "," + getRight() + ")";
  175.     }

  176.     /**
  177.      * Formats the receiver using the given format.
  178.      *
  179.      * <p>This uses {@link java.util.Formattable} to perform the formatting. Three variables may
  180.      * be used to embed the left and right elements. Use {@code %1$s} for the left
  181.      * element, {@code %2$s} for the middle and {@code %3$s} for the right element.
  182.      * The default format used by {@code toString()} is {@code (%1$s,%2$s,%3$s)}.</p>
  183.      *
  184.      * @param format  the format string, optionally containing {@code %1$s}, {@code %2$s} and {@code %3$s}, not null.
  185.      * @return the formatted string, not null.
  186.      */
  187.     public String toString(final String format) {
  188.         return String.format(format, getLeft(), getMiddle(), getRight());
  189.     }

  190. }