~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~ Copyright 2007 Kasper B. Graversen
~~ 
~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~ 
~~     http://www.apache.org/licenses/LICENSE-2.0
~~ 
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                                    -------------
                                    Release notes
                                    -------------

Release notes

* 2.4.0

  <10/2015>
  
  Some long overdue features and bug fixes, plus some exciting new features from our new contributors.
  
  <<New features>>
  
    * {{{https://github.com/super-csv/super-csv/issues/3}3}} - New <<<maxLinesPerRow>>> preference
    
    * {{{https://github.com/super-csv/super-csv/issues/6}6}} - New <<<CsvResultSetWriter>>> for writing JDBC result sets
    
    * {{{https://github.com/super-csv/super-csv/issues/53}53}} - Cell Processors for Java 8 time related classes: <<<Duration>>>, <<<LocalDate>>>, <<<LocalDateTime>>>, etc.

    * {{{https://github.com/super-csv/super-csv/issues/71}71}} - Improve write performance in multi-threaded environment. Added new <<<AbstractCsvWriter>>> constructor which allows to define whether given writer should be wrapped by <<<BufferedWriter>>> class or not.

  <<Bug fixes>>
    
    * {{{https://github.com/super-csv/super-csv/issues/33}33}} - Fixed misleading Exception for a CSV file with mismatched quotes
    
    * {{{https://github.com/super-csv/super-csv/issues/42}42}} - <<<CsvContext>>> is no longer being reset when exceptions are ignored

  <<General enhancements>>
  
    * {{{https://github.com/super-csv/super-csv/issues/32}32}} - <<<CsvPreference.getQuoteChar()>>> now returns a <<<char>>> instead of an <<<int>>>

    * {{{https://github.com/super-csv/super-csv/pull/66}66}} - <<<CellProcessor.execute(final Object value, final CsvContext context)>>> now returns generic <<<T>>> instead of an <<<Object>>>

  <<Minor changes>>

    * {{{https://github.com/super-csv/super-csv/issues/16}16}} - super-csv passes "Turkey Test"

    * {{{https://github.com/super-csv/super-csv/issues/49}49}} - Fixed documentation for <<<CsvDozerBeanWriter>>> class

    * {{{https://github.com/super-csv/super-csv/issues/56}56}} - Created test suite due to {{{http://csveed.org/comparison-matrix.html}Comparison matrix}} page

* 2.3.1

  <03/2015>
  
  Fixed a regression introduced in the last release.
  
  <<Bug fixes>>

    * {{{https://github.com/super-csv/super-csv/issues/30}30}} - Fixed bug in <<<Tokenizer>>> where consecutive quoted newlines caused a <<<StringIndexOutOfBoundsException>>>

* 2.3.0

  <02/2015>
  
  General housekeeping, plus a brand new Joda-Time extension packed with useful cell processors.
  
  <<New features>>
  
    * {{{https://github.com/super-csv/super-csv/issues/15}15}} - Cell Processors for Joda-Time
  
  <<Bug fixes>>

    * {{{https://github.com/super-csv/super-csv/issues/18}18}} - Fixed locale-dependent unit test
    
  <<General enhancements>>
  
    * {{{https://github.com/super-csv/super-csv/issues/20}20}} - Memory optimization in <<<Tokenizer>>>
    
    * {{{https://github.com/super-csv/super-csv/issues/28}28}} - Allowed <<<validateInputNotNull()>>> to be overridden by cell processors
    
  <<Breaking changes>>

    * {{{https://github.com/super-csv/super-csv/issues/17}17}} - Removed deprecated <<<AbstractCsvWriter.escapeString()>>> method

* 2.2.1

  <01/2015>
  
  Moved the project to GitHub (and git!), as well as some features and bug fixes.
  
  <<New features>>
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/40/}40}} - Added ignoreCase functionality to <<<ParseBool>>>
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/48/}48}} - Added <<<ignoreEmptyLines>>> preference  
  
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/43/}43}} - Fixed <<<DefaultCsvEncoder>>> to prevent <<<StringIndexOutOfBoundsException>>> when using preferences in multiple threads.

* 2.2.0

  <04/2014>
  
  A small release to show the project is still alive...(has a whole year passed already??)
  
  <<New features>>
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/28/}28}} - <<<CsvBeanReader>>> and <<<CsvDozerBeanReader>>> can now read into existing beans
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/39/}39}} - <<<ParseBigDecimal>>> now removes grouping separators if <<<DecimalFormatSymbols>>> are supplied  
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/41/}41}} - A new <<<ParseEnum>>> cell processor for parsing Enums
  
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/45/}45}} - <<<CsvBeanReader>>> and <<<CsvBeanWriter>>> are more flexible when matching getters/setters (case is ignored)

    * {{{https://sourceforge.net/p/supercsv/bugs/46/}46}} - <<<DMinMax>>> and <<<LMinMax>>> processors can now be chained after <<<StringCellProcessors>>>
    
    * {{{https://sourceforge.net/p/supercsv/bugs/49/}49}} - <<<HashMapper>>> now allows all kinds of processors to be chained after it
    
* 2.1.0

  <04/2013>
  
  A ton of great new features :)
  
  <<New features>>
  
    * {{{https://sourceforge.net/p/supercsv/feature-requests/8/}8}} - Added locale support to ParseDate processor
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/9/}9}} - Readers can now skip comments (via the <<<skipComments>>> CsvPreference) 
      and Writers can write comments (via the <<<writeComment()>>> method)
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/23/}23}} - Upgrade to Dozer 5.4.0
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/24/}24}} - Added a <<<quoteMode>>> preference that allows quoting to be enabled when it's normally
      not required, as well as adding a <<<csvEncoder>>> preference that allows complete control over how CSV is encoded for writing.
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/25/}25}} - Added {{{./apidocs/org/supercsv/cellprocessor/Collector.html}Collector}} and 
      {{{./apidocs/org/supercsv/cellprocessor/constraint/IsElementOf.html}IsElementOf}} cell processors, which can be combined to ensure referential integrity.
      Collector can also help during development - you could apply a Collector (with a Set) to a column to find out all of the unique values for that column!
      
    * {{{https://sourceforge.net/p/supercsv/feature-requests/27/}27}} - Added support for boolean getters (e.g. <<<isX()>>>) to CsvBeanWriter
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/31/}31}} - CsvListReader now supports cell processors for CSV files with a variable number of columns
  
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/38/}38}} - <<<AbstractCsvWriter.escapeString()>>> now increments the line count correctly for embedded newlines
    
    * {{{https://sourceforge.net/p/supercsv/bugs/39/}39}} - <<<CsvDozerBeanReader>>> now accepts hints when reading into Lists of beans using indexed mapping
    
  <<General enhancements>>
  
    * Resurrected the speed benchmark tests. There's now a full suite of benchmark tests for all the readers/writers.
    
* 2.0.1

  <12/2012>
  
  Just a small bug fix release to restore Java 5 compatibility (should also be more compatible with older versions of Android as well).
  
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/36/}36}} - CsvBeanReader allows a nameMapping array of the wrong size when processors aren't used
    
    * {{{https://sourceforge.net/p/supercsv/bugs/37/}37}} - Restore Java 5 compatibility

* 2.0.0

  <11/2012>
  
  This is the final release of version 2.0.0, which fixes a few minor bugs found in version 2.0.0-beta-1.
  Please refer to the 2.0.0-beta-1 release notes below for a full list of new features, bug fixes and upgrade notes.
  
  
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/33/}33}} - Added missing WEDNESDAY enum literal to custom cell processor example
    
    * {{{https://sourceforge.net/p/supercsv/bugs/34/}34}} - Added SLF4J API jar to distribution zip file
    
    * {{{https://sourceforge.net/p/supercsv/bugs/35/}35}} - CsvListReader now returns a new List for each <<<read()>>> operation
    
* 2.0.0-beta-1

  <09/2012>
  
  <<New features>>

    * 100% {{{http://tools.ietf.org/html/rfc4180}RFC 4180}} compliance

    * {{{https://sourceforge.net/p/supercsv/feature-requests/3/}3}} - Super CSV now supports mapping nested properties (deep mapping and index-based mapping)
    with the new CsvDozerBeanReader and CsvDozerBeanWriter (included in the super-csv-dozer-extension project).

    * {{{https://sourceforge.net/p/supercsv/feature-requests/12/}12}} - CsvBeanReader now supports any compatible setter method (as long as the parameter type - interface or object - is compatible with the object being set).
    Previously, the parameter type had to be an exact match on the object's type.
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/17/}17}} - All Writers implement <<<Flushable>>>

    * {{{https://sourceforge.net/p/supercsv/feature-requests/18/}18}} - OSGi support
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/19/}19}} - All Readers and Writers now implement <<<Closeable>>>

    * {{{https://sourceforge.net/p/supercsv/feature-requests/20/}20}} - Maven support (see details on the {{{./downloading.html}download}} page)
    
    * {{{https://sourceforge.net/p/supercsv/feature-requests/21/}21}} - All Readers now have a <<<getUntokenizedRow()>>> method for retrieving the raw String of the row just
      read (before it's been tokenized). 
      All Readers and Writers now have a <<<getRowNumber()>>> method for getting the number of CSV rows read/written (including the header).
      This is different from <<<getLineNumber()>>>, which returns the physical line number, as rows may span more than one line (the CSV
      format allows for multiline fields, as long as they're within double-quotes).
    
  <<Bug fixes>>

    * {{{https://sourceforge.net/p/supercsv/bugs/12/}12}} - Fixed NPE in CsvBeanReader when value to set is null
    
    * {{{https://sourceforge.net/p/supercsv/bugs/14/}14}} - AbstractCsvWriter now escapes for trailing spaces
    
    * {{{https://sourceforge.net/p/supercsv/bugs/16/}16}} - Refactored Readers/Writers so it's no longer possible to modify preferences
    
    * {{{https://sourceforge.net/p/supercsv/bugs/19/}19}} - Fixed NPE in SuperCsvException constructor

    * {{{https://sourceforge.net/p/supercsv/bugs/21/}21}} - New <<<surroundingSpacesNeedQuotes>>> preference allows the disabling of quoting for leading spaces

    * {{{https://sourceforge.net/p/supercsv/bugs/23/}23}} - CsvListWriter now allows all cell processors (not just String processors)
    
    * {{{https://sourceforge.net/p/supercsv/bugs/29/}29}} - Column numbers now start at 1 (instead of 0)
    
    * {{{https://sourceforge.net/p/supercsv/bugs/30/}30}} - All writers now allow null in the nameMapping array (except CsvDozerBeanWriter)

  <<General enhancements>>
  
    * Complete overhaul of javadoc
    
    * Improved test coverage (now 100%!)
    
    * More defensive programming (à la Josh Bloch's <Effective Java>). 
    It's a lot harder to do silly stuff with the API now - for example CellProcessors will fail fast during construction if not set up correctly, instead of during execution.
    
    * A new and improved maven site (please like/+1 us!)
    
    * Removed dependency on the Spiffy library - Super CSV (excluding the new Dozer extension) is now completely standalone!
    
  <<Upgrade notes>>
  
  As this is a major release and it's been 4 years since the last release, there have been numerous changes that are not backwards-compatible with older versions.
  Here's an overview of things to be aware of when upgrading from version 1.52:
  
  * General changes
  
    * The treatment of spaces surrounding a cell has changed
    
      * All spaces are now considered important (to conform to RFC 4180), and surrounding spaces won't be trimmed by default
      
      * A new preference has been added to enable/disable this functionality (see the section on <<<surroundingSpacesNeedQuotes>>> on the {{{./preferences.html}preferences}} page).

    * Line number, row number (a new property of both readers and writers) and column number all start from 1. This means:
  
      * the <<<get(int n)>>> method of all Readers now expects the column number to begin at 1 (it was previously 0)
    
      * the column number reported in Exceptions (via the CsvContext object) begins at 1
    
      * the new row number property refers to one record of CSV (which may span multiple physical lines) - this number begins at 1 and includes the header
    
      * line number refers to the physical line of CSV being read/written and begins at 1 (same as before).
    
    * CsvPreference is now immutable, and must be constructed using its internal builder (see the {{{./preferences.html}preferences}} page)
  
    * All classes with <<<CSV>>> in their name have been renamed to <<<Csv>>>. The new names are:
  
      * <<<SuperCsvException>>>
    
      * <<<SuperCsvReflectionException>>>
    
      * <<<CsvContext>>>
      
    * Exceptions have been tidied up
    
      * <<<ClassCastInputCSVException>>> and <<<NullInputException>>> have been removed 
      (<<<SuperCsvCellProcessorException>>> is now used when an unexpected type or null input is encountered in a cell processor).
  
      * <<<SuperCsvException>>> has been updated. It no longer contains the offending processor, as there's a new exception (<<<SuperCsvCellProcessorException>>>) for this.
    
      * <<<SuperCsvCellProcessorException>>> has been added as a general exception for anything that goes wrong during cell processor execution.
    
      * <<<SuperCsvConstraintViolationException>>> has been added. 
      This exception is <only> thrown when the processor can accept the input (it's of the expected type and not null), but it doesn't satisfy the constraint. 
      For example, if <<<LMinMax>>> encounters a Long value, but it is outside the required range then a <<<SuperCsvConstraintViolationException>>> will be thrown.
      If the <<<LMinMax>>> processor encounters a decimal value (e.g. 1.5), then a general <<<SuperCsvCellProcessorException>>> will be thrown. 
  
  * Changes related to reading
  
    * The <<<getCSVHeader()>>> on all Readers has been renamed to <<<getHeader()>>> (to match <<<writeHeader()>>> on Writers)
  
    * All Readers will now read empty columns (i.e. <<<"">>>) as <<<null>>> (previously they would be read as <<<"">>>).
      The <<<Optional>>> processor has been updated to cater for this.
    
    * All Readers now implement <<<Closeable>>>
    
    * All Readers now have a <<<getUntokenizedRow()>>> method which returns the untokenized CSV row that was just read
    
    * All Readers now have a <<<getRowNumber()>>> method which returns the number of the CSV row just read (essentially the number of records, including the header)
    
    * <<<CsvListReader>>> now returns a List of Objects (not Strings) when CellProcessors are used
    
    * <<<CsvMapReader>>> read() methods no longer have wildcards in their return type
    
    * <<<CsvBeanReader>>> now allows any compatible setter method to be used 
    (e.g. if the value to map to the bean is a Double, then a setter that expects a Number will now work - 
    previously the setter would have to expect a Double as well).
    
  * Changes related to writing
  
    * All Writers will now write null columns as <<<"">>> (previously this would have caused an Exception).
  
    * All Writers now implement <<<Closeable>>>
  
    * All Writers now implement <<<Flushable>>> - so you can flush the stream without closing.
    
    * All Writers now have a <<<getRowNumber()>>> method which returns the number of the CSV row just written (essentially the number of records, including the header)
    
  * Changes related to CellProcessors
  
    * The Optional processor now matches on <<<null>>> instead of <<<"">>>. This means it can now be used for reading <and> writing.
    
    * The <<<Required>>>, <<<StrForbidden>>>, and <<<StrRegExReplace>>> processors have been removed. 
      Instead, you should use <<<RequireHashCode>>>, <<<ForbidSubStr>>>, and <<<StrReplace>>> respectively.
      
    * The <<<Trim>>> processor now trims whitespace (i.e. <<<String.trim()>>>). The new <<<Truncate>>> processor contains the old Trim functionality.
    
    * The min/max constants in <<<DMinMax>>> and <<<LMinMax>>> have all been renamed, and extra constants added to distinguish between signed/unsigned 8-bit min/max values.
    
    * <<<StrRegEx>>> now uses <<<Matcher.matches()>>> instead of <<<Matcher.find()>>>, so the regular expression must match the whole field
    
    * All processors have been updated to use the new exception classes <<<SuperCsvCellProcessorException>>> and <<<SuperCsvConstraintViolationException>>> 
  
=========================================================================================================

* 1.52

  <09/2008>

  <<Bug fixes>>

    * Bug in CsvListWriter on null inputs

=========================================================================================================
  
* 1.51

  <08/2008>

  <<New features>>

    * Improved processors. Extended auto boxing types to include boolean, float and double.

=========================================================================================================

* 1.50

  <08/2008>

  <<New features>>

    * Improved processors.
    
  <<Bug fixes>>

    * Minor bug fixes

=========================================================================================================

* 1.50 Beta

  <06/2008>

  Added the following cell processors
  
    * <<<Equals>>> - test if all values are equals alone, or equals to a given constant
    
    * <<<FmtBool>>> - format as a string any Boolean value
    
    * <<<HashMapper>>> - to map encountered values with other objects/values
    
    * <<<IsIncludedIn>>> - to ensure input value belongs to a specific set of given values
    
    * <<<NotNull>>> - to ensure non-null values for columns
    
    * <<<ParseBigDecimal>>> - parse a string to get a big decimal
    
    * <<<StrNotNullOrEmpty>>> - to ensure non-null or empty values for columns
    
    * <<<StrReplace>>> - for string manipulation
    
    * <<<StrRegExReplace>>> - for string manipulation

  Deprecated the following cell processors
  
    * <<<Required>>>, re-implemented as <<<RequiredHashCode>>>

  A new processor named <<<Unique>>> (based on <<<equals()>>>) has been created - the old definition based on hashCode() has been renamed to <<<UniqueHashCode>>>.

  BeanReader and BeanWriter now supports method overloading of get/set methods.

  Cell processors now only throw <<<SuperCSVException>>>

  Added the following exceptions
  
    * ClassCastInputCSVException
    
    * NullInputException: this exception is raised now for unexpected 'null' input value for processor. 
      Numerous processors have been modified to use that exception class.

  Better handling of lines without the expected number of columns
  
    * The raised exception is now associated with a valid CSVContext object (previously, this object was 'null')
    
  Better error messages, more context information in the exception and available to the programmer

  Upgrade notes
  
    * Just copy over the .jar file and notice the deprecated classes...

=========================================================================================================

* 1.30

  <01/2008>

  Improved integration and convenience
  
    * BeanReader now accepts interface types to read into. The reader will create an implementation on-the-fly of the interface and use this.
    
    * The ITokenizer interface has become public, making 3rd party extensions better integrated.
     
    *  The exception class now contains the file context in which it was thrown. And generally, all places exceptions are 
       thrown have been cleaned up, streamlined and now passes the file context upon an exception.
       
    *  An overloaded read() has been removed entirely
    
    * Added the following new cell processors: <<<ParseBigDecimal>>>
    
    * A new exception <<<SuperCSVReflectionException>>> replaces annoying Java checked exceptions 
      <<<ClassNotFoundException, IllegalAccessException, InstantiationException, InvocationTargetException, NoSuchMethodException>>>
      
    * More methods now use the var-args ("...") notation for easy use.
    
=========================================================================================================

* 1.20

  <11/2007>

  Improved processors and partial writing

    * Added the ConvertNullTo cell processor which enables better support for writing partial objects, maps and lists.

    * Changed method signatures to use the var-args ("...") notation to make the programming more natural. This has been done for:

      * <<<writeHeader()>>> on all Writers
      
      * <<<ForbidSubStr>>>, <<<Required>>>, and <<<StrLen>>>
      
    * Small bugfix in processor StrLen
    
    * More documentation on the web
    
=========================================================================================================

* 1.15

  <10/2007>
  
  Improved robustness and speed
  
    * Made the CSV Encoder more robust (used when writing CSV files)
    
    * Made the CSV encoder faster. Around 25% faster!
    
    * Added a lot of tests.
    
    * Set up an environment in dir slow_tests to enable future development to easily compare efficiency with older versions of the same functionality

=========================================================================================================

* 1.10

  <10/2007>
  
  Faster and better
  
    * Introduced new cell processors <<<ParseChar>>>, <<<ForbidSubStr>>>, <<<RequireSubStr>>>
    
    * Made the tokenizer 5% faster (the thing that reads and interprets the CSV files)! Reading files has never been faster!
    
    * The framework now support plugging in new tokenizers onto readers. Feel free to author your own fast tokenizer
    
    * Improved the Javadoc for some processors
    
    * Added source branch specifically for tokenizer speed testing and comparison. It is now easy to experiment with various tokenizing strategies.

=========================================================================================================

* 1.02

  <09/2007>
  
  Small bugfixes
  
    * Empty cells with value <<<"">>> was mistakenly interpreted as an escaped quoted char rather than the empty line
    
    * No longer removes trailing spaces inside quotes so <<<" hello ">>> is read as <<<" hello ">>> rather than <<<" hello">>>
    
    * Renamed the cell processor <<<MagicToken>>> to <<<Token>>>
    
    * TABs are not regarded as whitespace anymore

=========================================================================================================

* 1.01

  <09/2007>
  
  Small bugfixes

    * Inherited properties are now supported by the bean reader/writer
    
    * JAR file is now compiled for JDK 5.
    
=========================================================================================================

* 1.0

  <09/2007>
 
  Initial release
