Contains routines used to read and process Comma-separated values from a file or a stream.

lcsvutils.pas contains routines used to read and process Comma-separated values from a file or a stream. It is used in the implementation of the LazUtils package and the TGrid component.

This file is part of the LazUtils package.

Defines a procedure used to process field values.

TCSVRecordProc defines a nested procedure type used when reading and processing delimited field values. A TCSVRecordProc reference is passed as an argument to the LoadFromCSVFile and LoadFromCSVStream routines. Applications must create a procedure that performs actions required when a line of data has been read from its source and separated into individual field values.

The Fields argument is a TStringList instance which contains the field values converted and parsed in the calling routine. Each field value exists on a separate line in the Fields argument. A field with no value is represented as an empty line in the TStringList instance.

An application must implement a procedure using the signature in TCSVRecordProc, and pass its address as an argument to the LoadFromCSVFile or LoadFromCSVStream routine. The procedure is responsible for performing any actions needed for the values in Fields.

TStringList used to store comma-separated field values.
Represents character encodings used for values in CSV data.

TCSVEncoding is an enumerated type which represents character encodings used for CSV data. A value from the enumeration can be passed as an argument to the LoadFromCSVFile and LoadFromCSVStream routines.

A value from the enumeration is passed as an argument to the LoadFromCSVFile and LoadFromCSVStream routines. It identifies the character encoding for the byte values read from the data source, and determines the actions needed to convert the byte values to the UTF-8 encoding needed for the String type.

Auto-detects character encoding applied to the CSV data.
CSV data uses the UTF-8 encoding.
CSV data uses the UTF-16 encoding.
CSV data uses the UTF-16 Big-Endian encoding.
Loads and processes comma-separated values from the specified stream.

LoadFromCSVStream is a procedure used to read and process delimited values from the stream specified in AStream.

The procedure name is actually a misnomer; the routine uses the value in ADelimiter as the delimiter between field values. It does not have to be a Comma (,) character. Comma is, however, the default value for the ADelimiter argument.

LoadFromCSVStream reads lines of data from the stream, and calls nested routines to handle character encodings for the byte values. Each line is terminated with one or more line-ending characters (#13, #10).

The position in AStream is not maintained in the routine. Processing is started using the stream position on entry. The stream position on exit is after the last line of text successfully processed from the stream, and is normally at the end of the stream.

The value in CSVEncoding indicates the encoding for the byte values read from the stream. ceAuto is the default value for the argument, and indicates that the encoding is auto-detected in the routine using the BOM (Byte Order Mark) at the beginning of the processed byte values. The nested routines convert non-UTF-8 encodings to the UTF-8 encoding needed for the native String type.

Leading spaces in a line of text read from the stream are discarded. Field values in the line of text can be enclosed in Quotation (") marks if the delimiter character appears in the field content. Nested Quotation marks are allowed when used in a balanced pair.

LoadFromCSVStream calls the procedure passed in the AProc argument to process and apply each delimited field value from the line of text read from the stream. Field values are stored in a TStringList instance that is passed as argument to the routine in AProc. An application must implement the procedure passed in the argument to perform any actions needed for the field values.

No actions are performed in LoadFromCSVStream when AProc has not been assigned.

Use the LoadFromCSVFile procedure to process delimited values in a specified file name.

LoadFromCSVStream is called from the LoadFromCSVFile routine, and used in the implementation of the LoadFromCSVFile and LoadFromCSVStream methods in TCustomStringGrid. For database-aware applications, consider the TCSVDataset class found in the csvdataset unit from the FCL; also available on the Data Access tab for the Lazarus IDE component palette.

TCustomStringGrid.LoadFromCSVFile TCustomStringGrid.LoadFromCSVStream
TStream instance containing the CSV data.
Routine used to load and process lines in the CSV data.
Delimiter used to separate fields in the CSV data.
Character encoding used for the CSV data.
Loads and processes comma-separated values from the specified file.

LoadFromCSVFile is a procedure used to read and process delimited values from the file specified in the AFilename argument.

The procedure name is actually a misnomer; the routine uses the value in ADelimiter as the delimiter between field values. It does not have to be a Comma (,) character. Comma is, however, the default value for the ADelimiter argument.

LoadFromCSVFile reads lines of data from the file, and converts the encoded byte values to fields which are processed and applied using the procedure in AProc. Internally, it creates a temporary TFileStream instance for the specified file name. The LoadFromCSVStream routine is called to read and apply the content using the arguments in AProc, ADelimiter, and CSVEncoding.

See LoadFromCSVStream for more information about the arguments passed to the routine, and how the procedure is implemented.

File name which contains the CSV data.
Routine used to load and process lines in the CSV data.
Delimiter used to separate fields in the CSV data.
Character encoding used for the CSV data.