doc improvements and cleanups

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-** Please create PR against the develop branch **
+** Please create PR against the main branch **
 
 This PR relates to Issue: #
 
@@ -10,7 +10,7 @@ This PR relates to Issue: #
 
 ## Performance
 
-In order to prevent a performance degradation please run a benchmark
+To prevent a performance degradation, please run a benchmark
 using `./gradlew jmh` before and after your change and show the results.
 
-<!-- Outputs of build/reports/jmh/results.txt -->
+<!-- Outputs of ./lib/build/results/jmh/results.txt -->

README.md

@@ -18,5 +18,5 @@
 ------
 
 <p align="center">
-  Visit our website at <a href="https://fastcsv.org">https://fastcsv.org</a>
+  Visit our website at <a href="https://fastcsv.org">fastcsv.org</a>
 </p>

example/src/main/java/example/ExampleCsvReaderWithCustomCallbackHandler.java

@@ -22,8 +22,9 @@
  * Example for implementing a custom callback handler.
  * <p>
  * You should only go this route if you need to squeeze out every bit of performance and I/O or post-processing is not
- * the bottleneck. The standard implementation ({@link de.siegmar.fastcsv.reader.CsvRecordHandler}) is already
- * very fast and should be sufficient for most use cases.
+ * a bottleneck.
+ * The standard implementation ({@link de.siegmar.fastcsv.reader.CsvRecordHandler}) is already very fast and should be
+ * sufficient for most use cases.
  * <p>
  * A comparison with 1 bn records (86 GiB) has shown the following results:
  * <table>
@@ -153,7 +154,7 @@ private static Path produceLargeFakeDataset() throws IOException {
                     Long.toString(timestamp),
                     Double.toString(latitude),
                     Double.toString(longitude),
-                    "Celcius",
+                    "Celsius",
                     Double.toString(temperature));
             }
         }

example/src/main/java/example/ExampleIndexedCsvReader.java

