[q-lang-cvs] q-csv README,1.8,1.9

[Albert G. <ag...@us...>]

Update of /cvsroot/q-lang/q-csv
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv9772

Modified Files:
	README 
Log Message:
overhaul the description of the primary interface functions and error handling

Index: README
===================================================================
RCS file: /cvsroot/q-lang/q-csv/README,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** README	14 Jan 2008 04:35:30 -0000	1.8
--- README	14 Jan 2008 06:43:09 -0000	1.9
***************
*** 28,37 ****
  
  - freadcsv_data converts non-quoted numeric fields to integer or double values
!   automatically. Invalidly formatted CSV strings force the invocation of a
!   'csv_error MSG' rule.
    fwritecsv_data writes integer or double values to non-quoted fields. The 
    handling of quoted or non-quoted fields is automatic. Fields with types
!   other than floats, integers or strings force the invocation of a 
!   'csv_error MSG' rule.
      
  - freadcsv_string and fwritecsv_string read all fields as strings 
--- 28,37 ----
  
  - freadcsv_data converts non-quoted numeric fields to integer or double values
!   automatically. Invalidly formatted CSV causes return of a 'csv_error MSG'
!   term (see NOTES below).
    fwritecsv_data writes integer or double values to non-quoted fields. The 
    handling of quoted or non-quoted fields is automatic. Fields with types
!   other than floats, integers or strings cause return of a 'csv_error MSG'
!   term (see NOTES below).
      
  - freadcsv_string and fwritecsv_string read all fields as strings 
***************
*** 39,46 ****
    fwritecsv_string writes all values as quoted fields.
  
! The primary interface function fread_csvstr reads a string from a file
! with embedded end of lines. It does not check for a valid record. The two
! other primary interface functions, csvstr_to_tuple and tuple_to_csvstr
! convert CSV formatted strings to tuples and vice versa.
  
  The routines described above read/write one record at a time. Additional
--- 39,54 ----
    fwritecsv_string writes all values as quoted fields.
  
! The above routines are defined in terms of the following primary interface
! functions fread_csvstr, csvstr_to_tuple and tuple_to_csvstr:
! 
! - fread_csvstr reads a single CSV record from a file. This essentially works
!   like freads, but handles quoted newlines embedded in a field value. Note
!   that fread_csvstr does *not* verify that the string actually conforms to CSV
!   syntax.
! 
! - csvstr_to_tuple and tuple_to_csvstr convert CSV formatted strings to tuples
!   and vice versa. These functions check for correct CSV syntax and proper
!   field values, respectively, and return a 'csv_error MSG' term in case of an
!   error condition (see NOTES below).
  
  The routines described above read/write one record at a time. Additional
***************
*** 51,64 ****
  NOTES
  
! - The read functions fail when reading records that do not abide by the RFC
!   4180 rules.
  
! - The write functions fail when field types other than strings, integers, or
!   floats are given.
  
! - MS Excel files should be read using _string variants as Excel does not quote
!   values such as 0004. These types of values will be converted to integers and
!   the leading significant 0s will be lost. Significant leading or trailing 
!   space may likewise be lost without using the _string variant.
  
  TO DO
--- 59,76 ----
  NOTES
  
! - Errors in the conversion routines (input strings that do not abide by the
!   RFC 4180 rules; records containing field types other than strings, integers
!   and floats) cause a special 'csv_error MSG' term to be returned, where MSG
!   is a string describing the particular error. To handle error conditions,
!   your application should either check for these, or define csv_error to
!   directly handle the error in some way (e.g., provide a default value, or
!   raise an exception). For instance:
  
!   csv_error MSG = throw MSG;
  
! - MS Excel files should be read using the _string variants as Excel does not
!   quote values such as 0004. These types of values will be converted to
!   integers and the leading significant 0s will be lost. Significant leading or
!   trailing space may likewise be lost without using the _string variant.
  
  TO DO