Mercurial > octave

changeset 28627:0da2fbd3a642

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Overhaul Strings chapter. * doc/interpreter/container.txi: Rename changed nodes. * doc/interpreter/octave.texi: Rename changed nodes. Reduce to section level. * doc/interpreter/strings.txi: Overhaul chapter, especially reorder functions to suiteable categories.
author Abdallah Elshamy <abdallah.k.elshamy@gmail.com>
date Thu, 20 Aug 2020 23:12:47 +0900
parents 34696240591e
children 83172e1c77f2
files doc/interpreter/container.txi doc/interpreter/octave.texi doc/interpreter/strings.txi
diffstat 3 files changed, 117 insertions(+), 111 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/container.txi	Thu Aug 20 23:12:47 2020 +0900
+++ b/doc/interpreter/container.txi	Thu Aug 20 23:12:47 2020 +0900
@@ -914,11 +914,11 @@
 The following string functions support cell arrays of strings:
 @code{char}, @code{strvcat}, @code{strcat} (@pxref{Concatenating
 Strings}), @code{strcmp}, @code{strncmp}, @code{strcmpi},
-@code{strncmpi} (@pxref{Comparing Strings}), @code{str2double},
+@code{strncmpi} (@pxref{Searching in Strings}), @code{str2double},
 @code{deblank}, @code{strtrim}, @code{strtrunc}, @code{strfind},
 @code{strmatch}, , @code{regexp}, @code{regexpi}
-(@pxref{Manipulating Strings}) and @code{str2double}
-(@pxref{String Conversions}).
+(@pxref{String Operations}) and @code{str2double}
+(@pxref{Converting Strings}).
 
 The function @code{iscellstr} can be used to test if an object is a
 cell array of strings.
--- a/doc/interpreter/octave.texi	Thu Aug 20 23:12:47 2020 +0900
+++ b/doc/interpreter/octave.texi	Thu Aug 20 23:12:47 2020 +0900
@@ -302,17 +302,10 @@
 
 * Escape Sequences in String Constants::
 * Character Arrays::
-* Creating Strings::
-* Comparing Strings::
-* Manipulating Strings::
-* String Conversions::
+* String Operations::
+* Converting Strings::
 * Character Class Functions::
 
-Creating Strings
-
-* Concatenating Strings::
-* Converting Numerical Data to Strings::
-
 Data Containers
 
 * Structures::
--- a/doc/interpreter/strings.txi	Thu Aug 20 23:12:47 2020 +0900
+++ b/doc/interpreter/strings.txi	Thu Aug 20 23:12:47 2020 +0900
@@ -56,14 +56,17 @@
 While strings can in principle store arbitrary content, most functions expect
 them to be UTF-8 encoded Unicode strings.
 
+Furthermore, it is 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)
+
 @menu
 * Escape Sequences in String Constants::
 * Character Arrays::
-* Creating Strings::
-* Comparing Strings::
-* Manipulating Strings::
-* String Conversions::
-* JSON decoding/encoding::
+* String Operations::
+* Converting Strings::
 * Character Class Functions::
 @end menu
 
@@ -208,26 +211,65 @@
 
 @DOCSTRING(string_fill_char)
 
+Another useful function to control the text justification in this case is
+the @code{strjust} function.
+
+@DOCSTRING(strjust)
+
 This 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}.
 
-@node Creating Strings
-@section Creating Strings
+@node String Operations
+@section String Operations
+
+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.
 
-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).
+@example
+@group
+quote = ...
+  "First things first, but not necessarily in that order";
+quote( quote == " " ) = "_"
+@result{} quote =
+    First_things_first,_but_not_necessarily_in_that_order
+@end group
+@end example
 
-@DOCSTRING(blanks)
+For more complex manipulations, such as searching, replacing, and
+general regular expressions, the following functions come with Octave.
 
 @menu
+* Common String Operations::
 * Concatenating Strings::
-* Converting Numerical Data to Strings::
+* Splitting and Joining Strings::
+* Searching in Strings::
+* Searching and Replacing in Strings::
 @end menu
 
+@node Common String Operations
+@subsection Common String Operations
+
+The following functions are useful to perform common String operations.
+
+@DOCSTRING(tolower)
+
+@DOCSTRING(toupper)
+
+@DOCSTRING(deblank)
+
+@DOCSTRING(strtrim)
+
+@DOCSTRING(strtrunc)
+
+@DOCSTRING(untabify)
+
+@DOCSTRING(do_string_escapes)
+
+@DOCSTRING(undo_string_escapes)
+
 @node Concatenating Strings
 @subsection Concatenating Strings
 
@@ -371,25 +413,21 @@
 
 @DOCSTRING(cstrcat)
 
