DOC: Clarify the differences between field() and word()

word() mentions that delimiters at the start and end are ignored, but
it does not mention that consecutive delimiters are merged.

May be backported as far as the patch applies.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 0676aa1fbdf9c3769b98579fe2d81ea38bbe00e4..33e4ab63bfd087cd0e36087ffc8bcc6482bf42b7 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -18479,6 +18479,7 @@ field(<index>,<delimiters>[,<count>])
   fields.
 
   Example :
+      str(f1_f2_f3__f5),field(4,_)    # <empty>
       str(f1_f2_f3__f5),field(5,_)    # f5
       str(f1_f2_f3__f5),field(2,_,0)  # f2_f3__f5
       str(f1_f2_f3__f5),field(2,_,2)  # f2_f3
@@ -19746,17 +19747,21 @@ word(<index>,<delimiters>[,<count>])
   Extracts the nth word counting from the beginning (positive index) or from
   the end (negative index) considering given delimiters from an input string.
   Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
-  Delimiters at the beginning or end of the input string are ignored.
+  Empty words are skipped. This means that delimiters at the start or end of
+  the input string are ignored and consecutive delimiters within the input
+  string are considered to be a single delimiter.
   Optionally you can specify <count> of words to extract (default: 1).
   Value of 0 indicates extraction of all remaining words.
 
   Example :
       str(f1_f2_f3__f5),word(4,_)    # f5
+      str(f1_f2_f3__f5),word(5,_)    # <not found>
       str(f1_f2_f3__f5),word(2,_,0)  # f2_f3__f5
       str(f1_f2_f3__f5),word(3,_,2)  # f3__f5
       str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
       str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
       str(/f1/f2/f3/f4),word(1,/)    # f1
+      str(/f1////f2/f3/f4),word(1,/) # f2
 
 wt6([<avalanche>])
   Hashes a binary input sample into an unsigned 32-bit quantity using the WT6