LineIterator (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io

## Class LineIterator

- java.lang.Object
- - org.apache.commons.io.LineIterator

- All Implemented Interfaces:
    java.util.Iterator<java.lang.String>

      public class LineIterator
      extends java.lang.Object
      implements java.util.Iterator<java.lang.String>

  An Iterator over the lines in a `Reader`.

  `LineIterator` holds a reference to an open `Reader`. When you have finished with the iterator you should close the reader to free internal resources. This can be done by closing the reader directly, or by calling the `close()` or `closeQuietly(LineIterator)` method on the iterator.

  The recommended usage pattern is:

       LineIterator it = FileUtils.lineIterator(file, "UTF-8");
       try {
         while (it.hasNext()) {
           String line = it.nextLine();
           // do something with line
         }
       } finally {
         it.close();
       }

  Since:
    1.2
  Version:
    $Id: LineIterator.java 1471767 2013-04-24 23:24:19Z sebb $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.io.BufferedReader` | `bufferedReader` The reader that is being read.
    `private java.lang.String` | `cachedLine` The current line.
    `private boolean` | `finished` A flag indicating if the iterator has been fully read.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LineIterator(java.io.Reader reader)` Constructs an iterator of the lines for a `Reader`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the underlying `Reader` quietly.
    `static void` | `closeQuietly(LineIterator iterator)` Closes the iterator, handling null and ignoring exceptions.
    `boolean` | `hasNext()` Indicates whether the `Reader` has more lines.
    `protected boolean` | `isValidLine(java.lang.String line)` Overridable method to validate each line that is returned.
    `java.lang.String` | `next()` Returns the next line in the wrapped `Reader`.
    `java.lang.String` | `nextLine()` Returns the next line in the wrapped `Reader`.
    `void` | `remove()` Unsupported.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### bufferedReader

          private final java.io.BufferedReader bufferedReader

      The reader that is being read.

    - #### cachedLine

          private java.lang.String cachedLine

      The current line.

    - #### finished

          private boolean finished

      A flag indicating if the iterator has been fully read.

  - ### Constructor Detail

    - #### LineIterator

          public LineIterator(java.io.Reader reader)
                       throws java.lang.IllegalArgumentException

      Constructs an iterator of the lines for a `Reader`.
      Parameters:
        `reader` - the `Reader` to read from, not null
      Throws:
        `java.lang.IllegalArgumentException` - if the reader is null

  - ### Method Detail

    - #### hasNext

          public boolean hasNext()

      Indicates whether the `Reader` has more lines. If there is an `IOException` then `close()` will be called on this instance.
      Specified by:
        `hasNext` in interface `java.util.Iterator<java.lang.String>`
      Returns:
        `true` if the Reader has more lines
      Throws:
        `java.lang.IllegalStateException` - if an IO exception occurs

    - #### isValidLine

          protected boolean isValidLine(java.lang.String line)

      Overridable method to validate each line that is returned. This implementation always returns true.
      Parameters:
        `line` - the line that is to be validated
      Returns:
        true if valid, false to remove from the iterator

    - #### next

          public java.lang.String next()

      Returns the next line in the wrapped `Reader`.
      Specified by:
        `next` in interface `java.util.Iterator<java.lang.String>`
      Returns:
        the next line from the input
      Throws:
        `java.util.NoSuchElementException` - if there is no line to return

    - #### nextLine

          public java.lang.String nextLine()

      Returns the next line in the wrapped `Reader`.
      Returns:
        the next line from the input
      Throws:
        `java.util.NoSuchElementException` - if there is no line to return

    - #### close

          public void close()

      Closes the underlying `Reader` quietly. This method is useful if you only want to process the first few lines of a larger file. If you do not close the iterator then the `Reader` remains open. This method can safely be called multiple times.

    - #### remove

          public void remove()

      Unsupported.
      Specified by:
        `remove` in interface `java.util.Iterator<java.lang.String>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### closeQuietly

          public static void closeQuietly(LineIterator iterator)

      Closes the iterator, handling null and ignoring exceptions.
      Parameters:
        `iterator` - the iterator to close

Copyright (c) 2002-2016 Apache Software Foundation