# HG changeset patch
# User Guillaume Flandin <guillaume.offline@gmail.com>
# Date 1559666698 25200
# Node ID f26b13c80e45beb3597c943b08923128c0ad4253
# Parent  142084841f23e5436b9cb6131ea4fe483460d89a
Implement new function "newline" for Matlab compatibility (bug #56419).

* NEWS: Announce new function.

* strfns.cc (Fnewline): New function to create the "\n" character.

* strings.txi: Add DOCSTRING entry to manual.

diff -r 142084841f23 -r f26b13c80e45 NEWS
--- a/NEWS	Tue Jun 04 09:23:09 2019 -0700
+++ b/NEWS	Tue Jun 04 09:44:58 2019 -0700
@@ -59,6 +59,13 @@
   of Octave, some lines and markers will appear 4/3 larger.
 
 
+### Alphabetical list of new functions added in Octave 6
+
+- `lightangle`
+- `newline`
+- `verLessThan`
+
+
 ### Deprecated functions and properties
 
 The following functions and properties have been deprecated in Octave 6
@@ -113,13 +120,6 @@
   `uitable`            | `fontweight`              | `"demi"` and `"light"`
 
 
-
-### Alphabetical list of new functions added in Octave 6
-
-- `lightangle`
-- `verLessThan`
-
-
 ### Old release news
 
 - [Octave 5.x](etc/NEWS.5)
diff -r 142084841f23 -r f26b13c80e45 doc/interpreter/strings.txi
--- a/doc/interpreter/strings.txi	Tue Jun 04 09:23:09 2019 -0700
+++ b/doc/interpreter/strings.txi	Tue Jun 04 09:44:58 2019 -0700
@@ -248,7 +248,12 @@
 the overhead of a function call and the input validation of the associated
 function.
 
-Nevertheless, there are several other functions for concatenating string
+The @code{newline} function can be used to join strings such that they appear
+as multiple lines of text when displayed.
+
+@DOCSTRING(newline)
+
+In addition, there are several other functions for concatenating string
 objects which can be useful in specific circumstances: @code{char},
 @code{strvcat}, @code{strcat}, and @code{cstrcat}.  Finally, the general
 purpose concatenation functions can be used: see @ref{XREFcat,,cat},
diff -r 142084841f23 -r f26b13c80e45 libinterp/corefcn/strfns.cc
--- a/libinterp/corefcn/strfns.cc	Tue Jun 04 09:23:09 2019 -0700
+++ b/libinterp/corefcn/strfns.cc	Tue Jun 04 09:44:58 2019 -0700
@@ -1030,6 +1030,42 @@
 %!assert (unicode_idx (["aäou"; "Ä∞"]), [1 2 2 3 4; 5 5 6 6 6]);
 */
 
+DEFUN (newline, args, ,
+       doc: /* -*- texinfo -*-
+@deftypefn {} {} newline
+Return the character corresponding to a newline.
+
+This is equivalent to @qcode{"@xbackslashchar{}n"}.
+
+Example Code
+
+@example
+@group
+joined_string = [newline "line1" newline "line2"]
+@result{}
+line1
+line2
+@end group
+@end example
+
+@seealso{strcat, strjoin, strsplit}
+@end deftypefn */)
+{
+  if (args.length () != 0)
+  print_usage ();
+ 
+  static octave_value_list retval = ovl ("\n");
+ 
+  return retval;
+}
+
+/*
+%!assert (newline (), "\n")
+
+%!error newline (1)
+%!error [a, b] = newline ();
+*/
+
 DEFUN (list_in_columns, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn {} {} list_in_columns (@var{arg}, @var{width}, @var{prefix})