Skip to content

Commit

Permalink
Document behavior of copy vs regular constructors
Browse files Browse the repository at this point in the history
  • Loading branch information
runeflobakk committed Jun 18, 2021
1 parent e7a1945 commit 52e306d
Showing 1 changed file with 14 additions and 0 deletions.
14 changes: 14 additions & 0 deletions src/main/java/no/digipost/collection/NonEmptyList.java
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,20 @@
* take care to ensure that instances will <em>never</em> in any
* circumstance be allowed to be empty.
*
* @implNote In general, constructing a {@code NonEmptyList} from another
* mutable container source (e.g. an existing list or array), and then changing the
* contents of the source, results in undefined behavior of the non-empty list. The
* only guarantee is that the non-empty list will <em>never</em> be empty, but the
* behavior when mutating a list on which the non-empty list is based on should not be
* relied on.
* <p>
* If you need to construct non-empty lists based on another container you
* need to further mutate, consider using one of the {@link #copyOf(List) copyOf}
* constructors, which will copy the given references so that any subsequent changes to the
* to the given source container will not be reflected in the created non-empty list. (As usual,
* this is a shallow copy, meaning that the instances themselves can of course be mutated by anything.)
*
*
* @param <E> the type of elements in this list
*/
public interface NonEmptyList<E> extends List<E> {
Expand Down

0 comments on commit 52e306d

Please sign in to comment.