matrix docs

diff --git a/doc/matrices.texi b/doc/matrices.texi
index 459940823f8c1e5edc998e91111796fa77f48b16..5c03eb79c3748841d898cfb43aa298c434fe2595 100644 (file)
--- a/doc/matrices.texi
+++ b/doc/matrices.texi
@@ -2018,6 +2018,19 @@ Each expression on @code{DO IF} and @code{ELSE IF} must evaluate to a
 scalar.  Positive scalars are considered to be true, and scalars that
 are zero or negative are considered to be false.
 
 scalar.  Positive scalars are considered to be true, and scalars that
 are zero or negative are considered to be false.
 

+The following matrix language fragment sets @samp{b} to the term
+following @samp{a} in the
+@url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler
+sequence}:
+
+@example
+DO IF MOD(a, 2) = 0.
+  COMPUTE b = TRUNC(a &** (1/2)).
+ELSE.
+  COMPUTE b = TRUNC(a &** (3/2)).
+END IF.
+@end example
+

 @node Matrix LOOP and BREAK Commands
 @subsection The @code{LOOP} and @code{BREAK} Commands
 
 @node Matrix LOOP and BREAK Commands
 @subsection The @code{LOOP} and @code{BREAK} Commands
 


@@ -2057,12 +2070,61 @@ The optional @code{IF} on @code{END LOOP} is evaluated after each
 iteration through the loop body.  If its expression, which must
 evaluate to a scalar, is zero or negative, then the loop terminates.
 
 iteration through the loop body.  If its expression, which must
 evaluate to a scalar, is zero or negative, then the loop terminates.
 

+The following computes and prints @math{l(n)}, whose value is the
+number of steps in the
+@url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler sequence}
+for @math{n}, for @math{n} from 2 to 10 inclusive:
+
+@example
+COMPUTE l = @{@}.
+LOOP n = 2 TO 10.
+  COMPUTE a = n.
+  LOOP i = 1 TO 100.
+    DO IF MOD(a, 2) = 0.
+      COMPUTE a = TRUNC(a &** (1/2)).
+    ELSE.
+      COMPUTE a = TRUNC(a &** (3/2)).
+    END IF.
+  END LOOP IF a = 1.
+  COMPUTE l = @{l; i@}.
+END LOOP.
+PRINT l.
+@end example
+
+@node Matrix BREAK Command
+@subsubsection The @code{BREAK} Command
+

 The @code{BREAK} command may be used inside a loop body, ordinarily
 within a @code{DO IF} command.  If it is executed, then the loop
 terminates immediately, jumping to the command just following
 @code{END LOOP}.  When multiple @code{LOOP} commands nest,
 @code{BREAK} terminates the innermost loop.
 
 The @code{BREAK} command may be used inside a loop body, ordinarily
 within a @code{DO IF} command.  If it is executed, then the loop
 terminates immediately, jumping to the command just following
 @code{END LOOP}.  When multiple @code{LOOP} commands nest,
 @code{BREAK} terminates the innermost loop.
 

+The following example is a revision of the one above that shows how
+@code{BREAK} could substitute for the index and @code{IF} clauses on
+@code{LOOP} and @code{END LOOP}:
+
+@example
+COMPUTE l = @{@}.
+LOOP n = 2 TO 10.
+  COMPUTE a = n.
+  COMPUTE i = 1.
+  LOOP.
+    DO IF MOD(a, 2) = 0.
+      COMPUTE a = TRUNC(a &** (1/2)).
+    ELSE.
+      COMPUTE a = TRUNC(a &** (3/2)).
+    END IF.
+    DO IF a = 1.
+      BREAK.
+    END IF.
+    COMPUTE i = i + 1.
+  END LOOP.
+  COMPUTE l = @{l; i@}.
+END LOOP.
+PRINT l.
+@end example
+

 @node Matrix READ and WRITE Commands
 @subsection The @code{READ} and @code{WRITE} Commands
 
 @node Matrix READ and WRITE Commands
 @subsection The @code{READ} and @code{WRITE} Commands
 


@@ -2171,6 +2233,74 @@ file.  It is also ineffective just after a command that uses the
 particular file, because @code{EOF} has to try to read the next line
 from the file to determine whether the file contains more input.
 
 particular file, because @code{EOF} has to try to read the next line
 from the file to determine whether the file contains more input.
 

+@subsubheading Example 1: Basic Use
+
+The following matrix program reads the same matrix @code{@{1, 2, 4; 2,
+3, 5; 4, 5, 6@}} into matrix variables @code{v}, @code{w}, and
+@code{x}:
+
+@example
+READ v /FILE='input.txt' /FIELD=1 TO 100 /SIZE=@{3, 3@}.
+READ w /FIELD=1 TO 100 /SIZE=@{3; 3@} /MODE=SYMMETRIC.
+READ x /FIELD=1 TO 100 BY 1/SIZE=@{3, 3@} /MODE=SYMMETRIC.
+@end example
+
+@noindent
+given that @file{input.txt} contains the following:
+
+@example
+1, 2, 4
+2, 3, 5
+4, 5, 6
+1
+2 3
+4 5 6
+1
+23
+456
+@end example
+
+The @code{READ} command will read as many lines of input as needed for
+a particular row, so it's also acceptable to break any of the lines
+above into multiple lines.  For example, the first line @code{1, 2, 4}
+could be written with a line break following either or both commas.
+
+@subsubheading Example 2: Reading into a Submatrix
+
+The following reads a @math{5@times{}5} matrix from @file{input2.txt},
+reversing the order of the rows:
+
+@example
+COMPUTE m = MAKE(5, 5, 0).
+LOOP r = 5 TO 1 BY -1.
+  READ m(r, :) /FILE='input2.txt' /FIELD=1 TO 100.
+END LOOP.
+@end example
+
+@subsubheading Example 3: Using @code{REREAD}
+
+Suppose each of the 5 lines in a file @file{input3.txt} starts with an
+integer @var{count} followed by @var{count} numbers, e.g.:
+
+@example
+1 5
+3 1 2 3
+5 6 -1 2 5 1
+2 8 9
+3 1 3 2
+@end example
+
+@noindent
+Then, the following reads this file into a matrix @code{m}:
+
+@example
+COMPUTE m = MAKE(5, 5, 0).
+LOOP i = 1 TO 5.
+  READ count /FILE='input3.txt' /FIELD=1 TO 1 /SIZE=1.
+  READ m(i, 1:count) /FIELD=3 TO 100 /REREAD.
+END LOOP.
+@end example
+

 @node Matrix WRITE Command
 @subsubsection The @code{WRITE} Command
 
 @node Matrix WRITE Command
 @subsubsection The @code{WRITE} Command