1 files changed, 86 insertions, 0 deletions
diff --git a/txr.1 b/txr.1
index f7c9ae8c..76be9f33 100644
--- a/txr.1
+++ b/txr.1
@@ -33459,6 +33459,92 @@ elements. To find the rightmost of the maxima, the
 function can be substituted. Analogous reasoning applies to other
 test functions.
 
+.coNP Function @ subst
+.synb
+.mets (subst < old < new < seq >> [ testfun <> [ keyfun ]])
+.syne
+.desc
+The
+.code subst
+function returns a sequence of the same type as
+.meta seq
+in which elements of
+.meta seq
+which match the
+.meta old
+object have been replaced with the
+.meta new
+object.
+
+To form the comparison keys, the elements of
+.meta seq
+are projected through the
+.meta testfun
+function, which defaults to
+.codn identity ,
+so the items themselves are used as keys by default.
+
+Keys are compared to the
+.meta old
+value using
+.metn testfun ,
+which defaults to
+.codn equal .
+
+.TP* Examples:
+
+.verb
+  (subst "brown" "black" #("how" "now" "brown" "cow"))
+  -> #("how" "now" "black" "cow"))
+
+  ;; elements are converted to lower case to form keys
+  [subst "brown" "black"
+         #("how" "now" "BROWN" "cow") : downcase-str]
+  -> #("how" "now" "black" "cow")
+
+  ;; using < instead of equality, replace elements
+  ;; greater than 5 with 0
+  [subst 5 0 '(1 2 3 4 5 6 7 8 9 10) <] (1 2 3 4 5 0 0 0 0 0))
+.brev
+
+.coNP Functions @, subq @ subql and @ subqual
+.synb
+.mets (subq < old < new << sequence )
+.mets (subql < old < new << sequence )
+.mets (subqual < old < new << sequence )
+.syne
+.desc
+The
+.codn subq ,
+.code subql
+and
+.code subqual
+functions return a sequence of the same kind as
+.meta sequence
+in which elements matching the
+.meta old
+object are replaced by
+.meta new
+object.
+
+The matching elements are identified by comparing with
+.meta old
+using, respectively, the functions
+.codn eq ,
+.codn eql ,
+and
+.codn equal .
+
+.TP* Examples:
+
+.verb
+  (subq #\eb #\ez "abc") -> "azc"
+  (subql 1 3 #(0 1 2)) -> #(0 3 2)
+
+  (subqual "are" "do" '#"how are you")
+  -> ("how" "do" "you")
+.brev
+
 .coNP Function @ mismatch
 .synb
 .mets (mismatch < left-seq < right-seq >> [ testfun <> [ keyfun ]])