csv.h


Headers Index Help      Within this page: Functions Constants Variables


Overview

CSV library functions.

This library reads and writes comma separated variable formatted text files. When the file is read, all fields are decoded into strings. A number of field output functions are provided to allow strings, integers and real numbers to be output. Alternatively, it can accept strings containing comma separated fields for decoding and it can assemble strings of comma separated fields for use elsewhere in the program.

The rules defining a validly formatted csv file are:

There are a number of possible quote modes. Changes to the quote mode only affect output and take effect immediately. The quote modes are:

The NEVER quote mode is intended to be combined with a nonstandard separator to allow the creating of files suitable for input to database loaders and to the creation of tab-separated files.

Many csv files may be open at once. Each file has a CSV control block that contains the resources and settings applicable to the file. The control block will exist if csvopen() was able to allocate and initialise memory for it. All other functions can be called if the control block pointer is NULL or points to a valid control block, so the pointer should be initialised to NULL when it is declared. Functions passed a NULL control block pointer will return an error code.

This package provides the ability to change both field and line delimiters. It also provides control over the amount of field quoting to be applied to the file. All changes to run conditions should be made by using the csvsetxxxx() functions. All settings are specific to a single file and are stored in the CSV control block. Internal fields within the control block are subject to change without notice. Because of this they should not be accessed directly and must not be modified by the calling program except via the functions provided for this purpose.

Functions that return an integer but have no explicit meaning described for the return value should be assumed to return zero for success and a negative value if an error has occurred.

In all cases a call to csvgeterr() after another function will return zero if no error ocurred and a negative value if an error has ocurred. This can be translated into a displayable string by calling csvgeterrtext(). The current error status is held in a hidden global variable that is common to all active csv files, so it is good practise to check the error status, with csvgeterr() if necessary, after every csv function call and to translate and report the error immediately.

Compilation

The calling programs should include csv.h and must be linked using -lenviron.

environ - C programming support functions
Copyright (C) 2005 Martin C Gregorie

This program is free software; you can redistribute it and/or modify it under the terms of the Lesser GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the Lesser GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Contact Martin Gregorie at martin@gregorie.org

Functions


csvclose

#include <csv.h>

CSV *csvclose(CSV *cb);

Close a CSV file and delete the CSV control block, releasing the space it occupies. Returns null.

In: csv.c

Return to the top

csvgeterr

#include <csv.h>

int csvgeterr(void);

Retrieve the current error code. Returns zero if there is no error. Errors are positive if they are standard system error codes and negative integers if they are specific to this library.

In: csv.c

Return to the top

csvgeterrtext

#include <csv.h>

char *csvgeterrtext(void);

Return a pointer to a string containing a textual description of the current error. This always returns a string pointer, but the string is empty if there was no current error.

In: csv.c

Return to the top

csvgetfield

#include <csv.h>

char *csvgetfield(CSV *f, int n);

Returns a pointer to the the contents of the nth field in the last line read by csvgetline(). Fields are numbered from 0. It returns NULL if called before csvgetline(), n<0 or is beyond the last field. Fields are separated by the current separator character. Fields may be surrounded by "..."; such quotes are removed. Within "...", "" is replaced by a single double quote mark and the separator character has no special meaning. In unquoted fields, quotes are regular characters. There can be an arbitrary number of fields of any length; NULL is returned if memory cannot be obtained to hold the current field or if the attempt to unpack the field fails. Fields must be treated as read-only storage; the caller must make a copy to preserve or change the field contents.

In: csv.c

Return to the top

csvgetline

#include <csv.h>

char *csvgetline(CSV *f);

This reads one line from the open file f. It assumes that all lines are terminated by carriage return, linefeed or EOF. It returns a pointer to the line with the terminator removed or NULL if EOF was encountered. The line may be of any arbitrary length. NULL will be returned if the memory limit is exceeded while the line is being read. The line must be treated as read-only storage. The caller must make a copy to preserve or change its content.

In: csv.c

Return to the top

csvgetn

#include <csv.h>

int csvgetn(CSV *f);

Returns the number of fields in the last line read by csvgetline(). It returns -1 if it is called before csvgetline() is called for the first time. Returns the number of fields in the last line read. Negative values indicate that an error has occurred.

In: csv.c

Return to the top

csvopen

#include <csv.h>

CSV *csvopen(char *name, char *mode);

