Addition.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.  *      http://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.numbers.core;

  18. /**
  19.  * Addition.
  20.  *
  21.  * @param <T> Type of elements.
  22.  */
  23. public interface Addition<T> {
  24.     /**
  25.      * Binary addition.
  26.      *
  27.      * @param a Element.
  28.      * @return {@code this + a}.
  29.      */
  30.     T add(T a);

  31.     /**
  32.      * Identity element.
  33.      *
  34.      * @return the field element such that for all {@code a},
  35.      * {@code zero().add(a).equals(a)} is {@code true}.
  36.      */
  37.     T zero();

  38.     /**
  39.      * Additive inverse.
  40.      *
  41.      * @return {@code -this}.
  42.      */
  43.     T negate();

  44.     /**
  45.      * Check if this is a neutral element of addition, i.e. {@code this.add(a)} returns
  46.      * {@code a} or an element representing the same value as {@code a}.
  47.      *
  48.      * <p>The default implementation calls {@link Object#equals(Object) equals(zero())}.
  49.      * Implementations may want to employ more a efficient method. This may even
  50.      * be required if an implementation has multiple representations of {@code zero} and its
  51.      * {@code equals} method differentiates between them.
  52.      *
  53.      * @return {@code true} if {@code this} is a neutral element of addition.
  54.      * @see #zero()
  55.      * @since 1.2
  56.      */
  57.     default boolean isZero() {
  58.         return this.equals(zero());
  59.     }
  60. }