Header rows are supported when parsing from CSV data, both to arrays of arrays and to arrays of objects.

When parsing CSV data to an array of arrays, a header row that exists in the CSV data string can either just be "gobbled" and thrown away, or it can be gathered in an empty array that you supply using the columns decoding option. Either way, the column names in a header row are kept from getting into the records array that is returned by the Uize.Data.Csv.from method, because they are not part of the data set.

When parsing CSV data to an array of objects, the header row that exists in the CSV data string can be used for the key names for the objects in the returned records array. If there is no header row in the CSV data string and the value false is specified for the hasHeader option, the column names can still be supplied to the Uize.Data.Csv.from method using the columns decoding option when parsing to an array of objects.

Header rows are supported when serializing to CSV data, both from arrays of arrays and from arrays of objects.

When serializing an array of arrays to a CSV data string, the column names to be used in the header row can be supplied to the Uize.Data.Csv.to method using the columns encoding option.

When serializing an array of objects to a CSV data string, the column names to be used in the header row can be taken directly from the key names of the first object in the records array, or they can be explicitly specified to the Uize.Data.Csv.to method using the columns encoding option. Using the columns option allows the column order to be controlled, or a subset of the columns to be serialized (see Column Ordering And Filtering).

The columns encoding option can be used to enforce an ordering for columns in the serialized CSV data string.

If you're serializing a records array where the records are of type object and you leave it up to the Uize.Data.Csv.to method to determine the columns, the column order will depend entirely on the order in which the keys were assigned to the first row's object in the records array. As long as the serialized CSV data string has a header row (the value true is specified for the hasHeader option) and the data is to be later parsed to an array of objects, one may not care about the column ordering. If column ordering is important, however, then the columns option can be used to control this.

In some cases you may wish to serialize an array of object records, but not include all of the columns in the serialized output.

In such cases you can use the columns encoding option to specify just the columns that you wish to have serialized, along with the exact order in which you wish them to be arranged in the serialized CSV data string.

When parsing a CSV data string that contains a header row, to an array of arrays (i.e. specifying the value 'array' for the rowType option), and specifying the value true for the hasHeader option, the column names row doesn't make its way into the returned records array.

This is by design, because the column names are not part of the data set. In such cases, specifying an array value for the columns option provides a way for you to obtain the column names. Even when parsing such a CSV data string to an array of objects, where each record object has key names that reflect the column names obtained from the header row, it still may be useful to get back a separate array of the column names - especially for the occasional case where the CSV data string has no data, but just the column names header row.

NOTE

The contents of an array specified for the columns option will be replaced with the column names from the CSV data string's header row. Typically, you would supply an empty array, but you could reuse an array with existing contents.

When parsing a CSV data string that doesn't contain a header row, to an array of objects (i.e. specifying the value 'object' for the rowType option), then the columns option lets you specify the names of the columns.

Column names supplied by the columns option will be used as the key names for the objects of the returned records array. In this case, the contents of the specified column names array will not be altered.

In this example, the CSV data string being parsed has been serialized in strict accordance to the rules laid out in RFC 4180, and is being parsed by the Uize.Data.Csv.from method using all the decoding option defaults (i.e. no decodingOptionsOBJ parameter is being specified).

INPUT

"John ""Willy""",Wilkey,(650) 123-4567
Marie, Stevenson ,"(415) 456-7890, Ext. 214"
Craig,Pollack,"(310) 987-6543
(650) 303-1000"

PARSE

Uize.Data.Csv.from (input);

OUTPUT

[
  ['John "Willy"','Wilkey','(650) 123-4567'],
  ['Marie',' Stevenson ','(415) 456-7890, Ext. 214'],
  ['Craig','Pollack','(310) 987-6543\n(650) 303-1000']
]

Looking at the CSV data string, you'll notice a few things...

None of the above factors are a problem for the Uize.Data.Csv.from method, since all these behaviors comply with the rules of RFC 4180.

In this example, the CSV data string was originally serialized with a cosmetic space after the comma value delimiter.

We happen to know this about the source material, so we specify the value true for the trimPaddingOnParse option. This results in the whitespace padding around values being trimmed away. In the returned records array, therefore, the column values do not contain padding.

INPUT