@@ -106,7 +106,7 @@ private static void statusMonitor(final Path file) throws IOException {
 
         final var statusListener = new CollectingStatusListener();
 
-        // Using the StatusListener we can monitor the indexing process in background
+        // Using the StatusListener, we can monitor the indexing process in the background
         final var executor = Executors.newSingleThreadScheduledExecutor();
         executor.scheduleAtFixedRate(
             () -> {

lib/build.gradle.kts

@@ -147,7 +147,7 @@ publishing {
             pom {
                 name = "FastCSV"
                 description = "Lightning-fast, dependency-free CSV library that conforms to RFC standards."
-                url = "https://github.com/osiegmar/FastCSV"
+                url = "https://fastcsv.org"
                 licenses {
                     license {
                         name = "MIT License"

lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java

@@ -83,7 +83,7 @@ public static CsvReaderBuilder builder() {
      * Remember to close the returned iterator when you're done.
      * Alternatively, use {@link #stream()}.
      * <br>
-     * This method is idempotent.
+     * This method is idempotent and can be called multiple times.
      *
      * @return an iterator over the CSV records.
      * @throws UncheckedIOException if an I/O error occurs.
@@ -102,7 +102,7 @@ public CloseableIterator<T> iterator() {
      * Remember to invoke {@link #close()} when you're done.
      * Alternatively, use {@link #stream()}.
      * <br>
-     * This method is idempotent.
+     * This method is idempotent and can be called multiple times.
      *
      * @return a spliterator over the CSV records.
      * @throws UncheckedIOException if an I/O error occurs.
@@ -115,12 +115,15 @@ public Spliterator<T> spliterator() {
     }
 
     /**
-     * Returns a sequential {@code Stream} with this reader as its source.
+     * Returns a new sequential {@code Stream} with this reader as its source.
      * <p>
      * The returned stream is not thread-safe.
      * Remember to close the returned stream when you're done.
+     * Closing the stream will also close this reader.
      * <br>
-     * This method is idempotent.
+     * This method can be called multiple times, although it creates a new stream each time.
+     * <br>
+     * The stream is not reusable after it has been closed.
      *
      * @return a sequential {@code Stream} over the CSV records.
      * @throws UncheckedIOException if an I/O error occurs.
@@ -291,7 +294,7 @@ public void close() throws IOException {
 
     /**
      * This builder is used to create configured instances of {@link CsvReader}. The default
-     * configuration of this class complies with RFC 4180:
+     * configuration of this class adheres with RFC 4180:
      * <ul>
      *     <li>Field separator: {@code ,} (comma)</li>
      *     <li>Quote character: {@code "} (double quotes)</li>

lib/src/main/java/de/siegmar/fastcsv/reader/CsvRecord.java

@@ -110,11 +110,11 @@ public List<String> getFields() {
     }
 
     /**
-     * Obtains the count of fields in this record.
+     * Gets the count of fields in this record.
      * <p>
      * The minimum number of fields is 1, even if the line was empty.
      *
-     * @return the number of fields of this record
+     * @return the number of fields in this record
      * @see CsvReader.CsvReaderBuilder#ignoreDifferentFieldCount(boolean)
      */
     public int getFieldCount() {

lib/src/main/java/de/siegmar/fastcsv/reader/FieldModifier.java

@@ -14,7 +14,7 @@ public interface FieldModifier {
 
     /**
      * Gets called for every single field (that is not a comment).
-     * Default implementation returns the field as is.
+     * The Default implementation returns the field as is.
      *
      * @param startingLineNumber the starting line number (starting with 1)
      * @param fieldIdx           the field index (starting with 0)
@@ -28,7 +28,7 @@ default String modify(final long startingLineNumber, final int fieldIdx, final b
 
     /**
      * Gets called for every comment.
-     * Default implementation returns the field as is.
+     * The Default implementation returns the field as is.
      *
      * @param startingLineNumber the starting line number (starting with 1)
      * @param field              the field value (comment), never {@code null}

lib/src/main/java/de/siegmar/fastcsv/reader/FieldModifiers.java

@@ -44,7 +44,7 @@ private FieldModifiers() {
      * Comments are not modified.
      *
      * @param locale use the case transformation rules for this locale
-     * @return a new field modifier that converts the input to lower case.
+     * @return a new field modifier that converts the input to lower-case.
      */
     public static FieldModifier lower(final Locale locale) {
         return (SimpleFieldModifier) field -> field.toLowerCase(locale);
@@ -55,7 +55,7 @@ public static FieldModifier lower(final Locale locale) {
      * Comments are not modified.
      *
      * @param locale use the case transformation rules for this locale
-     * @return a new field modifier that converts the input to upper case.
+     * @return a new field modifier that converts the input to upper-case.
      */
     public static FieldModifier upper(final Locale locale) {
         return (SimpleFieldModifier) field -> field.toUpperCase(locale);

lib/src/main/java/de/siegmar/fastcsv/reader/IndexedCsvReader.java

@@ -184,7 +184,7 @@ public static IndexedCsvReaderBuilder builder() {
     }
 
     /**
-     * Obtain the index used for accessing the CSV file.
+     * Get the index used for accessing the CSV file.
      * That index is either a freshly built index or the index that has been
      * passed via {@link IndexedCsvReaderBuilder#index(CsvIndex)}.
      *
@@ -248,7 +248,7 @@ public String toString() {
 
     /**
      * This builder is used to create configured instances of {@link IndexedCsvReader}. The default
-     * configuration of this class complies with RFC 4180.
+     * configuration of this class adheres with RFC 4180.
      * <p>
      * The line delimiter (line-feed, carriage-return or the combination of both) is detected
      * automatically and thus not configurable.

lib/src/main/java/de/siegmar/fastcsv/reader/NamedCsvRecord.java

@@ -80,7 +80,7 @@ public String getField(final String name) {
         return fields[fieldIdx];
     }
 
-    // Finds the index of the first occurrence of the given header name (case-sensitive); returns -1 if not found
+    // Finds the index for the first occurrence of the given header name (case-sensitive); returns -1 if not found
     private int findHeaderIndex(final String name) {
         for (int i = 0; i < header.length; i++) {
             if (name.equals(header[i])) {
@@ -154,7 +154,7 @@ public Map<String, String> getFieldsAsMap() {
     }
 
     /**
-     * Constructs an unordered map, associating header names with an ordered list of corresponding field values of
+     * Constructs an unordered map, associating header names with an ordered list of corresponding field values in
      * this record.
      * <p>
      * The constructed map will only contain entries for fields that have a key and a value. No map entry will have a

lib/src/main/java/de/siegmar/fastcsv/writer/CsvWriter.java

@@ -83,7 +83,7 @@ public static CsvWriterBuilder builder() {
      * @param values the fields to write ({@code null} values are handled as empty strings, if
      *               not configured otherwise ({@link QuoteStrategies#EMPTY})).
      * @return This CsvWriter.
-     * @throws UncheckedIOException if a write error occurs
+     * @throws UncheckedIOException if a write-error occurs
      * @throws IllegalStateException if a record is already started (by calling {@link #writeRecord()}) and not ended
      * @see #writeRecord(String...)
      */
@@ -106,7 +106,7 @@ public CsvWriter writeRecord(final Iterable<String> values) {
      * @param values the fields to write ({@code null} values are handled as empty strings, if
      *               not configured otherwise ({@link QuoteStrategies#EMPTY}))
      * @return This CsvWriter.
-     * @throws UncheckedIOException if a write error occurs
+     * @throws UncheckedIOException if a write-error occurs
      * @throws IllegalStateException if a record is already started (by calling {@link #writeRecord()}) and not ended
      * @see #writeRecord(Iterable)
      */
@@ -245,7 +245,7 @@ private static void writeEscaped(final Writer w, final String value, final char
      *                will be written, terminated with the line break character configured by
      *                {@link CsvWriterBuilder#lineDelimiter(LineDelimiter)}.
      * @return This CsvWriter.
-     * @throws UncheckedIOException if a write error occurs
+     * @throws UncheckedIOException if a write-error occurs
      * @throws IllegalStateException if a record is already started (by calling {@link #writeRecord()}) and not ended
      */
     public CsvWriter writeComment(final String comment) {
@@ -321,7 +321,7 @@ public String toString() {
 
     /**
      * This builder is used to create configured instances of {@link CsvWriter}. The default
-     * configuration of this class complies with RFC 4180.
+     * configuration of this class adheres with RFC 4180.
      * <ul>
      *     <li>field separator: {@code ,} (comma)</li>
      *     <li>quote character: {@code "} (double quote)</li>
@@ -447,7 +447,7 @@ public CsvWriter build(final Writer writer) {
          * @param openOptions options specifying how the file is opened.
          *                    See {@link Files#newOutputStream(Path, OpenOption...)} for defaults.
          * @return a new CsvWriter instance - never {@code null}. Remember to close it!
-         * @throws IOException          if a write error occurs
+         * @throws IOException          if a write-error occurs
          * @throws NullPointerException if file or charset is {@code null}
          */
         public CsvWriter build(final Path file, final OpenOption... openOptions)
@@ -463,7 +463,7 @@ public CsvWriter build(final Path file, final OpenOption... openOptions)
          * @param openOptions options specifying how the file is opened.
          *                    See {@link Files#newOutputStream(Path, OpenOption...)} for defaults.
          * @return a new CsvWriter instance - never {@code null}. Remember to close it!
-         * @throws IOException          if a write error occurs
+         * @throws IOException          if a write-error occurs
          * @throws NullPointerException if file or charset is {@code null}
          */
         public CsvWriter build(final Path file, final Charset charset,
@@ -583,7 +583,7 @@ private CsvWriterRecord() {
          * Writes a field to the current record.
          * @param value the field value
          * @return this CsvWriterRecord instance
-         * @throws UncheckedIOException if a write error occurs
+         * @throws UncheckedIOException if a write-error occurs
          */
         public CsvWriterRecord writeField(final String value) {
             try {
@@ -597,7 +597,7 @@ public CsvWriterRecord writeField(final String value) {
         /**
          * Ends the current record.
          * @return the enclosing CsvWriter instance
-         * @throws UncheckedIOException if a write error occurs
+         * @throws UncheckedIOException if a write-error occurs
          */
         public CsvWriter endRecord() {
             openRecordWriter = false;