Merge release 1.0.0 into stable branchHEADstable

See the tag 'v1.0.0' or the changelog for more information about this
release.

1 files changed, 59 insertions, 43 deletions

diff --git a/src/main/java/sevenUnits/utils/NameSymbol.java b/src/main/java/sevenUnits/utils/NameSymbol.java
index 49c44fa..089978b 100644
--- a/src/main/java/sevenUnits/utils/NameSymbol.java
+++ b/src/main/java/sevenUnits/utils/NameSymbol.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2019 Adrien Hopkins
+ * Copyright (C) 2019, 2022, 2024, 2025 Adrien Hopkins
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Affero General Public License as published by
@@ -19,34 +19,35 @@ package sevenUnits.utils;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashSet;
-import java.util.Iterator;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 
 /**
  * A class that can be used to specify names and a symbol for a unit.
- * 
+ *
  * @author Adrien Hopkins
  * @since 2019-10-21
+ * @since v0.3.0
  */
 public final class NameSymbol {
+	/** The {@code NameSymbol} with all fields empty. */
 	public static final NameSymbol EMPTY = new NameSymbol(Optional.empty(),
 			Optional.empty(), new HashSet<>());
 
 	/**
 	 * Creates a {@code NameSymbol}, ensuring that if primaryName is null and
 	 * otherNames is not empty, one name is moved from otherNames to primaryName
-	 * 
+	 *
 	 * Ensure that otherNames is not a copy of the inputted argument.
 	 */
-	private static final NameSymbol create(final String name,
-			final String symbol, final Set<String> otherNames) {
+	private static NameSymbol create(final String name, final String symbol,
+			final Set<String> otherNames) {
 		final Optional<String> primaryName;
 
 		if (name == null && !otherNames.isEmpty()) {
 			// get primary name and remove it from savedNames
-			final Iterator<String> it = otherNames.iterator();
+			final var it = otherNames.iterator();
 			assert it.hasNext();
 			primaryName = Optional.of(it.next());
 			otherNames.remove(primaryName.get());
@@ -61,14 +62,15 @@ public final class NameSymbol {
 	/**
 	 * Gets a {@code NameSymbol} with a primary name, a symbol and no other
 	 * names.
-	 * 
+	 *
 	 * @param name   name to use
 	 * @param symbol symbol to use
 	 * @return NameSymbol instance
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 * @throws NullPointerException if name or symbol is null
 	 */
-	public static final NameSymbol of(final String name, final String symbol) {
+	public static NameSymbol of(final String name, final String symbol) {
 		return new NameSymbol(Optional.of(name), Optional.of(symbol),
 				new HashSet<>());
 	}
@@ -76,15 +78,16 @@ public final class NameSymbol {
 	/**
 	 * Gets a {@code NameSymbol} with a primary name, a symbol and additional
 	 * names.
-	 * 
+	 *
 	 * @param name       name to use
 	 * @param symbol     symbol to use
 	 * @param otherNames other names to use
 	 * @return NameSymbol instance
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 * @throws NullPointerException if any argument is null
 	 */
-	public static final NameSymbol of(final String name, final String symbol,
+	public static NameSymbol of(final String name, final String symbol,
 			final Set<String> otherNames) {
 		return new NameSymbol(Optional.of(name), Optional.of(symbol),
 				new HashSet<>(Objects.requireNonNull(otherNames,
@@ -94,12 +97,13 @@ public final class NameSymbol {
 	/**
 	 * h * Gets a {@code NameSymbol} with a primary name, a symbol and additional
 	 * names.
-	 * 
+	 *
 	 * @param name       name to use
 	 * @param symbol     symbol to use
 	 * @param otherNames other names to use
 	 * @return NameSymbol instance
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 * @throws NullPointerException if any argument is null
 	 */
 	public static final NameSymbol of(final String name, final String symbol,
@@ -112,13 +116,14 @@ public final class NameSymbol {
 	/**
 	 * Gets a {@code NameSymbol} with a primary name, no symbol, and no other
 	 * names.
-	 * 
+	 *
 	 * @param name name to use
 	 * @return NameSymbol instance
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 * @throws NullPointerException if name is null
 	 */
-	public static final NameSymbol ofName(final String name) {
+	public static NameSymbol ofName(final String name) {
 		return new NameSymbol(Optional.of(name), Optional.empty(),
 				new HashSet<>());
 	}
@@ -133,15 +138,16 @@ public final class NameSymbol {
 	 * If {@code name} is null and {@code otherNames} is not empty, a primary
 	 * name will be picked from {@code otherNames}. This name will not appear in
 	 * getOtherNames().
-	 * 
+	 *
 	 * @param name       name to use
 	 * @param symbol     symbol to use
 	 * @param otherNames other names to use
 	 * @return NameSymbol instance
 	 * @since 2019-11-26
+	 * @since v0.3.0
 	 */
-	public static final NameSymbol ofNullable(final String name,
-			final String symbol, final Set<String> otherNames) {
+	public static NameSymbol ofNullable(final String name, final String symbol,
+			final Set<String> otherNames) {
 		return NameSymbol.create(name, symbol,
 				otherNames == null ? new HashSet<>() : new HashSet<>(otherNames));
 	}
@@ -156,12 +162,13 @@ public final class NameSymbol {
 	 * If {@code name} is null and {@code otherNames} is not empty, a primary
 	 * name will be picked from {@code otherNames}. This name will not appear in
 	 * getOtherNames().
-	 * 
+	 *
 	 * @param name       name to use
 	 * @param symbol     symbol to use
 	 * @param otherNames other names to use
 	 * @return NameSymbol instance
 	 * @since 2019-11-26
+	 * @since v0.3.0
 	 */
 	public static final NameSymbol ofNullable(final String name,
 			final String symbol, final String... otherNames) {
@@ -171,13 +178,14 @@ public final class NameSymbol {
 
 	/**
 	 * Gets a {@code NameSymbol} with a symbol and no names.
-	 * 
+	 *
 	 * @param symbol symbol to use
 	 * @return NameSymbol instance
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 * @throws NullPointerException if symbol is null
 	 */
-	public static final NameSymbol ofSymbol(final String symbol) {
+	public static NameSymbol ofSymbol(final String symbol) {
 		return new NameSymbol(Optional.empty(), Optional.of(symbol),
 				new HashSet<>());
 	}
@@ -189,21 +197,26 @@ public final class NameSymbol {
 
 	/**
 	 * Creates the {@code NameSymbol}.
-	 * 
+	 *
 	 * @param primaryName primary name of unit
 	 * @param symbol      symbol used to represent unit
 	 * @param otherNames  other names and/or spellings, should be a mutable copy
 	 *                    of the argument
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 */
-	private NameSymbol(final Optional<String> primaryName,
-			final Optional<String> symbol, final Set<String> otherNames) {
+	NameSymbol(final Optional<String> primaryName, final Optional<String> symbol,
+			final Set<String> otherNames) {
 		this.primaryName = primaryName;
 		this.symbol = symbol;
-		otherNames.remove(null);
-		this.otherNames = Collections.unmodifiableSet(otherNames);
+		if (otherNames != null) {
+			otherNames.remove(null);
+			this.otherNames = Collections.unmodifiableSet(otherNames);
+		} else {
+			this.otherNames = Set.of();
+		}
 
-		if (this.primaryName.isEmpty()) {
+		if (this.primaryName == null || this.primaryName.isEmpty()) {
 			assert this.otherNames.isEmpty();
 		}
 	}
@@ -214,7 +227,7 @@ public final class NameSymbol {
 			return true;
 		if (!(obj instanceof NameSymbol))
 			return false;
-		final NameSymbol other = (NameSymbol) obj;
+		final var other = (NameSymbol) obj;
 		if (this.otherNames == null) {
 			if (other.otherNames != null)
 				return false;
@@ -236,31 +249,34 @@ public final class NameSymbol {
 	/**
 	 * @return otherNames
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 */
-	public final Set<String> getOtherNames() {
+	public Set<String> getOtherNames() {
 		return this.otherNames;
 	}
 
 	/**
 	 * @return primaryName
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 */
-	public final Optional<String> getPrimaryName() {
+	public Optional<String> getPrimaryName() {
 		return this.primaryName;
 	}
 
 	/**
 	 * @return symbol
 	 * @since 2019-10-21
+	 * @since v0.3.0
 	 */
-	public final Optional<String> getSymbol() {
+	public Optional<String> getSymbol() {
 		return this.symbol;
 	}
 
 	@Override
 	public int hashCode() {
-		final int prime = 31;
-		int result = 1;
+		final var prime = 31;
+		var result = 1;
 		result = prime * result
 				+ (this.otherNames == null ? 0 : this.otherNames.hashCode());
 		result = prime * result
@@ -270,10 +286,8 @@ public final class NameSymbol {
 		return result;
 	}
 
-	/**
-	 * @return true iff this {@code NameSymbol} contains no names or symbols.
-	 */
-	public final boolean isEmpty() {
+	/** @return true iff this {@code NameSymbol} contains no names or symbols. */
+	public boolean isEmpty() {
 		// if primaryName is empty, otherNames must also be empty
 		return this.primaryName.isEmpty() && this.symbol.isEmpty();
 	}
@@ -282,11 +296,10 @@ public final class NameSymbol {
 	public String toString() {
 		if (this.isEmpty())
 			return "NameSymbol.EMPTY";
-		else if (this.primaryName.isPresent() && this.symbol.isPresent())
+		if (this.primaryName.isPresent() && this.symbol.isPresent())
 			return this.primaryName.orElseThrow() + " ("
 					+ this.symbol.orElseThrow() + ")";
-		else
-			return this.primaryName.orElseGet(this.symbol::orElseThrow);
+		return this.primaryName.orElseGet(this.symbol::orElseThrow);
 	}
 
 	/**
@@ -294,16 +307,19 @@ public final class NameSymbol {
 	 * extra name. If this {@code NameSymbol} has a primary name, the provided
 	 * name will become an other name, otherwise it will become the primary name.
 	 *
-	 * @since v0.4.0
+	 * @param name additional name to add
+	 * @return copy of this NameSymbol with the additional name
+	 *
 	 * @since 2022-04-19
+	 * @since v0.4.0
 	 */
-	public final NameSymbol withExtraName(String name) {
+	public NameSymbol withExtraName(String name) {
 		if (this.primaryName.isPresent()) {
 			final var otherNames = new HashSet<>(this.otherNames);
 			otherNames.add(name);
 			return NameSymbol.ofNullable(this.primaryName.orElse(null),
 					this.symbol.orElse(null), otherNames);
-		} else
-			return NameSymbol.ofNullable(name, this.symbol.orElse(null));
+		}
+		return NameSymbol.ofNullable(name, this.symbol.orElse(null));
 	}
 }
\ No newline at end of file