John, Wilkey, (650) 123-4567
Marie, Stevenson, (415) 456-7890
Craig, Pollack, (310) 987-6543

PARSE

Uize.Data.Csv.from (input,{trimPaddingOnParse:true});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

In this example, we're parsing a CSV data string to an array of records and supplying the column names.

INPUT

John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

PARSE

Uize.Data.Csv.from (input,{columns:['firstName','lastName','phone']});

OUTPUT

[
  {firstName:'John',lastName:'Wilkey',phone:'(650) 123-4567'},
  {firstName:'Marie',lastName:'Stevenson',phone:'(415) 456-7890'},
  {firstName:'Craig',lastName:'Pollack',phone:'(310) 987-6543'}
]

As you'll notice from the CSV data string, there is no header row to indicate the column names. Therefore, when we parse the string we provide the column names using the columns option. Now, because we're specifying an array for the columns option, and because we're not specifying a value for the rowType option (so it defaults to 'auto'), the Uize.Data.Csv.from method chooses object type for the records. The column names that we've provided are used as the keys for the record objects.

In this example, the CSV data string contains a header row and we're parsing the string to an array of objects.

INPUT

firstName,lastName,phone
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

PARSE

Uize.Data.Csv.from (input,{hasHeader:true});

OUTPUT

[
  {firstName:'John',lastName:'Wilkey',phone:'(650) 123-4567'},
  {firstName:'Marie',lastName:'Stevenson',phone:'(415) 456-7890'},
  {firstName:'Craig',lastName:'Pollack',phone:'(310) 987-6543'}
]

The Uize.Data.Csv.from method doesn't know that the CSV data string has a header row unless we tell it, so we specify the value true for the hasHeader option. Now, because we're specifying true for the hasHeader option, and because we're not specifying a value for the rowType option (so it defaults to 'auto'), the Uize.Data.Csv.from method chooses object type for the records. The column names are obtained from the first row of the CSV data string and are used as the keys for the record objects.

In this example, the CSV data string contains a header row, but we want to parse the string to an array of arrays and don't want the column names in the data set.

INPUT

firstName,lastName,phone
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

PARSE

Uize.Data.Csv.from (input,{hasHeader:true,rowType:'array'});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

First off, the Uize.Data.Csv.from method doesn't know that the CSV data string has a header row unless we tell it, so we specify the value true for the hasHeader option. If we don't expicitly specify a value for the rowType option, this option will default to 'auto', and the Uize.Data.Csv.from method will decide to parse the CSV data string to an array of objects because we're specifying true for the hasHeader option. By specifying the value 'array' for rowType, we override this automatic behavior. This results in the header row being "gobbled" up - it's not getting used as the keys for object records, and it doesn't belong in the data set.

In this example, the CSV data string contains a header row, we want to parse the string to an array of arrays and don't want the column names in the data set, but we would like to know what the column names are.

INPUT

firstName,lastName,phone
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

PARSE

var columnNames = [];
Uize.Data.Csv.from (input,{hasHeader:true,rowType:'array',columns:columnNames});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

First off, the Uize.Data.Csv.from method doesn't know that the CSV data string has a header row unless we tell it, so we specify the value true for the hasHeader option. We specify the value 'array' for the rowType option to override the automatic behaviour in this case of parsing the CSV data string to an array of objects. Finally, we specify a reference to an empty array for the columns option. This empty array will be populated with the column names obtained from the CSV data string's header row. We can then use these column names later in other code.

In this example, the CSV data string was originally serialized using a single quote character for quoting values, rather than the standard double quote character.

We happen to know this about the source material, so we specify the value '\'' for the quoteChar option. Our CSV data string parses correctly and life is good.

INPUT

'John','Wilkey','(650) 123-4567'
'Marie','Stevenson','(415) 456-7890'
'Craig','Pollack','(310) 987-6543'

PARSE

Uize.Data.Csv.from (input,{quoteChar:'\''});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

In this example, the (obviously) eccentric software that originally serialized the CSV data string used a "|" (pipe) character for separating column values.

Fortunately, we happen to know this about the source material, so we specify the value '|' for the valueDelimiter option and the Uize.Data.Csv.from method saves the day.

INPUT

John|Wilkey|(650) 123-4567
Marie|Stevenson|(415) 456-7890
Craig|Pollack|(310) 987-6543

