#CHCSVParser

CHCSVParser is an Objective-C parser for CSV files.

##Supported Platforms

• Mac OS X 10.5+
• iOS 3+

##Usage

###Parsing In order to parse CSV files, you'll need CHCSVParser.h and CHCSVParser.m. A CHCSVParser works very similarly to an NSXMLParser, in that it synchronously parses the data and invokes delegate callback methods to let you know that it has found a field, or has finished reading a line, or has encountered a syntax error.

A CHCSVParser can be created either with a path to a CSV file, or with an NSString of CSV data.

###Writing In order to write data to a CSV file, you'll need CHCSVWriter.h and CHCSVWriter.m. A CHCSVWriter has 2 primary methods (beyond the designated initializer): writeField: and writeLine.

writeField: accepts an object and writes its -description (after being properly escaped) out to the CSV file. It will also write field seperator (,) if necessary. You may pass an empty string (@"") or nil to write an empty field.

writeLine is used to terminate the current CSV line. If you do not invoke writeLine, then all of your CSV fields will be on a single line.

###Convenience Methods Included in the code is an NSArray category to simplify reading from and writing to CSV files. In order to use these methods, you must include CHCSVParser.*, CHCSVWriter.*, and NSArray+CHCSVAdditions.* in your project (all six files). This category adds 7 methods to NSArray: three class methods, three initializers, and one write method:

• + (id) arrayWithContentsOfCSVFile:(NSString *)csvFile encoding:(NSStringEncoding)encoding error:(NSError **)error;

• - (id) initWithContentsOfCSVFile:(NSString *)csvFile encoding:(NSStringEncoding)encoding error:(NSError **)error;

• + (id) arrayWithContentsOfCSVFile:(NSString *)csvFile usedEncoding:(NSStringEncoding *)usedEncoding error:(NSError **)error;

• - (id) initWithContentsOfCSVFile:(NSString *)csvFile usedEncoding:(NSStringEncoding *)usedEncoding error:(NSError **)error;

• + (id) arrayWithContentsOfCSVString:(NSString *)csvString encoding:(NSStringEncoding)encoding error:(NSError **)error;

• - (id) initWithContentsOfCSVString:(NSString *)csvString encoding:(NSStringEncoding)encoding error:(NSError **)error;

• - (BOOL) writeToCSVFile:(NSString *)csvFile atomically:(BOOL)atomically;

All of the initializers (both class and instance versions) return an NSArray of NSArray objects.

The writeToCSVFile: method expects the same structure (an NSArray of NSArray objects).

There is also an NSString category to parse an NSString of CSV data into an NSArray of NSArray objects. This method is:

• - (NSArray *) CSVComponents;

Both the NSArray and NSString categories require including the CHCSVSupport.h and CHCSVSupport.m files in your project.

###General Use

The simplest use of CHCSVParser is to include all of the files in your project:

• CHCSV.h
• CHCSVParser.h and CHCSVParser.m
• CHCSVWriter.h and CHCSVWriter.m
• NSArray+CHCSVAdditions.h and NSArray+CHCSVAdditions.m
• NSString+CHCSVAdditions.h and NSString+CHCSVAdditions.m
• CHCSVSupport.h and CHCSVSupport.m

Then to use any of the CSV parsing or writing functionality, simply #import "CHCSV.h" and use any of the classes and categories as you'd like.

##Data Encoding CHCSVParser relies on knowing the encoding of the CSV file. It should work with pretty much any kind of file encoding, if you can provide what that encoding is. If you do not know the encoding of the file, then CHCSVParser can make a naïve guess. CHCSVParser will try to guess the encoding of the file from among these options:

• NSUTF8StringEncoding (the default/fallback encoding)
• NSUTF16BigEndianStringEncoding
• NSUTF16LittleEndianStringEncoding
• NSUTF32BigEndianStringEncoding
• NSUTF32LittleEndianStringEncoding

##Performance CHCSVParser is conscious of low-memory environments, such as the iPhone or iPad. It can safely parse very large CSV files, because it only loads portions of the file into memory at a single time. For example, CHCSVParser can parse a 4 million line CSV file (over 300MB on disk) in under one second while only consuming about 75K of active memory.

##Credits

CHCSVParser was written by Dave DeLong.

CHCSVParser uses code to discover file encoding that was provided by Rainer Brockerhoff.

##License

CHCSVParser is licensed under the MIT license, which is reproduced in its entirety here:

Copyright (c) 2010 Dave DeLong

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.