Updated September 2023
WRITECD {#ch,} expr1{, …, exprN}
WRITECD {#ch,} ary()
WRITECD {#ch,} $grid()
"Write Comma Delimited" is a variation of the PRINT statement which is useful for creating industry-standard* comma-delimited (or tab-delimited) files, normally called CSV files for "Comma Separated Values."
Note: Although the default delimiter for WRITECD is the comma, it can be set to anything (see MX_CSVDELIM), making the WRITETD variation superfluous and now deprecated.
Individual Elements (first syntax above)
Syntax and operation for the first variation shown above are identical to the PRINT statement, except that WRITECD performs three additional functions which are useful when more than one variable is being output on a line:
| • | automatically inserts a comma between each variable being output |
| • | automatically quotes any string variable which itself contains any of the "likely" delimiter characters (comma, tab, semicolon, colon, quote, apostrophe) or the custom delimiter character if applicable |
| • | strips leading and trailing blanks from any string variable unless accompanied by a formatting mask |
The maximum size of an individual field needing to be enclosed in quotes is 4092 bytes.
Array (second syntax above)
The second syntax variation allows you to output all of the elements in an entire array, without specifying them individually.
This is equivalent to:
WRITECD #ch, ary(1), ary(2), ...
... up to the extent of the array.
Note that the ary() must be created with DIMX (and not MAP), limited to a single dimension, and made up of standard types (X,S,B,F,I; not structures).
Grid (third syntax above)
The third syntax variation outputs an entire grid (multiple rows and columns), starting from row 1; any rows below that are assumed to contain control information and are ignored. In the gridmap(int;varstr;varstr) case, an additional starting row is output containing the column headers. In the caseof gridmap(int;int;varstr), there is no special treatment of column headers, although it is traditional for the first data row to contain the column names.
Examples
WRITECD #1,5.2,"Nov 1, 1998"," abc ","Robert ""Bob"" Scott"
Outputs:
5.2,"Nov 1,1998",abc,"Robert 'Bob' Scott"
Array:
dimx ary(0), s, 20, auto_extend
ary(1) = "one" : ary(2) = "two" : ary(3) = "three"
writecd ary()
Outputs to the screen, as the #ch argument was omitted:
one,two,three
This next example illustrates both inputting an entire CSV file into a gridmap and then outputting it again.
dimx $grid, gridmap(int;varstr;varstr)
open #1, csvin$, input
input csv #1, $grid() ! input entire file into gridmap
close #1
open #2, csvout$, output
writecd #2, $grid() ! write entire gridmap to file
close #2
Comments
WRITECD is essentially the inverse of INPUT CSV, which see. WRITECD will convert any embedded quotes (") within a field into apostrophes ('), to try to be more compatible with other CSV readers.
Also note the procedure for breaking up a single line of CSV output into multiple WRITECD statements:
WRITECD #CH, A, B, C,;
WRITECD #CH, D, E, F
This will output the six variables on one line. Note that that the comma after the C and before the semicolon is required. If you omit it, the D output will immediately follow C with no delimiter. If you omit the semicolon from the first line, then you'll get two lines of output.
The most extreme version of this technique occurs when outputting individual fields in a loop. For example:
FOR %R = 1 TO MAXROW
FOR %C = 1 TO MAXCOL-1
WRITECD #CH, FIELD(%R,%C),;
NEXT %C
WRITECD #CH, FIELD(%R,MAXCOL) ! add last field, terminate line
NEXT %R
* Note that the term "industry standard" is used with a good deal of sarcasm and distaste in this context, since the notion of any such standard is farcical—which is why spreadsheet programs employ elaborate "wizards" to aid in the importing of CSV data, and which despite all kinds of fancy heuristics still have to rely on a complicated user interface for specifying all kinds of options, which if not specified properly, may reduce the results to mush. Readers are hereby advised that if they encounter a CSV file which doesn't read in properly using INPUT CSV, they might need to avail themselves of such a wizard to load the file into a spreadsheet and then re-save it, possibly with a different delimiter. This will hopefully result in a CSV file which has the same ideas about "standard" as does INPUT CSV.
History
2023 September, A-Shell 6.5.1742: The WRITECD ARY() statement now supports numeric array types as well as gridmaps..
2023 February, A-Shell 6.5.1724: Accept type S as well as type X for the array version.
2021 February, A-Shell 6.5.1697: Add WRITECD or WRITETD of an Entire Array.
2011 May, A-Shell 5.1.1216: Support new custom CSV delimiter per MX_CSVDELIM, expand the list of quoted characters. WRITETD is now deprecated, and should not be used; it remains a valid operator only to preserve operations by older code.