PARSE

Uize.Data.Csv.from (input,{valueDelimiter:'|'});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

To one-up the software that serialized a CSV data string using a "|" (pipe) character for separating column values, some even crazier software decided to use the "#" (pound / hash) character for quoting column values and a single space for separating values.

We suspect as much about the source material, based upon our deep-seated suspicions of the provider of the data, so we specify the value '#' for the quoteChar option and the value ' ' (space) for the valueDelimiter option. Everything checks out, and we've dodged another bullet.

INPUT

#John# #Wilkey# #(650) 123-4567#
#Marie# #Stevenson# #(415) 456-7890#
#Craig# #Pollack# #(310) 987-6543#

PARSE

Uize.Data.Csv.from (input,{quoteChar:'#',valueDelimiter:' '});

OUTPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

In this example, we have some very plain vanilla data - in the form of an array of arrays - and we're serializing this data to a CSV data string in strict accordance with the rules laid out in RFC 4180.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input);

OUTPUT

John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

There is nothing particulatly challenging about the source records array - none of the values have special characters that would cause them to need quoting. To serialize to strict CSV format, we don't need to specify any encoding options in the optional encodingOptionsOBJ parameter. Sometimes life is just too easy.

In this example, we're serializing data to a CSV data string in strict accordance with the rules laid out in RFC 4180, but some of the column values contain special characters that require them to be quoted.

INPUT

[
  ['John "Willy"','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890, Ext. 214'],
  ['Craig','Pollack','(310) 987-6543\n(650) 303-1000']
]

SERIALIZE

Uize.Data.Csv.to (input);

OUTPUT

"John ""Willy""",Wilkey,(650) 123-4567
Marie,Stevenson,"(415) 456-7890, Ext. 214"
Craig,Pollack,"(310) 987-6543
(650) 303-1000"

Comparing the source records array to the serialized CSV data string, you'll notice a few things...

None of the above factors are a problem for the Uize.Data.Csv.to method, since all these behaviors comply with the rules of RFC 4180, and no special encoding options needed to be specified.

In this example, we're serializing data to a CSV data string in strict accordance with the rules laid out in RFC 4180, where some of the column values contain whitespace padding.

INPUT

