[changeset] strfns.cc: documentation strings, examples and tests

[Thorsten Meyer]

Hi,

attached is a changeset that (imho) improves the documentation strings in 
src/strfns.cc and adds
examples and tests.

regards

Thorsten

# HG changeset patch
# User Thorsten Meyer <address@hidden>
# Date 1227994304 -3600
# Node ID e1720977d365b91e2b0dd511eea3d8c63beea21f
# Parent  6f495ef60d3b852c7433c500ae98e9d690261861
strfns.cc: improve documentation strings, add examples and tests

diff -r 6f495ef60d3b -r e1720977d365 src/ChangeLog
--- a/src/ChangeLog     Fri Nov 28 22:48:01 2008 +0100
+++ b/src/ChangeLog     Sat Nov 29 22:31:44 2008 +0100
@@ -1,3 +1,9 @@
+2008-11-29  Thorsten Meyer  <address@hidden>
+
+        * strfns.cc (Fchar), strfns.cc (Fischar), strfns.cc (Fstrncmp),
+        strfns.cc (Flist_in_columns): Improve documentation strings,
+        add examples and tests.
+        
 2008-11-25  Jaroslav Hajek  <address@hidden>
 
        * ov.cc (octave_value::is_equal): New member function.
diff -r 6f495ef60d3b -r e1720977d365 src/strfns.cc
--- a/src/strfns.cc     Fri Nov 28 22:48:01 2008 +0100
+++ b/src/strfns.cc     Sat Nov 29 22:31:44 2008 +0100
@@ -45,26 +45,26 @@
 @deftypefn {Built-in Function} {} char (@var{x})\n\
 @deftypefnx {Built-in Function} {} char (@var{cell_array})\n\
 @deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})\n\
-Create a string array from a numeric matrix, cell array, or list of\n\
-\n\
-If the argument is a numeric matrix, each element of the matrix is\n\
-converted to the corresponding ASCII character.  For example,\n\
+Create a string array from one or more numeric matrices, character\n\
+matrices or cell arrays.  For numerical input, each element is converted\n\
+to the corresponding ASCII character.  The arguments (and elements of\n\
+cell array(s)) are concatenated vertically.\n\
+The returned values are padded with blanks as needed to make each row\n\
+of the string array have the same length.  Empty strings are not removed.\n\
+For example,\n\
 \n\
 @example\n\
 @group\n\
-char ([97, 98, 99])\n\
-     @result{} \"abc\"\n\
+char ([97, 98, 99], \"\", @{\"98\", \"99\", address@hidden, [\"num\", 
\"bers\"])\n\
+     @result{} [\"abc    \"\n\
+        \"       \"\n\
+        \"98     \"\n\
+        \"99     \"\n\
+        \"d      \"\n\
+        \"numbers\"]\n\
 @end group\n\
 @end example\n\
 \n\
-If the argument is a cell array of strings, the result is a string array\n\
-with each element corresponding to one element of the cell array.\n\
-\n\
-For multiple string arguments, the result is a string array with each\n\
-element corresponding to the arguments.\n\
-\n\
-The returned values are padded with blanks as needed to make each row\n\
-of the string array have the same length.\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -155,7 +155,7 @@
 DEFUN (ischar, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ischar (@var{a})\n\
-Return 1 if @var{a} is a string.  Otherwise, return 0.\n\
+Return 1 if @var{a} is a character array.  Otherwise, return 0.\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -169,6 +169,16 @@
 
   return retval;
 }
+
+/*
+
+%!assert (ischar ("a"), logical (1));
+%!assert (ischar (["ab";"cd"]), logical (1));
+%!assert (ischar ({"ab"}), logical (0));
+%!assert (ischar (1), logical (0));
+%!error <Invalid call to ischar.*> ischar ();
+
+ */
 
 DEFUN (strcmp, args, ,
   "-*- texinfo -*-\n\
@@ -747,6 +757,18 @@
   return retval;
 }
 
+/*
+%!error <Invalid call to strncmp.*> strncmp ();
+%!error <Invalid call to strncmp.*> strncmp ("abc", "def");
+%!assert (strncmp ("abce", "abc", 3) == 1)
+%!assert (strncmp (100, 100, 1) == 0)
+%!assert (all (strncmp ("abce", {"abcd", "bca", "abc"}, 3) == [1, 0, 1]))
+%!assert (all (strncmp ("abc",  {"abcd", "bca", "abc"}, 4) == [0, 0, 0]))
+%!assert (all (strncmp ({"abcd", "bca", "abc"},"abce", 3) == [1, 0, 1]))
+%!assert (all (strncmp ({"abcd", "bca", "abc"},{"abcd", "bca", "abe"}, 3) == 
[1, 1, 0]))
+*/
+
+
 DEFUN (list_in_columns, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} list_in_columns (@var{arg}, @var{width})\n\
@@ -754,6 +776,28 @@
 columns with an overall maximum width of @var{width}.  The argument\n\
 @var{arg} must be a cell array of character strings or a character array.\n\
 If @var{width} is not specified, the width of the terminal screen is used.\n\
+Newline characters are used to break the lines in the output string.\n\
+For example:\n\
+\n\
address@hidden
address@hidden
+list_in_columns (@{\"abc\", \"def\", \"ghijkl\", \"mnop\", \"qrs\", \"tuv\"@}, 
20)\n\
+     @result{} ans = abc     mnop\n\
+            def     qrs\n\
+            ghijkl  tuv\n\
+\n\
+whos ans\n\
+     @result{}\n\
+     Variables in the current scope:\n\
+\n\
+       Attr Name        Size                     Bytes  Class\n\
+       ==== ====        ====                     =====  =====\n\
+            ans         1x37                        37  char\n\
+\n\
+     Total is 37 elements using 37 bytes\n\
address@hidden group\n\
address@hidden example\n\
+\n\
 @seealso{terminal_size}\n\
 @end deftypefn")
 {
@@ -794,6 +838,20 @@
 }
 
 /*
+%!error <Invalid call to list_in_columns.*> list_in_columns ();
+%!error <Invalid call to list_in_columns.*> list_in_columns (["abc", "def"], 
20, 2);
+%!error <invalid conversion from string to real scalar.*> list_in_columns 
(["abc", "def"], "a");
+%!test
+%!  input  = {"abc", "def", "ghijkl", "mnop", "qrs", "tuv"};
+%!  result = "abc     mnop\ndef     qrs\nghijkl  tuv\n";
+%!  assert (list_in_columns (input, 20) == result);
+%!test
+%!  input  = ["abc"; "def"; "ghijkl"; "mnop"; "qrs"; "tuv"];
+%!  result = "abc     mnop  \ndef     qrs   \nghijkl  tuv   \n";
+%!  assert (list_in_columns (input, 20) == result);
+*/
+
+/*
 ;;; Local Variables: ***
 ;;; mode: C++ ***
 ;;; End: ***