New utility function: ptrlen_get_word().

This is similar to strtok, only it operates on a ptrlen. Therefore it
can be properly stateless, or rather, it stores its state by
overwriting the input ptrlen to point to a tail of its previous value.

Also in this commit I add a clarifying comment about when
ptrlen_{starts,ends}with will write through its 'tail' pointer.

misc.h

@@ -168,8 +168,14 @@ static inline ptrlen ptrlen_from_strbuf(strbuf *sb)
 bool ptrlen_eq_string(ptrlen pl, const char *str);
 bool ptrlen_eq_ptrlen(ptrlen pl1, ptrlen pl2);
 int ptrlen_strcmp(ptrlen pl1, ptrlen pl2);
+/* ptrlen_startswith and ptrlen_endswith write through their 'tail'
+ * argument if and only if it is non-NULL and they return true. Hence
+ * you can write ptrlen_startswith(thing, prefix, &thing), writing
+ * back to the same ptrlen it read from, to remove a prefix if present
+ * and say whether it did so. */
 bool ptrlen_startswith(ptrlen whole, ptrlen prefix, ptrlen *tail);
 bool ptrlen_endswith(ptrlen whole, ptrlen suffix, ptrlen *tail);
+ptrlen ptrlen_get_word(ptrlen *input, const char *separators);
 char *mkstr(ptrlen pl);
 int string_length_for_printf(size_t);
 /* Derive two printf arguments from a ptrlen, suitable for "%.*s" */

utils.c

@@ -938,6 +938,26 @@ bool ptrlen_endswith(ptrlen whole, ptrlen suffix, ptrlen *tail)
     return false;
 }
 
+ptrlen ptrlen_get_word(ptrlen *input, const char *separators)
+{
+    const char *p = input->ptr, *end = p + input->len;
+    ptrlen toret;
+
+    while (p < end && strchr(separators, *p))
+        p++;
+    toret.ptr = p;
+    while (p < end && !strchr(separators, *p))
+        p++;
+    toret.len = p - (const char *)toret.ptr;
+
+    size_t to_consume = p - (const char *)input->ptr;
+    assert(to_consume <= input->len);
+    input->ptr = (const char *)input->ptr + to_consume;
+    input->len -= to_consume;
+
+    return toret;
+}
+
 char *mkstr(ptrlen pl)
 {
     char *p = snewn(pl.len + 1, char);