[
  ['John',' Wilkey ','(650) 123-4567'],
  ['Marie',' Stevenson ','(415) 456-7890'],
  ['Craig',' Pollack ','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input);

OUTPUT

John, Wilkey ,(650) 123-4567
Marie, Stevenson ,(415) 456-7890
Craig, Pollack ,(310) 987-6543

Because we're serializing to strict CSV format, none of the values that contain padding need to be quoted. This is because whitespace around the value separator is considered significant according to RFC 4180 and should not be stripped. Therefore, no special encoding options need to be specified when calling the Uize.Data.Csv.to method in this case.

In this example, we're serializing an array of arrays to a CSV data string, some of the values contain whitespace padding, and we know that the serialized CSV data string may at some point be parsed by code that trims padding around values.

In order to protect against the padding in our values being stripped out later, we let the Uize.Data.Csv.to method know that padding will be trimmed, by some parser in the future, by specifying the value true for the trimPaddingOnParse option. This results in the Uize.Data.Csv.to method quoting those values that contain padding.

INPUT

[
  ['John',' Wilkey ','(650) 123-4567'],
  ['Marie',' Stevenson ','(415) 456-7890'],
  ['Craig',' Pollack ','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{trimPaddingOnParse:true});

OUTPUT

John," Wilkey ",(650) 123-4567
Marie," Stevenson ",(415) 456-7890
Craig," Pollack ",(310) 987-6543

In this example, we're serializing an array of arrays to a CSV data string that has a header row, so we're supplying the column names explicitly.

To make sure that the serialized CSV data string has a header row, we specify the value true for the hasHeader option. Problem is, the records array does not contain the column names. This is normal, since the column names really aren't part of the data set. To remedy this, we explicitly provide the Uize.Data.Csv.to method with the column names using the columns option.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (
  input,
  {
    hasHeader:true,
    columns:['firstName','lastName','phone']
  }
);

OUTPUT

firstName,lastName,phone
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

In this example, we're serializing an array of objects to a CSV data string that has a header row, where the keys of the first record object are used as the column names.

As you'll notice from the records array, the first record has the object keys defined in a different order to the other records. The phone key is first, followed by lastName and firstName. Because we're not explicitly specifying a column order, the columns' names and their ordering is all determined by the first record. If you're parsing the serialized CSV data string back to an array of objects later, then this shouldn't matter. If you care about the order, then refer to the example With Header Row, Rows Are Objects, Column Order Specified. To get the header row in the serialized CSV data string, we're specifying the value true for the hasHeader option.

INPUT

[
  {phone:'(650) 123-4567',lastName:'Wilkey',firstName:'John'},
  {firstName:'Marie',lastName:'Stevenson',phone:'(415) 456-7890'},
  {firstName:'Craig',lastName:'Pollack',phone:'(310) 987-6543'}
]

SERIALIZE

Uize.Data.Csv.to (input,{hasHeader:true});

OUTPUT

phone,lastName,firstName
(650) 123-4567,Wilkey,John
(415) 456-7890,Stevenson,Marie
(310) 987-6543,Pollack,Craig

In this example, we're serializing an array of objects to a CSV data string that has a header row, and we're explicitly specifying the column order using the columns option.

Unlike the example With Header Row, Rows Are Objects, Column Names From Object Keys, here we actually care about the order of the columns in the serialized CSV data string. Therefore, we are using the columns option to control the ordering. If we didn't do this, the ordering would be determined by the order of the keys in the first record object.

To get the header row in the serialized CSV data string, we're specifying the value true for the hasHeader option. You could argue that controlling the column ordering would be even more important if the serialized CSV data string were to not contain a header row and was expected to be parsed at some later stage to an array of arrays, where there was an expected column ordering.

INPUT

[
  {phone:'(650) 123-4567',lastName:'Wilkey',firstName:'John'},
  {firstName:'Marie',lastName:'Stevenson',phone:'(415) 456-7890'},
  {firstName:'Craig',lastName:'Pollack',phone:'(310) 987-6543'}
]

SERIALIZE

Uize.Data.Csv.to (
  input,
  {
    hasHeader:true,
    columns:['firstName','lastName','phone']
  }
);

OUTPUT

firstName,lastName,phone
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

In this example, we're serializing an array of objects to a CSV data string that has a header row, and we're specifying a subset of the columns in the data set to be serialized.

Not only does the columns option let us control the ordering of columns in the serialized CSV data string (see the example With Header Row, Rows Are Objects, Column Order Specified), it also lets us specify just a subset of columns to serialize. In this example we're serializing just the firstName and lastName columns. To get the header row in the serialized CSV data string, we're specifying the value true for the hasHeader option.

INPUT

[
  {phone:'(650) 123-4567',lastName:'Wilkey',firstName:'John'},
  {firstName:'Marie',lastName:'Stevenson',phone:'(415) 456-7890'},
  {firstName:'Craig',lastName:'Pollack',phone:'(310) 987-6543'}
]

SERIALIZE

Uize.Data.Csv.to (
  input,
  {
    hasHeader:true,
    columns:['firstName','lastName']
  }
);

OUTPUT

firstName,lastName
John,Wilkey
Marie,Stevenson
Craig,Pollack

In this example, we're serializing an array of arrays to a CSV data string that has a header row, and since we're not explicitly specifying the column names using the columns option, the column indices are used instead.

To get the header row in the serialized CSV data string, we're specifying the value true for the hasHeader option. To have the array indices be used for the column names, we simply don't specify a value for the columns option. The default value of 'all' when the row type is array causes the column indices to be used as the column names. This may be an unusual and atypical case, but it illustrates the behavior when this combination of options is used.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{hasHeader:true});

OUTPUT

0,1,2
John,Wilkey,(650) 123-4567
Marie,Stevenson,(415) 456-7890
Craig,Pollack,(310) 987-6543

In this example, we're serializing an array of arrays to a CSV data string and forcing all values to be quoted by specifying the value 'always' for the whenToQuoteValues option.

If we didn't specify a value for the whenToQuoteValues option in this example, then none of the values would be quoted. That's because none of the values contain special characters that would require them to be quoted. If it is anticipated that the CSV data string may be parsed by an inferior or non-RFC 4180 compliant parser that requires all values to be quoted, then we can used this facility. Alternatively, if the data set would likely cause a mix of quoting and not quoting, and we have an aesthetic preference for a consistent look / treatment, then we can force all values to be quoted using this option.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{whenToQuoteValues:'always'});

OUTPUT

"John","Wilkey","(650) 123-4567"
"Marie","Stevenson","(415) 456-7890"
"Craig","Pollack","(310) 987-6543"

In this example, we're serializing an array of arrays to a CSV data string and forcing all values to be quoted using a single quote character.

We force all values to be quoted by specifying the value 'always' for the whenToQuoteValues option, and we force single quotes to be used by specifying the value '/'' for the quoteChar option. It is important, when serializing data using encoding options that don't conform to RFC 4180, that you specify the same options upon decoding data serialized in this way using the Uize.Data.Csv.from method. Compare this example to the example Always Quote Values, where all values are quoted, but using the RFC 4180 compliant double quote character.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{whenToQuoteValues:'always',quoteChar:'\''});

