# HG changeset patch # User jwe # Date 1179195812 0 # Node ID 545847da3b88e75ecad2c81d83b317bc8d3a4114 # Parent e416771442831bf0ccb4148c0cf68408d9225e18 [project @ 2007-05-15 02:23:08 by jwe] diff --git a/doc/ChangeLog b/doc/ChangeLog --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -8,6 +8,16 @@ * interpreter/package.texi: Document "*" flag for loaded packages. + * interpreter.var.txi: Improve explanation of clear, exist, and who. + + * interpreter/intro.txi: Change @unnumberedsubsec to @subsection. + + * interpreter/container.txi: Doc fix. + + * interpreter/strings.txi: Improve explanation for creating + comparing, and converting strings. + * interpreter/octave.texi: Update detailed menu. + 2007-05-09 David Bateman * faq/Octave-FAQ.texi: Update compatibility section. diff --git a/doc/interpreter/basics.txi b/doc/interpreter/basics.txi --- a/doc/interpreter/basics.txi +++ b/doc/interpreter/basics.txi @@ -288,12 +288,6 @@ invoke Octave with the @code{--verbose} option but without the @code{--silent} option. -@DOCSTRING(OCTAVE_HOME) - -@DOCSTRING(version) - -@DOCSTRING(ver) - @node Quitting Octave @section Quitting Octave @cindex exiting octave diff --git a/doc/interpreter/container.txi b/doc/interpreter/container.txi --- a/doc/interpreter/container.txi +++ b/doc/interpreter/container.txi @@ -164,9 +164,9 @@ with a single variable as is the case with numerical arrays. Accessing multiple elements of a cell array with the @samp{@{} and -@samp{@{} operators will result in a comma-seperated list of all +@samp{@}} operators will result in a comma-separated list of all the requested elements. This list can then be used anywhere where a -comma-seperated list is used, such as in the creation of a new +comma-separated list is used, such as in the creation of a new numerical array or cell array, or be passed as arguments to a function. If all the accessed elements of a cell array are scalars or column vectors, they can be concatenated into a new column vector diff --git a/doc/interpreter/intro.txi b/doc/interpreter/intro.txi --- a/doc/interpreter/intro.txi +++ b/doc/interpreter/intro.txi @@ -66,7 +66,7 @@ are lines you type, ending each with a carriage return. Octave will respond with an answer, or by displaying a graph. -@unnumberedsubsec Creating a Matrix +@subsection Creating a Matrix To create a new matrix and store it in a variable so that it you can refer to it later, type the command @@ -96,7 +96,7 @@ octave:3> B @end example -@unnumberedsubsec Matrix Arithmetic +@subsection Matrix Arithmetic Octave has a convenient operator notation for performing matrix arithmetic. For example, to multiply the matrix @code{a} by a scalar @@ -129,7 +129,7 @@ octave:6> A' * A @end example -@unnumberedsubsec Solving Linear Equations +@subsection Solving Linear Equations To solve the set of linear equations @code{A@var{x} = b}, use the left division operator, @samp{\}: @@ -153,7 +153,7 @@ If the coefficient matrix is singular, Octave will print a warning message and compute a minimum norm solution. -@unnumberedsubsec Integrating Differential Equations +@subsection Integrating Differential Equations Octave has built-in functions for solving nonlinear differential equations of the form @@ -246,7 +246,7 @@ Systematized Collection of ODE Solvers}, in: Scientific Computing, R. S. Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64. -@unnumberedsubsec Producing Graphical Output +@subsection Producing Graphical Output To display the solution of the previous example graphically, use the command @@ -278,7 +278,7 @@ explains more options for the @code{print} command and provides a list of additional output file formats. -@unnumberedsubsec Editing What You Have Typed +@subsection Editing What You Have Typed At the Octave prompt, you can recall, edit, and reissue previous commands using Emacs- or vi-style editing commands. The default @@ -292,7 +292,7 @@ A complete description of the command line editing capability is given in this manual in @ref{Command Line Editing}. -@unnumberedsubsec Help and Documentation +@subsection Help and Documentation Octave has an extensive help facility. The same documentation that is available in printed form is also available from the Octave prompt, diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi --- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -172,7 +172,7 @@ * Trouble:: If you have trouble installing Octave. * Installation:: How to configure, compile and install Octave. * Emacs:: -* Grammar:: +@c * Grammar:: * Copying:: The GNU General Public License. * Concept Index:: An item for each concept. * Variable Index:: An item for each documented variable. @@ -261,7 +261,8 @@ Strings * Creating Strings:: -* Searching and Replacing:: +* Comparing Strings:: +* Manipulating Strings:: * String Conversions:: * Character Class Functions:: @@ -539,7 +540,7 @@ * Running Octave From Within Emacs:: * Using the Emacs Info Reader for Octave:: -Grammar +@c Grammar * Keywords:: diff --git a/doc/interpreter/strings.txi b/doc/interpreter/strings.txi --- a/doc/interpreter/strings.txi +++ b/doc/interpreter/strings.txi @@ -30,7 +30,7 @@ @cindex escape sequence notation In double-quoted strings, the backslash character is used to introduce -@dfn{escape sequences} that reresent other characters. For example, +@dfn{escape sequences} that represent other characters. For example, @samp{\n} embeds a newline character in a double-quoted string and @samp{\"} embeds a double quote character. @@ -130,14 +130,44 @@ @node Creating Strings @section Creating Strings +The easiest way to create a string is, as illustrated in the introduction, +to enclose a text in double-quotes or single-quotes. It is however +possible to create a string without actually writing a text. The +function @code{blanks} creates a string of a given length consisting +only of blank characters (ASCII code 32). + @DOCSTRING(blanks) +The string representation used by Octave is an array of characters, so +the result of @code{blanks(10)} is actually a row vector of length 10 +containing the value 32 in all places. This lends itself to the obvious +generalisation to character matrices. Using a matrix of characters, it +is possible to represent a collection of same-length strings in one +variable. The convention used in Octave is that each row in a +character matrix is a separate string, but letting each column represent +a string is equally possible. + +The easiest way to create a character matrix is to put several strings +together into a matrix. + +@example +collection = [ "String #1"; "String #2" ]; +@end example + +@noindent +This creates a 2-by-9 character matrix. + +One relevant question is, what happens when character matrix is +created from strings of different length. The answer is that Octave +puts blank characters at the end of strings shorter than the longest +string. While it is possible to use a different character than the +blank character using the @code{string_fill_char} function, it shows +a problem with character matrices. It simply isn't possible to +represent strings of different lengths. The solution is to use a cell +array of strings, which is described in @ref{Cell Arrays of Strings}. + @DOCSTRING(char) -@DOCSTRING(int2str) - -@DOCSTRING(com2str) - @DOCSTRING(strcat) @DOCSTRING(strvcat) @@ -154,8 +184,50 @@ @DOCSTRING(num2str) -@node Searching and Replacing -@section Searching and Replacing +@DOCSTRING(int2str) + +@node Comparing Strings +@section Comparing Strings + +Since a string is a character array comparison between strings work +element by element as the following example shows. + +@example +GNU = "GNU's Not UNIX"; +spaces = (GNU == " ") + @result{} spaces = + 0 0 0 0 0 1 0 0 0 1 0 0 0 0 +@end example + +@noindent +To determine if two functions are identical it is therefore necessary +to use the @code{strcmp} or @code{strncpm} functions. Similar +functions exists for doing case-insensitive comparisons. + +@DOCSTRING(strcmp) + +@DOCSTRING(strcmpi) + +@DOCSTRING(strncmp) + +@DOCSTRING(strncmpi) + +@node Manipulating Strings +@section Manipulating Strings + +Octave supports a wide range of functions for manipulating strings. +Since a string is just a matrix, simple manipulations can be accomplished +using standard operators. The following example shows how to replace +all blank characters with underscores. + +@example +quote = "First things first, but not necessarily in that order"; +quote( quote == " " ) = "_" + @print{} quote = First_things_first,_but_not_necessarily_in_that_order +@end example + +For more complex manipulations, such as searching, replacing, and +general regular expressions, the following function come with Octave. @DOCSTRING(deblank) @@ -173,14 +245,6 @@ @DOCSTRING(split) -@DOCSTRING(strcmp) - -@DOCSTRING(strcmpi) - -@DOCSTRING(strncmp) - -@DOCSTRING(strncmpi) - @DOCSTRING(strrep) @DOCSTRING(substr) @@ -194,6 +258,15 @@ @node String Conversions @section String Conversions +Octave supports various kinds of conversions between strings and +numbers. As an example, it is possible to convert a string containing +a hexadecimal number to a floating point number. + +@example +hex2dec ("FF") + @result{} ans = 255 +@end example + @DOCSTRING(bin2dec) @DOCSTRING(dec2bin) @@ -206,9 +279,9 @@ @DOCSTRING(base2dec) -@DOCSTRING(strjust) +@DOCSTRING(str2double) -@DOCSTRING(str2double) +@DOCSTRING(strjust) @DOCSTRING(str2num) diff --git a/doc/interpreter/system.txi b/doc/interpreter/system.txi --- a/doc/interpreter/system.txi +++ b/doc/interpreter/system.txi @@ -387,8 +387,14 @@ @DOCSTRING(isieee) +@DOCSTRING(OCTAVE_HOME) + @DOCSTRING(OCTAVE_VERSION) +@DOCSTRING(version) + +@DOCSTRING(ver) + @DOCSTRING(octave_config_info) @DOCSTRING(getrusage) diff --git a/doc/interpreter/var.txi b/doc/interpreter/var.txi --- a/doc/interpreter/var.txi +++ b/doc/interpreter/var.txi @@ -96,7 +96,7 @@ @noindent the value of the global variable @code{gvar} is 1, not 2. Issuing a -@samp{clear a} command does not change the above behavior, but +@samp{clear gvar} command does not change the above behavior, but @samp{clear all} does. It is necessary declare a variable as global within a function body in @@ -203,7 +203,18 @@ @node Status of Variables @section Status of Variables -@DOCSTRING(clear) +When creating simple one-shot programs it can be very convenient to +see which variables are available at the prompt. The function @code{who} +and its siblings @code{whos} and @code{whos_line_format} will show +different information about what is in memory, as the following shows. + +@example +str = "A random string"; +who -variables + @print{} *** local user variables: + @print{} + @print{} __nargin__ str +@end example @DOCSTRING(who) @@ -211,8 +222,40 @@ @DOCSTRING(whos_line_format) +Instead of displaying which variables are in memory, it is possible +to determine if a given variable is available. That way it is possible +to alter the behaviour of a program depending on the existence of a +variable. The following example illustrates this. + +@example +if (! exist ("meaning", "var")) + disp ("The program has no 'meaning'"); +endif +@end example + @DOCSTRING(exist) +Usually Octave will manage the memory, but sometimes it can be practical +to remove variables from memory manually. This is usually needed when +working with large variables that fill a substantial part of the memory. +On a computer that uses the IEEE floating point format, the following +program allocates a matrix that requires around 128 MB memory. + +@example +large_matrix = zeros (4000, 4000); +@end example + +@noindent +Since having this variable in memory might slow down other computations, +it can be necessary to remove it manually from memory. The @code{clear} +function allows this. + +@DOCSTRING(clear) + +Information about a function or variable such as it's location in the +file system can also be acquired from within Octave. This is usually +only useful during development of programs, and not within a program. + @DOCSTRING(document) @DOCSTRING(type) diff --git a/scripts/general/int2str.m b/scripts/general/int2str.m --- a/scripts/general/int2str.m +++ b/scripts/general/int2str.m @@ -19,9 +19,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} int2str (@var{n}) -## @deftypefnx {Function File} {} num2str (@var{x}, @var{precision}) -## @deftypefnx {Function File} {} num2str (@var{x}, @var{format}) -## Convert a number to a string. This function is not very flexible. +## @deftypefnx {Function File} {} int2str (@var{x}, @var{precision}) +## @deftypefnx {Function File} {} int2str (@var{x}, @var{format}) +## Convert an integer to a string. This function is not very flexible. ## For better control over the results, use @code{sprintf} ## (@pxref{Formatted Output}). ## @seealso{sprintf, num2str} diff --git a/src/ChangeLog b/src/ChangeLog --- a/src/ChangeLog +++ b/src/ChangeLog @@ -10,7 +10,8 @@ * toplev.cc (Fatexit): Simplify example in doc string. * help.cc (Flookfor): Doc fix. - * input.cc, + * DLD-FUNCTIONS/cellfun.cc (Fcellfun): + Reformat to avoid long lines in doc string example. 2007-05-13 Søren Hauberg diff --git a/src/DLD-FUNCTIONS/cellfun.cc b/src/DLD-FUNCTIONS/cellfun.cc --- a/src/DLD-FUNCTIONS/cellfun.cc +++ b/src/DLD-FUNCTIONS/cellfun.cc @@ -101,7 +101,8 @@ \n\ @example\n\ @group\n\ -cellfun (\"tolower(x)\", @{\"Foo\", \"Bar\", \"FooBar\"@},'UniformOutput',false)\n\ +cellfun (\"tolower(x)\", @{\"Foo\", \"Bar\", \"FooBar\"@},\n\ + \"UniformOutput\",false)\n\ @result{} ans = @{\"foo\", \"bar\", \"foobar\"@}\n\ @end group\n\ @end example\n\