Open a file for csv use, returning a CSV control block pointer that is specific to the file that has just been opened. Name is the file name, mode the file opening mode, which must be "r" or "w".

If the file name is null, stdin or stdout is opened depending on whether the opening mode is "r" or "w".

If the file name is null and the mode is "s" no file will be opened because it is assumed that input and output will be to strings.

Returns a pointer to the CSV control block on success and null if an error ocurred.

In: csv.c

Return to the top

csvputint

#include <csv.h>

int csvputint(CSV *f, int val);

Appends val to the current line as a signed numeric string. If it is not the first field on the line it is preceeded by a separator character. Quoting depends on the current quote mode:

Signals an error if the separator character is found in the numeric string if the quote mode is NORMAL, NEVER or MINIMAL. Returns zero if the field is successfully processed and non-zero if errors were encountered.

In: csv.c

Return to the top

csvputline

#include <csv.h>

int csvputline(CSV *f);

Write the current output line to the file after appending the current newline character(s). The line buffer is cleared. Returns 0 if successful and a non-zero value otherwise.

In: csv.c

Return to the top

csvputreal

#include <csv.h>

int csvputreal(CSV *f, double val);

Identical with csvputint() except that a real number is output.

In: csv.c

Return to the top

csvputstr

#include <csv.h>

int csvputstr(CSV *f, char *val);

Appends val to the current line. If it is not the first field on the line it is preceeded by a separator character. Quoting depends on the current quote mode:

Returns zero if the field is successfully processed and non-zero if errors were encountered.

In: csv.c

Return to the top

csvsetdebug

#include <csv.h>

void csvsetdebug(int d);

Set CSV library debugging level. Debugging is global to all csv files and may be set at any time. Default is zero (no debugging), 1 traces all csv library calls, and 2 or greater traces internal function operations.

Debugging level 1 is intended as a debugging aid for the calling program. Higher debugging levels are used to debug the internals of this package.

In: csv.c

Return to the top

csvsetnl

#include <csv.h>

int csvsetnl(CSV *f, int nlcode);

Set the type of line separator to be output. The value must be one of the following:

The default is LF, which is the normal line delimiter for the system your program is running on. Returns zero if the change succeeded and non-zero if it failed. The change takes effect immediately.

In: csv.c

Return to the top

csvsetquote

#include <csv.h>

int csvsetquote(CSV *f, int quotemode);

Set the quote mode to one of the defined values. The quotation mode is one of the following:

Returns zero if this is successful and non-zero if the requested quote mode is invalid. The change takes effect immediately.

In: csv.c

Return to the top

csvsetsep

#include <csv.h>

int csvsetsep(CSV *f, int sepchar);

Change the field separator character. Returns zero if this is successful and non-zero if the requested separator character is invalid. Valid separators are any printable ASCII character except newline, carriage return or double quote. The change takes effect immediately.

In: csv.c

Return to the top

csvstrin

#include <csv.h>

int csvstrin(CSV *f, char *str);

Input a string containing a list of csv fields to be decoded. The string is terminated by a null and should not contain any newline characters. The string is stored internally and parsed into fields. Returns zero on success and non-zero if errors were encountered.

In: csv.c

Return to the top

csvstrout

#include <csv.h>

char *csvstrout(CSV *f);

Return a string containing a set of csv fields that has just been built. The string will be null terminated and will not contain a trailing newline. csvstrprep() should be called before a set of fields are added to the output string. Returns null if errors were encountered.

In: csv.c

Return to the top

csvstrprep

#include <csv.h>

int csvstrprep(CSV *f);

Prepare a receiving area to receive a string to be filled with csv fields for later return by csvstrout(). The separator and quoting control values are reset to their default values. Returns zero if the field was prepared successfully and non-zero if errors were encountered.

In: csv.c

Return to the top

Constants

line_delimiters
enum line_delimiters
{
   CRLF    = 1,
   CR      = 2,
   LF      = 3
};
quote_modes
enum quote_modes
{
   NORMAL  = 1,
   ALWAYS  = 2,
   NEVER   = 3,
   MINIMAL = 4
};

Return to the top

Variable type definitions

CSV
typedef struct 
{
   FILE *f;
   char *name;
   char *line;
   char *sline;
   char *oline;
   char **field;
   int  sused;
   int  maxline;
   int  maxfield;
   int  maxoline;
   int  outptr;
   int  nfield;
   int  quotemode;
   char sepchar[2];
   char nl[3];
} CSV;

Return to the top