From: Tim Duesterhus <tim@bastelstu.be>
Date: Thu, 30 Nov 2023 15:41:18 +0000 (+0100)
Subject: DOC: Clarify the differences between field() and word()
X-Git-Tag: v2.9.0~17
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ed3bc0bfdd8a0151d1be370cc051d005e6c80d19;p=thirdparty%2Fhaproxy.git

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 0676aa1fbd..33e4ab63bf 100644
--- 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