CHCSVParser is an Objective-C parser for CSV files.
- Mac OS X 10.5+
- iOS 3+
In order to use
CHCSVParser, you'll need to include the following three files in your project:
These four files are optional, though they do simplify things:
In order to use
CHCSVWriter, you'll need to include the following two files in your project:
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.
CHCSVParser can be created in one of three ways:
- With a path to a file
- With the contents of an
- With an
CHCSVParser can be configured to parse other "character-seperated" file formats, such as "TSV" (tab-seperated). You can change the delimiter of the parser prior to beginning parsing. The delimiter can only be one character in length, and cannot be any newline character,
CHCSVWriter has several methods for constructing CSV files:
-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 (
nil to write an empty field.
-writeFields: accepts a comma-delimited and nil-terminated list of objects and sends each one to
-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.
-writeLineOfFields: accepts a comma-delimited and nil-terminated list of objects, sends each one to
-writeField:, and then invokes
-writeLineWithFields: accepts an array of objects, sends each one to
-writeField:, and then invokes
-writeCommentLine: accepts a string and writes it out to the file as a CSV-style comment.
In addition to writing to a file,
CHCSVWriter can be initialized for writing directly to an
CHCSVWriter can be customized with a delimiter other than
, prior to beginning writing.
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 also include
NSArray+CHCSVAdditions.* in your project. This category adds many methods to
NSArray to simplify the process of converting a file, string, or input stream into an
NSStrings. There are also methods to write the array to a CSV file (or with a custom delimiter), or to convert it into an
NSString of well-formed CSV.
There is also an
NSString category to parse an
NSString of CSV data into an
NSArray objects. This method is
The simplest use of
CHCSVParser is to include all of the files mentioned above in your project. 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.
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:
NSMacOSRomanStringEncoding(the default/fallback encoding)
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.
At some point,
CHCSVWriter will support writing data directly to
Credits & Contributors
CHCSVParser was written by Dave DeLong.
CHCSVParser uses code to discover file encoding that was provided by Rainer Brockerhoff.
Thanks also to these people for suggestions and bug fixes to
CHCSVParser is licensed under the MIT license, which is reproduced in its entirety here:
Copyright (c) 2011 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.