Introducing UCSV
Published March 17, 2010 10:07 am
Background
UCSV is a small (less than 1kb when minified and gzipped) JavaScript library. It provides a simple interface for importing and exporting CSV data into and out of JavaScript applications. UCSV namespaces all of it's functions in a global variable named CSV. It has two easy to use methods: csvToArray and arrayToCsv. Below are a few simple examples demonstrating how to use UCSV.
In these examples we'll use a couple of small data sets of unemployment statistics from January 2010:
Data set 1
Alaska,8.5 Arkansas,7.6 California,12.5
Data set 2
Utah,6.8 Virginia,6.9 Washington,9.3
Converting CSV into a JavaScript Array
After our first data set is converted to a JavaScript string it looks like this:
"Alaska,8.5\nArkansas,7.6\nCalifornia,12.5\n"
The following code will take this CSV data and convert it into an array. Each item represents a row of data and itself is an array representing each field in the row.
var arr,
data = "Alaska,8.5\nArkansas,7.6\nCalifornia,12.5\n"
arr = CSV.csvToArray(data);
console.log(arr);
/* arr now contains the array:
[
["Alaska", "8.5"],
["Arkansas", "7.6"],
["California", "12.5"]
]
*/
By default UCSV complies to RFC 4180 and does not trim leading or trailing space in fields. If you would like this behavior you can set the optional second parameter to True.
var arr,
// padding added to fields
data = " Alaska ,8.5\n Arkansas ,7.6\nCalifornia , 12.5\n"
// setting the second parameter to true will strip
// the padding when importing
arr = CSV.csvToArray(data, true);
/* arr now contains the array:
[
["Alaska", "8.5"],
["Arkansas", "7.6"],
["California", "12.5"]
]
*/
Converting an Array Into a CSV
If we write our second data set as an array it ends up looking like this:
[
["Utah",6.8],
["Virginia",6.9],
["Washington",9.3]
]
We can convert it into a string using the following JavaScript:
var data,
arr = [
["Utah",6.8],
["Virginia",6.9],
["Washington",9.3]
];
data = CSV.arrayToCsv(arr);
/* data now contains: "Utah,6.8\nVirginia,6.9\nWashington,9.3" */
Conclusion
That's all there is to using UCSV. If you would like to learn more about UCSV you can find a more complex demo, documentation and source code at the UCSV project homepage.
- lbJuly 17, 2010 07:23 amI love what you've done and it is far superior to every other javascript-based csv parser i've found. But i think i disagree with some of the results you get. I expect consecutive commas to return null values, rather than empty strings. i.e.: ,,,, is not the same as: "","","","","" And other pedantic points around this same theme. I'm writing a csv parser for javascript and part of this is a suite of unit tests. As there's no consensus on what makes for valid csv it's hard to have a reliable set of unit tests, and the whole venture falls apart soon after. Still, I like to think that csv is the future ;-) kind regards lb
- July 17, 2010 11:41 pmThank you for the kind words. I have a unit test for this library, it's just not part of the files in the public releases yet. You are right about empty fields. I just change it so it behaves as you described. I've been working on other projects lately but I think I'm going to make a couple of other similar tweaks; treating non-quoted numbers like numbers instead of strings containing numbers, etc. It shouldn't take too long, I'll post a small entry on this blog when the new version is up. Oh, and JSON is the future :P
- August 22, 2010 11:05 pm[...] would insert an empty string into the resulting array when it encountered an empty field. As was suggested by Leon Bambrick, it now instead inserts nulls. Likewise, csvToArray() now converts non-quoted [...]
- July 13, 2011 09:33 amHello, i'm using your lib successfully. The only hack i added it was an argument in csvToArray to permit setting the separator ( i need \;\ instead of \,\). I paste the modifications:
function csvToArray(s, separator, trm) { s = chomp(s); if ( separator == undefined || separator == \\ ) { separator = \,\; } ... .... if (inQuote === false && (cur === separator || cur === \ \)) { ... - February 20, 2012 04:00 pmI agree that this is the best CSV code for javascript available on the internet, and I'm using it in my Firefox add-on \Rental Application\. I thank you very much for making it available. However, I've come accross a problem which can be demonstrated in your demo: http://www.uselesscode.org/javascript/csv/demo/example-importing-exporting-csv.htm. Copy and paste the below CSV, and replace 'dbl-quote' with actual double quote marks (for some reason this editor replaces double quotes with back-slashes).
dbl-quote1/20/2012 - 2/20/2012dbl-quote
- February 20, 2012 04:09 pmAnother example would be
"3835 Park Ave 64109"
- February 20, 2012 04:56 pmThanks for reporting this bug! When the arrayToCsv() method creates the output string it automatically wraps any item that has leading or trailing space, a comma or double-quotes with double quotes. It should have also been doing this to items containing newline characters but it wasn't. I've fixed the bug and a new version should be up soon.
- February 20, 2012 05:21 pmGreat! I was just working on wrapping all the textareas with double quotes, but was not getting the expected results. I hope you'll have the new version up today or tomorrow. Can you email me when it is? Will it have a new version number?
- February 20, 2012 05:50 pmNew version 1.0.3 is up.
- February 20, 2012 05:51 pmThanks. you're saving me.
- February 22, 2012 12:37 pmWould it be possible to add the following line to the very end of your source?
if (typeof exports == "object") { exports.arrayToCsv = CSV.arrayToCsv; exports.csvToArray = CSV.csvToArray; } //makes this library available to Mozilla Add-On SDK https://addons.mozilla.org/en-US/developers/docs/sdk/latest/ in the lib folder by var CSV = require('./UCSVv1.0.3'); - February 22, 2012 11:10 pm[...] in (Jetpack) Add-ons for Mozilla and should also allow use in Node.js projects. This feature was suggested by Colin Keenan who also discovered the bug fixed in the recent 1.0.3 [...]