[docs] Add some string-ascii and string-utf8 types to the docs

[gregorycoppola]

Fixes #2650

Changes

This PR changes the documents for the following functions: map, filter, fold, concat, as-max-len?, len, element-at, index-of.

Background

From #2650:

"When string-ascii and string-utf8 were introduced, many functions documentation in the Clarity reference were not modified to include references to these new types when applicable."

In fact, some times the examples of valid usage already include the strings, but the function documentation does not say this is allowed, e.g., "len", "element-at".

Testing

1. I ran cargo test vm::docs

This should mostly just test that the new file compiles.

2. I tested the new documentations that I added by creating a contract with the following print statements.

   ;;; tested for the PR
   ;;; map
   (print (map my-and 0x010203 0x010203))
   (print (map add-one-char u"hello world"))
   (print (map add-one-ascii "hello world"))
   ;;; filter
   (print (filter is-three 0x01020304030201))
   (print (filter is-vowel u"hello world"))
   (print (filter is-vowel-ascii "hello world"))
   ;;; concat
   (print (concat "concat1" "concat2"))
   (print (concat "concat1" "concat2"))
   ;;; len
   (print (len "hello world"))
   (print (len u"hello world"))
   ;;; element at
   (print (element-at u"hello world" u2))
   (print (element-at "hello world" u2))
   ;;; index of
   (print (index-of u"hello world" u"l"))
   (print (index-of "hello world" "l"))

[kantai]

These changes look great, thanks @gregorycoppola!

The only thing I would add is some more examples for the changed docs, for example, adding like

(filter buff-filter 0x00110022003300440055) ;; Returns 0x1122334455

And some similar ones for string-ascii (we probably don't need examples for both string-ascii and string-utf8).

[gregorycoppola]

Now "map", "filter", "fold", "concat", "as-max-len", "len", "element-at", and "index-of", should each have "string" and "buff" examples.

[gregorycoppola]

These changes look great, thanks @gregorycoppola!

The only thing I would add is some more examples for the changed docs, for example, adding like

(filter buff-filter 0x00110022003300440055) ;; Returns 0x1122334455

And some similar ones for string-ascii (we probably don't need examples for both string-ascii and string-utf8).

[gregorycoppola]

I closed the comment.. not sure if I was supposed to close it or let you close it, but let's see.

[psq]

I closed the comment.. not sure if I was supposed to close it or let you close it, but let's see.

that closed the whole PR, not what you wanted, I'm guessing, so I reopened so this does not get lost. Sometimes, for inline comments, you can mark as resolved but not in this case.

Nice to see all these extra examples, thank you for doing this!

[gregorycoppola]

@psq Thanks for reopening :)

[kantai]

LGTM, thanks @gregorycoppola!

[gregorycoppola]

Thanks @kantai .. added @pavitthrap for second review.

[gregorycoppola]

Thanks for the reviews @pavitthrap and @jcnelson.

I addressed and resolved some comments, but left some open.

Importantly, I left open the question of how to disjoin the various sequence forms that a function can take. In the case of 'map', 'filter' and 'fold', the resulting forms can be complex. See discussion inline where I suggest an option, but ask for feedback.

Thanks!

[gregorycoppola]

I just pushed a version of this change that refactors the sequence arguments for readability and consistency.

See comment #2676 (comment)

[pavitthrap]

Just had a few minor comments left! Thanks for updating the docs :)

[kantai]

repsectively -> respectively

[kantai]

LGTM, just a couple typos!

[jcnelson]

Thanks @gregorycoppola! LGTM. Please make sure all tests pass before merging -- looks like there's a unit test failure?

[psq]

After all these iterations, the final version is much better now. Thank you!

[blockstack-devops]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.