Harmonize Options API

src/main/java/net/datafaker/idnumbers/AmericanIdNumber.java

@@ -48,6 +48,6 @@ public PersonIdNumber generateValid(BaseProviders faker, IdNumber.IdNumberReques
 
     @Override
     public String generateInvalid(BaseProviders faker) {
-        return faker.regexify(faker.options().nextElement(INVALID_SSNS));
+        return faker.regexify(faker.options().option(INVALID_SSNS));
     }
 }

src/main/java/net/datafaker/providers/base/Company.java

@@ -36,7 +36,7 @@ public String profession() {
     }
 
     public String buzzword() {
-        return faker.options().nextElement(allBuzzwords.get());
+        return faker.options().option(allBuzzwords.get());
     }
 
     private List<String> loadBuzzwords() {
@@ -93,7 +93,7 @@ private String domainSuffix() {
 
     private String joinSampleOfEachList(List<List<String>> listOfLists) {
         return listOfLists.stream()
-            .map(list -> faker.options().nextElement(list))
+            .map(list -> faker.options().option(list))
             .collect(joining(" "));
     }
 }

src/main/java/net/datafaker/providers/base/Finance.java

@@ -136,7 +136,7 @@ public String bic() {
      */
     public String iban() {
         List<String> countryCodes = new ArrayList<>(countryCodeToBasicBankAccountNumberPattern.keySet());
-        String countryCode = faker.options().nextElement(countryCodes);
+        String countryCode = faker.options().option(countryCodes);
         return iban(countryCode);
     }
 

src/main/java/net/datafaker/providers/base/Http.java

@@ -104,7 +104,7 @@ public String contentType() {
 
     /** Returns a random browser user agent string from any supported browser. */
     public String userAgent() {
-        Browser browser = faker.options().nextElement(Browser.values());
+        Browser browser = faker.options().option(Browser.values());
         return resolve("http.user_agent." + browser.key);
     }
 
@@ -143,7 +143,7 @@ public String encoding() {
      * @see #responseBody(String)
      */
     public String responseBody() {
-        return resolve("http.response_body." + faker.options().nextElement(TEXT_BODY_TYPES));
+        return resolve("http.response_body." + faker.options().option(TEXT_BODY_TYPES));
     }
 
     /**
@@ -181,7 +181,7 @@ private static String contentTypeToBodyKey(String contentType) {
     }
 
     private String randomStatusEntry() {
-        String category = faker.options().nextElement(ALL_STATUS_CATEGORIES);
+        String category = faker.options().option(ALL_STATUS_CATEGORIES);
         return resolve("http.status_code." + category);
     }
 

src/main/java/net/datafaker/providers/base/Internet.java

@@ -202,7 +202,7 @@ public String url() {
      * @since 2.0.0
      */
     public String url(boolean schemeChoice, boolean portChoice, boolean pathChoice, boolean fileChoice, boolean paramsChoice, boolean anchorChoice) {
-        String scheme = schemeChoice ? faker.options().nextElement(HTTP_SCHEMES) : "https://";
+        String scheme = schemeChoice ? faker.options().option(HTTP_SCHEMES) : "https://";
         String port = portChoice ? (":" + port()) : "";
         String path = pathChoice ? ("/" + slug(faker.lorem().words(2), "/")) : "/";
         String file = fileChoice ? faker.lorem().words(1).get(0) : "";

src/main/java/net/datafaker/providers/base/Options.java

@@ -17,11 +17,11 @@ protected Options(BaseProviders faker) {
     }
 
     /**
-     * Returns a random element from an varargs.
+     * Returns a random element from an array or varargs.
      *
      * @param options The varargs to take a random element from.
-     * @param <E>     The type of the elements in the varargs.
-     * @return A randomly selected element from the varargs.
+     * @param <E>     The type of the elements in the array.
+     * @return A randomly selected element from the array.
      */
     @SafeVarargs
     public final <E> E option(E... options) {
@@ -71,7 +71,7 @@ public final byte option(byte[] options) {
      * If size is zero then an empty subset will be returned.
      * If size is larger than a unique set from options then all options will be returned.
      */
-    @SuppressWarnings("unchecked")
+    @SafeVarargs
     public final <E> Set<E> subset(int size, E... options) {
         if (size < 0) {
             throw new IllegalArgumentException("size should be not negative: " + size);
@@ -154,9 +154,11 @@ public <E extends Enum<E>> E option(Class<E> enumeration) {
      * @param array The array to take a random element from.
      * @param <E>   The type of the elements in the array.
      * @return A randomly selected element from the array.
+     * @deprecated Use {@link #option(Object[]) option(E...)}
      */
+    @Deprecated(since = "3.0.0", forRemoval = true)
     public <E> E nextElement(E[] array) {
-        return array[faker.random().nextInt(array.length)];
+        return option(array);
     }
 
     /**
@@ -165,8 +167,21 @@ public <E> E nextElement(E[] array) {
      * @param list The list to take a random element from.
      * @param <E>  The type of the elements in the list.
      * @return A randomly selected element from the list.
+     * @deprecated Use {@link #option(List)}
      */
+    @Deprecated(since = "3.0.0", forRemoval = true)
     public <E> E nextElement(List<E> list) {
+        return option(list);
+    }
+
+    /**
+     * Returns a random element from a list.
+     *
+     * @param list The list to take a random element from.
+     * @param <E>  The type of the elements in the list.
+     * @return A randomly selected element from the list.
+     */
+    public <E> E option(List<E> list) {
         return list.get(faker.random().nextInt(list.size()));
     }
 
@@ -179,7 +194,7 @@ public <E> E nextElement(List<E> list) {
      * @throws IllegalArgumentException if the collection is empty.
      * @since 3.0.0
      */
-    public <E> E nextElement(Collection<E> collection) throws IllegalArgumentException {
+    public <E> E option(Collection<E> collection) {
         return collection.stream()
             .skip(faker.random().nextInt(collection.size()))
             .findFirst().orElseThrow(() -> new IllegalArgumentException("Collection is empty"));

src/test/java/net/datafaker/providers/base/OptionsTest.java

@@ -104,6 +104,8 @@ void testOptionWithEnum() {
         assertThat(opt.option(Day.class)).isIn((Object[]) Day.values());
     }
 
+    @SuppressWarnings("removal")
+    @Deprecated
     @Test
     void testNextArrayElement() {
         Integer[] array = {1, 2, 3, 5, 8, 13, 21};
@@ -113,6 +115,8 @@ void testNextArrayElement() {
         }
     }
 
+    @SuppressWarnings("removal")
+    @Deprecated
     @Test
     void testNextListElement() {
         List<Integer> list = List.of(1, 2, 3, 5, 8, 13, 21);
@@ -122,17 +126,25 @@ void testNextListElement() {
     }
 
     @Test
-    void testNextCollectionElement() {
+    void testOptionWithList() {
+        List<Integer> list = List.of(1, 2, 3, 5, 8, 13, 21);
+        for (int i = 1; i < 10; i++) {
+            assertThat(opt.option(list)).isIn(list);
+        }
+    }
+
+    @Test
+    void testOptionWithCollection() {
         Collection<Integer> collection = Set.of(1, 2, 3, 5, 8, 13, 21);
         for (int i = 1; i < 10; i++) {
-            assertThat(opt.nextElement(collection)).isIn(collection);
+            assertThat(opt.option(collection)).isIn(collection);
         }
     }
 
     @Test
-    void testNextCollectionElementEmpty() {
+    void testOptionWithEmptyCollection() {
         Collection<Integer> collection = Set.of();
-        assertThatThrownBy(() -> opt.nextElement(collection))
+        assertThatThrownBy(() -> opt.option(collection))
             .isInstanceOf(IllegalArgumentException.class);
     }