paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-10 01:28:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: LazUtils/lcsvutils. Updates topic content.

Browse Source
This commit is contained in:
dsiders 2021-09-27 20:38:36 +01:00
parent a8a398e553
commit 1d0d348cf6
1 changed files with 91 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/xml/lazutils/lcsvutils.xml
View File

@ -11,16 +11,32 @@
Contains routines used to read and process Comma-separated values from a file or a stream.
</short>
<descr>
<file>lcsvutils.pas</file> 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.
<p>
<file>lcsvutils.pas</file> contains routines used to read and process Comma-separated values from a file or a stream. It is used in the implementation of the <file>LazUtils</file> package and the <var>TGrid</var> component.
</p>
<p>
This file is part of the <file>LazUtils</file> package.
</p>
</descr>
<!-- procedure type Visibility: default -->
<element name="TCSVRecordProc">
<short>Procedure used to read and process comma-separated values.</short>
<short>Defines a procedure used to process field values.</short>
<descr>
TCSVProc is a nested procedure used when reading and processing comma-separated values. A TCSVProc 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 CSV of data has been read from its data source and separated into individual field values.
<p>
<var>TCSVRecordProc</var> defines a nested procedure type used when reading and processing delimited field values. A TCSVRecordProc reference is passed as an argument to the <var>LoadFromCSVFile</var> and <var>LoadFromCSVStream</var> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso></seealso>
<seealso>
<link id="LoadFromCSVFile"/>
<link id="LoadFromCSVStream"/>
</seealso>
</element>
<element name="TCSVRecordProc.Fields">
<short>TStringList used to store comma-separated field values.</short>
@ -29,9 +45,17 @@
<element name="TCSVEncoding">
<short>Represents character encodings used for values in CSV data.</short>
<descr>
TCSVEncoding is an enumerated type which represents character encodings that can be used for CSV data.
<p>
<var>TCSVEncoding</var> 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 <var>LoadFromCSVFile</var> and <var>LoadFromCSVStream</var> routines.
</p>
<p>
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.
</p>
</descr>
<seealso></seealso>
<seealso>
<link id="LoadFromCSVFile"/>
<link id="LoadFromCSVStream"/>
</seealso>
</element>
<element name="TCSVEncoding.ceAuto">
<short>Auto-detects character encoding applied to the CSV data.</short>
@ -50,15 +74,51 @@
<short>
Loads and processes comma-separated values from the specified stream.
</short>
<descr></descr>
<errors></errors>
<seealso></seealso>
<descr>
<p>
<var>LoadFromCSVStream</var> is a procedure used to read and process delimited values from the stream specified in <var>AStream</var>.
</p>
<p>
The procedure name is actually a misnomer; the routine uses the value in <var>ADelimiter</var> 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.
</p>
<p>
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).
</p>
<remark>
The position in AStream is <b>not</b> 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.
</remark>
<p>
The value in <var>CSVEncoding</var> indicates the encoding for the byte values read from the stream. <var>ceAuto</var> 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.
</p>
<p>
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.
</p>
<p>
LoadFromCSVStream calls the procedure passed in the <var>AProc</var> 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.
</p>
<p>
No actions are performed in LoadFromCSVStream when AProc has not been assigned.
</p>
<p>
Use the <var>LoadFromCSVFile</var> procedure to process delimited values in a specified file name.
</p>
<p>
LoadFromCSVStream is called from the <var>LoadFromCSVFile</var> routine, and used in the implementation of the LoadFromCSVFile and LoadFromCSVStream methods in <var>TCustomStringGrid</var>. For database-aware applications, consider the <var>TCSVDataset</var> class found in the <file>csvdataset</file> unit from the FCL; also available on the Data Access tab for the Lazarus IDE component palette.
</p>
</descr>
<seealso>
<link id="LoadFromCSVFile"/>
<link id="TCSVEncoding"/>
<link id="TCSVRecordProc"/>
<link id="#lcl.grids.TCustomStringGrid.LoadFromCSVFile">TCustomStringGrid.LoadFromCSVFile</link>
<link id="#lcl.grids.TCustomStringGrid.LoadFromCSVStream">TCustomStringGrid.LoadFromCSVStream</link>
</seealso>
</element>
<element name="LoadFromCSVStream.AStream">
<short>TStream instance containing the CSV data.</short>
</element>
<element name="LoadFromCSVStream.AProc">
<short>Routine used to load and process records in the CSV data.</short>
<short>Routine used to load and process lines in the CSV data.</short>
</element>
<element name="LoadFromCSVStream.ADelimiter">
<short>Delimiter used to separate fields in the CSV data.</short>
@ -69,17 +129,33 @@
<element name="LoadFromCSVFile">
<short>
Loads and process comma-separated valued from the specified file.
Loads and processes comma-separated values from the specified file.
</short>
<descr></descr>
<errors></errors>
<seealso></seealso>
<descr>
<p>
<var>LoadFromCSVFile</var> is a procedure used to read and process delimited values from the file specified in the <var>AFilename</var> argument.
</p>
<p>
The procedure name is actually a misnomer; the routine uses the value in <var>ADelimiter</var> 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.
</p>
<p>
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 <var>AProc</var>. Internally, it creates a temporary <var>TFileStream</var> instance for the specified file name. The <var>LoadFromCSVStream</var> routine is called to read and apply the content using the arguments in <var>AProc</var>, <var>ADelimiter</var>, and <var>CSVEncoding</var>.
</p>
<p>
See <link id="#lazutils.lcsvutils.LoadFromCSVStream">LoadFromCSVStream</link> for more information about the arguments passed to the routine, and how the procedure is implemented.
</p>
</descr>
<seealso>
<link id="LoadFromCSVStream"/>
<link id="TCSVEncoding"/>
<link id="TCSVRecordProc"/>
</seealso>
</element>
<element name="LoadFromCSVFile.aFilename">
<short>File name which contains the CSV data.</short>
</element>
<element name="LoadFromCSVFile.AProc">
<short>Routine used to load and process records in the CSV data.</short>
<short>Routine used to load and process lines in the CSV data.</short>
</element>
<element name="LoadFromCSVFile.ADelimiter">
<short>Delimiter used to separate fields in the CSV data.</short>