OUTPUT

'John','Wilkey','(650) 123-4567'
'Marie','Stevenson','(415) 456-7890'
'Craig','Pollack','(310) 987-6543'

In this example, we're serializing an array of arrays to a CSV data string, using a non-standard "|" (pipe) character as a value delimiter.

This is an unusual case, but not quite as unusual as the example Space As Value Delimiter, Quote Values Using Hash. The Uize.Data.Csv.to method provides the flexibility to do some unusual things. It is important, when serializing data using encoding options that don't conform to RFC 4180, that you specify the same options upon decoding data serialized in this way using the Uize.Data.Csv.from method.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{valueDelimiter:'|'});

OUTPUT

John|Wilkey|(650) 123-4567
Marie|Stevenson|(415) 456-7890
Craig|Pollack|(310) 987-6543

In this example, a space is being used as a value delimiter and a "#" (pound / hash) character is being used as a quoting character.

This is a rather unusual case, and who's to say why this choice of options would be made. This example demonstrates, however, that the Uize.Data.Csv.to method provides the flexibility to do some unusual things. It is important, when serializing data using encoding options that don't conform to RFC 4180, that you specify the same options upon decoding data serialized in this way using the Uize.Data.Csv.from method.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{quoteChar:'#',valueDelimiter:' '});

OUTPUT

#John# #Wilkey# #(650) 123-4567#
#Marie# #Stevenson# #(415) 456-7890#
#Craig# #Pollack# #(310) 987-6543#

In this example, the value delimiter being specified in the valueDelimiter option is a comma with a trailing space.

This makes for a prettier CSV data string. We're not specifying a value for the trimPaddingOnParse option here, so it gets its default value of false. This means that the spaces introduced by the value delimiter could find their way into the column values when the CSV data string is parsed at a later stage. Therefore, the Uize.Data.Csv.to automatically quotes all the column values (as you'll see from the output) so that it is clear what's really inside the values and what's outside the values.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig','Pollack','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{valueDelimiter:', '});

OUTPUT

"John", "Wilkey", "(650) 123-4567"
"Marie", "Stevenson", "(415) 456-7890"
"Craig", "Pollack", "(310) 987-6543"

In this example, the value delimiter being specified in the valueDelimiter option is a comma with a trailing space.

This makes for a prettier CSV data string. We don't mind that there appears to be an extra leading space before the second and third column values, because we know that the code that will parse this CSV data string later will trim whitespace padding around values, and we specify that fact using the trimPaddingOnParse option.

INPUT

[
  ['John','Wilkey','(650) 123-4567'],
  ['Marie','Stevenson','(415) 456-7890'],
  ['Craig',' Pollack ','(310) 987-6543']
]

SERIALIZE

Uize.Data.Csv.to (input,{valueDelimiter:', ',trimPaddingOnParse:true});

OUTPUT

John, Wilkey, (650) 123-4567
Marie, Stevenson, (415) 456-7890
Craig, " Pollack ", (310) 987-6543

Notice in the output how the value ' Pollack ' is quoted, while all the other values aren't. This is because the value itself contains padding, and the true value for trimPaddingOnParse indicates that values containing padding should be quoted or there padding might be trimmed away in error during parsing at a later stage.