changeset 21362:1bb9a34011d1

doc: Specify that only numeric data are allowed for delimited file I/O (bug #46248). * csvread.m, csvwrite.m, dlmread.cc (Fdlmread), dlmwrite.m: Update docstrings.
author Philip Nienhuis <prnienhuis@users.sf.net>
date Sat, 12 Dec 2015 16:18:57 +0100
parents 9ca194f7a858
children 8cfd1b47d49f
files libinterp/corefcn/dlmread.cc scripts/io/csvread.m scripts/io/csvwrite.m scripts/io/dlmwrite.m
diffstat 4 files changed, 29 insertions(+), 23 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/dlmread.cc	Fri Feb 26 13:13:21 2016 -0500
+++ b/libinterp/corefcn/dlmread.cc	Sat Dec 12 16:18:57 2015 +0100
@@ -163,28 +163,30 @@
 @deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{r0}, @var{c0})\n\
 @deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{range})\n\
 @deftypefnx {} {@var{data} =} dlmread (@dots{}, \"emptyvalue\", @var{EMPTYVAL})\n\
-Read the matrix @var{data} from a text file which uses the delimiter\n\
+Read numeric data from the text file @var{file} which uses the delimiter\n\
 @var{sep} between data values.\n\
 \n\
 If @var{sep} is not defined the separator between fields is determined from\n\
 the file itself.\n\
 \n\
-Given two scalar arguments @var{r0} and @var{c0}, these define the starting\n\
-row and column of the data to be read.  These values are indexed from zero,\n\
-such that the first row corresponds to an index of zero.\n\
+The optional scalar arguments @var{r0} and @var{c0} define the starting row\n\
+and column of the data to be read.  These values are indexed from zero,\n\
+i.e., the first data row corresponds to an index of zero.\n\
 \n\
-The @var{range} parameter may be a 4-element vector containing the upper\n\
-left and lower right corner @code{[@var{R0},@var{C0},@var{R1},@var{C1}]}\n\
-where the lowest index value is zero.  Alternatively, a spreadsheet style\n\
-range such as @qcode{\"A2..Q15\"} or @qcode{\"T1:AA5\"} can be used.  The\n\
+The @var{range} parameter specifies exactly which data elements are read.\n\
+The first form of the parameter is a 4-element vector containing the upper\n\
+left and lower right corners @code{[@var{R0},@var{C0},@var{R1},@var{C1}]}\n\
+where the indices are zero-based.  Alternatively, a spreadsheet style\n\
+form such as @qcode{\"A2..Q15\"} or @qcode{\"T1:AA5\"} can be used.  The\n\
 lowest alphabetical index @qcode{'A'} refers to the first column.  The\n\
 lowest row index is 1.\n\
 \n\
-@var{file} should be a filename or file id given by @code{fopen}.  In the\n\
+@var{file} should be a filename or a file id given by @code{fopen}.  In the\n\
 latter case, the file is read until end of file is reached.\n\
 \n\
 The @qcode{\"emptyvalue\"} option may be used to specify the value used to\n\
-fill empty fields.  The default is zero.\n\
+fill empty fields.  The default is zero.  Note that any non-numeric values,\n\
+such as text, are also replaced by the @qcode{\"emptyvalue\"}.\n\
 @seealso{csvread, textscan, textread, dlmwrite}\n\
 @end deftypefn")
 {
--- a/scripts/io/csvread.m	Fri Feb 26 13:13:21 2016 -0500
+++ b/scripts/io/csvread.m	Sat Dec 12 16:18:57 2015 +0100
@@ -19,7 +19,10 @@
 ## -*- texinfo -*-
 ## @deftypefn  {} {@var{x} =} csvread (@var{filename})
 ## @deftypefnx {} {@var{x} =} csvread (@var{filename}, @var{dlm_opts})
-## Read the comma-separated-value file @var{filename} into the matrix @var{x}.
+## Read the comma-separated-value (CSV) file @var{filename} into the matrix
+## @var{x}.
+##
+## Note: only CSV files containing numeric data can be read.
 ##
 ## This function is equivalent to
 ##
@@ -27,7 +30,7 @@
 ## @var{x} = dlmread (@var{filename}, "," , @dots{})
 ## @end example
 ##
-## @seealso{csvwrite, dlmread, dlmwrite}
+## @seealso{dlmread, textread, textscan, csvwrite, dlmwrite}
 ## @end deftypefn
 
 function x = csvread (filename, varargin)
--- a/scripts/io/csvwrite.m	Fri Feb 26 13:13:21 2016 -0500
+++ b/scripts/io/csvwrite.m	Sat Dec 12 16:18:57 2015 +0100
@@ -19,8 +19,8 @@
 ## -*- texinfo -*-
 ## @deftypefn  {} {} csvwrite (@var{filename}, @var{x})
 ## @deftypefnx {} {} csvwrite (@var{filename}, @var{x}, @var{dlm_opts})
-## Write the matrix @var{x} to the file @var{filename} in
-## @w{comma-separated-value} format.
+## Write the numeric matrix @var{x} to the file @var{filename} in
+## @w{comma-separated-value} (CSV) format.
 ##
 ## This function is equivalent to
 ##
--- a/scripts/io/dlmwrite.m	Fri Feb 26 13:13:21 2016 -0500
+++ b/scripts/io/dlmwrite.m	Sat Dec 12 16:18:57 2015 +0100
@@ -22,12 +22,14 @@
 ## @deftypefnx {} {} dlmwrite (@var{file}, @var{M}, @var{key}, @var{val} @dots{})
 ## @deftypefnx {} {} dlmwrite (@var{file}, @var{M}, "-append", @dots{})
 ## @deftypefnx {} {} dlmwrite (@var{fid}, @dots{})
-## Write the matrix @var{M} to the named file using delimiters.
+## Write the numeric matrix @var{M} to the text file @var{file} using a 
+## delimiter.
 ##
-## @var{file} should be a filename or writable file ID given by @code{fopen}.
+## @var{file} should be a filename or a writable file ID given by @code{fopen}.
 ##
 ## The parameter @var{delim} specifies the delimiter to use to separate values
-## on a row.
+## on a row.  If no delimiter is specified the comma character @samp{,} is
+## used.
 ##
 ## The value of @var{r} specifies the number of delimiter-only lines to add to
 ## the start of the file.
@@ -48,12 +50,11 @@
 ## See @var{delim} above.
 ##
 ## @item @qcode{"newline"}
-## The character(s) to use to separate each row.  Three special cases exist
-## for this option.  @qcode{"unix"} is changed into
-## @qcode{"@xbackslashchar{}n"}, @qcode{"pc"} is changed into
-## @qcode{"@xbackslashchar{}r@xbackslashchar{}n"}, and @qcode{"mac"} is
-## changed into @qcode{"@xbackslashchar{}r"}.  Any other value is used
-## directly as the newline separator.
+## The character(s) to separate each row.  Three special cases exist for this
+## option.  @qcode{"unix"} is changed into @qcode{"@xbackslashchar{}n"},
+## @qcode{"pc"} is changed into @qcode{"@xbackslashchar{}r@xbackslashchar{}n"},
+## and @qcode{"mac"} is changed into @qcode{"@xbackslashchar{}r"}.  Any other
+## value is used directly as the newline separator.
 ##
 ## @item @qcode{"roffset"}
 ## See @var{r} above.