Mercurial > jwe > octave
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.