aboutsummaryrefslogtreecommitdiff
path: root/src/util
diff options
context:
space:
mode:
authorPieter Wuille <pieter.wuille@gmail.com>2019-09-18 12:25:55 -0700
committerPieter Wuille <pieter.wuille@gmail.com>2019-09-18 12:25:55 -0700
commit5e69aeec3f2a0fafd5e591b7222716f00145761d (patch)
tree6005548a9a4a7780a4914e13e7464b53e86ad58f /src/util
parent230d43fdbc41b356700b0d8a6984d69e00279ade (diff)
Add documenting comments to spanparsing.h
Diffstat (limited to 'src/util')
-rw-r--r--src/util/spanparsing.h29
1 files changed, 25 insertions, 4 deletions
diff --git a/src/util/spanparsing.h b/src/util/spanparsing.h
index a2eb24b1fb..63f54758bd 100644
--- a/src/util/spanparsing.h
+++ b/src/util/spanparsing.h
@@ -12,16 +12,37 @@
namespace spanparsing {
-/** Parse a constant. If successful, sp is updated to skip the constant and return true. */
+/** Parse a constant.
+ *
+ * If sp's initial part matches str, sp is updated to skip that part, and true is returned.
+ * Otherwise sp is unmodified and false is returned.
+ */
bool Const(const std::string& str, Span<const char>& sp);
-/** Parse a function call. If successful, sp is updated to be the function's argument(s). */
+/** Parse a function call.
+ *
+ * If sp's initial part matches str + "(", and sp ends with ")", sp is updated to be the
+ * section between the braces, and true is returned. Otherwise sp is unmodified and false
+ * is returned.
+ */
bool Func(const std::string& str, Span<const char>& sp);
-/** Return the expression that sp begins with, and update sp to skip it. */
+/** Extract the expression that sp begins with.
+ *
+ * This function will return the initial part of sp, up to (but not including) the first
+ * comma or closing brace, skipping ones that are surrounded by braces. So for example,
+ * for "foo(bar(1),2),3" the initial part "foo(bar(1),2)" will be returned. sp will be
+ * updated to skip the initial part that is returned.
+ */
Span<const char> Expr(Span<const char>& sp);
-/** Split a string on every instance of sep, returning a vector. */
+/** Split a string on every instance of sep, returning a vector.
+ *
+ * If sep does not occur in sp, a singleton with the entirety of sp is returned.
+ *
+ * Note that this function does not care about braces, so splitting
+ * "foo(bar(1),2),3) on ',' will return {"foo(bar(1)", "2)", "3)"}.
+ */
std::vector<Span<const char>> Split(const Span<const char>& sp, char sep);
} // namespace spanparsing