FAQ entry for #351 (#958)

Author: johnkerl

docs/src/special-symbols-and-formatting.md

@@ -165,4 +165,19 @@ b it is!
 c is it ...
 </pre>
 
-The `ssub` function exists precisely for this reason: so you don't have to escape anything.
+The [`ssub`](reference-dsl-builtin-functions.md#ssub) function exists precisely for this reason: so you don't have to escape anything.
+
+## How to apply math to regex output?
+
+* Use parentheses for capture groups
+* Use `\1`, `\2`, etc. to refer to the captures
+* The matched patterns are strings, so cast them to `int` or `float`
+
+See also the [page on regular expressions](reference-main-regular-expressions.md).
+
+<pre class="pre-highlight-in-pair">
+<b>echo "a=14°45'" | mlr put '$a =~"^([0-9]+)°([0-9]+)" {$degrees = float("\1") + float("\2") / 60}'</b>
+</pre>
+<pre class="pre-non-highlight-in-pair">
+a=14°45',degrees=14.75
+</pre>

docs/src/special-symbols-and-formatting.md.in

@@ -89,4 +89,16 @@ GENMD-RUN-COMMAND
 mlr --oxtab put '$c = ssub($a, "?"," ...")' data/question.dat
 GENMD-EOF
 
-The `ssub` function exists precisely for this reason: so you don't have to escape anything.
+The [`ssub`](reference-dsl-builtin-functions.md#ssub) function exists precisely for this reason: so you don't have to escape anything.
+
+## How to apply math to regex output?
+
+* Use parentheses for capture groups
+* Use `\1`, `\2`, etc. to refer to the captures
+* The matched patterns are strings, so cast them to `int` or `float`
+
+See also the [page on regular expressions](reference-main-regular-expressions.md).
+
+GENMD-RUN-COMMAND
+echo "a=14°45'" | mlr put '$a =~"^([0-9]+)°([0-9]+)" {$degrees = float("\1") + float("\2") / 60}'
+GENMD-EOF

todo.txt

@@ -3,12 +3,14 @@ RELEASES
 * plan 6.1.0
   o unsparsify -f CSV by default -- ? into CSV record-writer -- ? caveat that record 1 controls all ...
   o mlr join --left-fields a,b,c
-  o several needs-doc issues
-    https://github.com/johnkerl/miller/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds-documentation
   o fmt/unfmt/regex doc
   o FAQ/examples reorg
   ? ??? for doc-string contents search -- ? & mlr help namegoeshere foo ...
 
+  o several needs-doc issues
+    https://github.com/johnkerl/miller/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds-documentation
+    echo "a=14°20" | mlr put '$out=sub($a,"^([0-9]+)°([0-9]+)$","\1\2")'
+
   k strptime/882
   k fmtifnum, & recursive fmtnum/fmtifnum
   k unicode string literals
@@ -26,6 +28,9 @@ RELEASES
   k ?foo and ??foo @ repl help
   k doc-improves
 
+  d all-contribs check before release
+    > release notes in particular Poshi derekmahar aborruso
+
 * plan 6.2.0
   ! extended field accessors for #763 and #948 (positional & json.nested)
   ! strict mode