From bdb17a7878f51a349f4eb98cc37b7a574ba8c8c4 Mon Sep 17 00:00:00 2001 From: Grzegorz Piwowarek Date: Mon, 14 Oct 2024 21:41:52 +0200 Subject: [PATCH] Add JavaDocs (#40) --- .../pivovarit/gatherers/MoreGatherers.java | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) diff --git a/src/main/java/com/pivovarit/gatherers/MoreGatherers.java b/src/main/java/com/pivovarit/gatherers/MoreGatherers.java index 23e4fd4..2557a56 100644 --- a/src/main/java/com/pivovarit/gatherers/MoreGatherers.java +++ b/src/main/java/com/pivovarit/gatherers/MoreGatherers.java @@ -13,66 +13,207 @@ public final class MoreGatherers { private MoreGatherers() { } + /** + * Creates a {@link Gatherer} that gathers the last {@code n} elements. + * + * @param the type of the input elements + * @param n the number of last elements to gather + * + * @return a {@link Gatherer} that collects the last {@code n} elements + */ public static Gatherer last(int n) { return new LastGatherer<>(n); } + /** + * Creates a {@link Gatherer} that gathers every {@code n}-th element. + * + * @param the type of the input elements + * @param n the interval at which elements are gathered + * + * @return a {@link Gatherer} that samples elements every {@code n}-th element + */ public static Gatherer sampling(int n) { return new SamplingGatherer<>(n); } + /** + * Creates a {@link Gatherer} that filters elements to ensure that only distinct elements + * remain, based on a key extracted by the given {@code keyExtractor}, keeping the last + * occurrence of each distinct key. + * + * @param the type of the input elements + * @param the type of the key extracted from the input elements + * @param keyExtractor the function used to extract the key for distinguishing elements + * + * @return a {@link Gatherer} that collects distinct elements by key, keeping the last occurrence + */ public static Gatherer distinctByKeepLast(Function keyExtractor) { return new DistinctByKeepLastGatherer<>(keyExtractor); } + /** + * Creates a {@link Gatherer} that filters elements to ensure that only distinct elements + * remain, based on a key extracted by the given {@code keyExtractor}, keeping the first + * occurrence of each distinct key. + * + * @param the type of the input elements + * @param the type of the key extracted from the input elements + * @param keyExtractor the function used to extract the key for distinguishing elements + * + * @return a {@link Gatherer} that collects distinct elements by key, keeping the first occurrence + */ public static Gatherer distinctBy(Function keyExtractor) { return new DistinctByGatherer<>(keyExtractor); } + /** + * Creates a {@link Gatherer} that gathers distinct consecutive elements. + * Elements are considered distinct if they are different from the previously gathered element. + * + * @param the type of the input elements + * + * @return a {@link Gatherer} that collects distinct consecutive elements + */ public static Gatherer distinctUntilChanged() { return distinctUntilChanged(Function.identity()); } + /** + * Creates a {@link Gatherer} that gathers distinct consecutive elements + * based on a key extracted by the given {@code keyExtractor}. + * Elements are considered distinct if the extracted key is different from the previous key. + * + * @param the type of the input elements + * @param the type of the key extracted from the input elements + * @param keyExtractor the function used to extract the key for distinguishing elements + * + * @return a {@link Gatherer} that collects distinct consecutive elements by key + */ public static Gatherer distinctUntilChanged(Function keyExtractor) { Objects.requireNonNull(keyExtractor, "keyExtractor can't be null"); return new DistinctUntilChangedGatherer<>(keyExtractor); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Stream} of type {@code T2}. The resulting pair is returned as a {@link Map.Entry}. + * + * @param the type of the first stream elements + * @param the type of the second stream elements + * @param other the other stream to zip with + * + * @return a {@link Gatherer} that pairs elements from the two streams + */ public static Gatherer> zip(Stream other) { Objects.requireNonNull(other, "other can't be null"); return zip(other.iterator()); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Stream} of type {@code T2}, and combines them using the provided {@code mapper}. + * + * @param the type of the first stream elements + * @param the type of the second stream elements + * @param the type of the result produced by the {@code mapper} + * @param other the other stream to zip with + * @param mapper the function that combines elements from both streams + * + * @return a {@link Gatherer} that pairs elements from the two streams using the {@code mapper} + */ public static Gatherer zip(Stream other, BiFunction mapper) { Objects.requireNonNull(other, "other can't be null"); Objects.requireNonNull(mapper, "mapper can't be null"); return zip(other.iterator(), mapper); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Iterable} of type {@code T2}. The resulting pair is returned as a {@link Map.Entry}. + * + * @param the type of the first iterable elements + * @param the type of the second iterable elements + * @param other the other iterable to zip with + * + * @return a {@link Gatherer} that pairs elements from the two iterables + */ public static Gatherer> zipWithIterable(Iterable other) { Objects.requireNonNull(other, "other can't be null"); return zip(other.iterator()); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Iterable} of type {@code T2}, and combines them using the provided {@code mapper}. + * + * @param the type of the first iterable elements + * @param the type of the second iterable elements + * @param the type of the result produced by the {@code mapper} + * @param other the other iterable to zip with + * @param mapper the function that combines elements from both iterables + * + * @return a {@link Gatherer} that pairs elements from the two iterables using the {@code mapper} + */ public static Gatherer zipWithIterable(Iterable other, BiFunction mapper) { Objects.requireNonNull(other, "other can't be null"); Objects.requireNonNull(mapper, "mapper can't be null"); return zip(other.iterator(), mapper); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Iterator} of type {@code T2}. The resulting pair is returned as a {@link Map.Entry}. + * + * @param the type of the first iterator elements + * @param the type of the second iterator elements + * @param iterator the iterator to zip with + * + * @return a {@link Gatherer} that pairs elements from the two iterators + */ public static Gatherer> zip(Iterator iterator) { Objects.requireNonNull(iterator, "iterator can't be null"); return zip(iterator, Map::entry); } + /** + * Creates a {@link Gatherer} that zips elements of type {@code T1} with elements from + * another {@link Iterator} of type {@code T2}, and combines them using the provided {@code mapper}. + * + * @param the type of the first iterator elements + * @param the type of the second iterator elements + * @param the type of the result produced by the {@code mapper} + * @param iterator the iterator to zip with + * @param mapper the function that combines elements from both iterators + * + * @return a {@link Gatherer} that pairs elements from the two iterators using the {@code mapper} + */ public static Gatherer zip(Iterator iterator, BiFunction mapper) { return new ZipIteratorGatherer<>(iterator, mapper); } + /** + * Creates a {@link Gatherer} that zips elements with their corresponding index, + * using the given {@code mapper} to produce the final result. + * + * @param the type of the input elements + * @param the type of the result produced by the {@code mapper} + * @param mapper the function that combines an index and an element to produce the result + * + * @return a {@link Gatherer} that pairs elements with their corresponding index using the {@code mapper} + */ public static Gatherer zipWithIndex(BiFunction mapper) { return new ZipWithIndexMappingGatherer<>(mapper); } + /** + * Creates a {@link Gatherer} that zips elements with their corresponding index, + * producing a {@link Map.Entry} where the key is the index and the value is the element. + * + * @param the type of the input elements + * + * @return a {@link Gatherer} that pairs elements with their corresponding index + */ public static Gatherer> zipWithIndex() { return new ZipWithIndexGatherer<>(); }