Format: add pp_print_substring and pp_print_substring_as

[Octachron]

While looking at Format implementation, I was intrigued by the discrepancy that Format requires that its low-level printing devices are able to output slice of strings, but Format never exposes this feature to end users.

This PR proposes to fix this asymmetry by adding two functions: pp_print_substring and pp_print_substring_as to the Format module. Along the way, it updates pp_print_text to use the new function pp_print_substring function.

Note that this PR is mostly a request for comments, I am not sure if the functions are that useful but the implementation was very straightforward.

[c-cube]

This is one of these little paper cuts in the stdlib. I wish this had been added in 3.12 when I started using OCaml in earnest :).

[gasche]

I agree that it is reasonable to expose this capability, and the implementation looks fine. Approved.

(If we wanted to implement Jules' idea of precision for %s format specifiers, we would also need something like that for efficient support in Format. The other thing we would need is a new case Acc_data_substring in the type camlinternalFormat.acc.

[Octachron]

We might want at least a second opinion on the labels for the function (that were picked because they sounded good enough).

[dbuenzli]

Personally I tend more to use first/last/len for specifyng subranges and start/last for specifying processes (e.g. find) operating in a subrange (no stop, it's ambiguous).

But if you want to be consistent with StringLabels these start should rather be pos.

[gasche]

If I understand correctly, the recommendation is to use either ~first ~last, or ~first ~len, or ~pos ~len. @Octachron, which do you prefer?

[Octachron]

Keeping the information that the first integer is the first character of the substring range à la ~first ~len seems more important to me than being consistent with StringLabels in this case.

[gasche]

Fine with me. This PR still needs a second approval.

[nojb]

The docstring does not match the labels: start <-> first.

Personally, I didn't understand from the discussion why we don't use pos for the first label as in StringLabels. It seems needlessly noisy to introduce yet another convention of how to refer to the starting offset of a substring.

[Octachron]

I don't think that we should be beholden to the label choice of StringLabels outside of the labelled variant of the standard library and pos is an uninformative and ambiguous label name.

But if you prefer I could use it; after all Format API is already barely usable without Fmt due to its extremely verbose naming convention.

[gasche]

I don't have a strong opinion, but for me pos means "position" and I have no doubt that it means the position of the (start of the) substring, and len its len. So i am fine with either pos and first.

[dbuenzli]

Note that String attributes a particular meaning to the term position (versus index, see the String module preamble). If pos is used one should check the function works when it is equal to String.length s.

[nojb]

I don't have a strong opinion on this issue, so I'm happy to let @Octachron decide. In any case, the docstring should be corrected.

[nojb]

Idem.

[Octachron]

I have updated the documentation and decided to go with the more uniform ~pos label (after checking that yes print_substring s ~pos:(String.length s) ~len:0 works as intended).

[Octachron]

@nojb , are you fine with the current state?

[nojb]

@nojb , are you fine with the current state?

Yes!

The @since tags need to be updated, though.