-@node Converting Numerical Data to Strings
-@subsection Converting Numerical Data to Strings
-Apart from the string concatenation functions (@pxref{Concatenating Strings})
-which cast numerical data to the corresponding UTF-8 encoded characters, there
-are several functions that format numerical data as strings.  @code{mat2str}
-and @code{num2str} convert real or complex matrices, while @code{int2str}
-converts integer matrices.  @code{int2str} takes the real part of complex
-values and round fractional values to integer.  A more flexible way to format
-numerical data as strings is the @code{sprintf} function
-(@pxref{Formatted Output}, @ref{XREFsprintf,,sprintf}).
+@node Splitting and Joining Strings
+@subsection Splitting and Joining Strings
+
+@DOCSTRING(substr)
+
+@DOCSTRING(strtok)
 
-@DOCSTRING(mat2str)
+@DOCSTRING(strsplit)
 
-@DOCSTRING(num2str)
+@DOCSTRING(ostrsplit)
 
-@DOCSTRING(int2str)
+@DOCSTRING(strjoin)
 
-@node Comparing Strings
-@section Comparing Strings
+@node Searching in Strings
+@subsection Searching in Strings
 
 Since a string is a character array, comparisons between strings work
 element by element as the following example shows:
@@ -417,37 +455,13 @@
 
 @DOCSTRING(strncmpi)
 
+Despite those comparison functions, there are more specialized function to
+find the index position of a search pattern within a string.
+
 @DOCSTRING(startsWith)
 
 @DOCSTRING(endsWith)
 
-@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
-@group
-quote = ...
-  "First things first, but not necessarily in that order";
-quote( quote == " " ) = "_"
-@result{} quote =
-    First_things_first,_but_not_necessarily_in_that_order
-@end group
-@end example
-
-For more complex manipulations, such as searching, replacing, and
-general regular expressions, the following functions come with Octave.
-
-@DOCSTRING(deblank)
-
-@DOCSTRING(strtrim)
-
-@DOCSTRING(strtrunc)
-
 @DOCSTRING(findstr)
 
 @DOCSTRING(strchr)
@@ -456,26 +470,19 @@
 
 @DOCSTRING(rindex)
 
-@DOCSTRING(strfind)
+@DOCSTRING(unicode_idx)
 
-@DOCSTRING(strjoin)
+@DOCSTRING(strfind)
 
 @DOCSTRING(strmatch)
 
-@DOCSTRING(strtok)
-
-@DOCSTRING(strsplit)
-
-@DOCSTRING(ostrsplit)
-
-@DOCSTRING(strread)
+@node Searching and Replacing in Strings
+@subsection Searching and Replacing in Strings
 
 @DOCSTRING(strrep)
 
 @DOCSTRING(erase)
 
-@DOCSTRING(substr)
-
 @DOCSTRING(regexp)
 
 @DOCSTRING(regexpi)
@@ -484,23 +491,45 @@
 
 @DOCSTRING(regexptranslate)
 
-@DOCSTRING(untabify)
+@node Converting Strings
+@section Converting Strings
+
+Octave offers several kinds of conversion functions for Strings.
 
-@DOCSTRING(unicode_idx)
+@menu
+* String encoding::
+* Numerical Data and Strings::
+* JSON data decoding/encoding::
+@end menu
 
-@node String Conversions
-@section String Conversions
+@node String encoding
+@subsection String encoding
+
+@DOCSTRING(unicode2native)
+
+@DOCSTRING(native2unicode)
 
-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.
+@node Numerical Data and Strings
+@subsection Numerical Data and Strings
 
-@example
-@group
-hex2dec ("FF")
-      @result{} 255
-@end group
-@end example
+Apart from the string concatenation functions (@pxref{Concatenating Strings})
+which cast numerical data to the corresponding UTF-8 encoded characters, there
+are several functions that format numerical data as strings.  @code{mat2str}
+and @code{num2str} convert real or complex matrices, while @code{int2str}
+converts integer matrices.  @code{int2str} takes the real part of complex
+values and round fractional values to integer.  A more flexible way to format
+numerical data as strings is the @code{sprintf} function
+(@pxref{Formatted Output}, @ref{XREFsprintf,,sprintf}).
+
+@DOCSTRING(mat2str)
+
+@DOCSTRING(num2str)
+
+@DOCSTRING(int2str)
+
+@DOCSTRING(str2double)
+
+@DOCSTRING(str2num)
 
 @DOCSTRING(bin2dec)
 
@@ -518,26 +547,10 @@
 
 @DOCSTRING(hex2num)
 
-@DOCSTRING(str2double)
-
-@DOCSTRING(strjust)
-
-@DOCSTRING(str2num)
-
-@DOCSTRING(tolower)
-
-@DOCSTRING(toupper)
+@DOCSTRING(strread)
 
-@DOCSTRING(unicode2native)
-
-@DOCSTRING(native2unicode)
-
-@DOCSTRING(do_string_escapes)
-
-@DOCSTRING(undo_string_escapes)
-
-@node JSON decoding/encoding
-@section JSON decoding/encoding
+@node JSON data decoding/encoding
+@subsection JSON data decoding/encoding
 
 JavaScript Object Notation, in short JSON, is a very common human readable
 and structured data format.  GNU Octave supports decoding and encoding this