3

In Java 15, JEP 378: Text Blocks added three instance methods to String: stripIndent(), translateEscapes(), and formatted(Object... args):

The following methods will be added to support text blocks;

  • String::stripIndent(): used to strip away incidental white space from the text block content
  • String::translateEscapes(): used to translate escape sequences
  • String::formatted(Object... args): simplify value substitution in the text block

The usefulness of formatted when working with text blocks is explained in the JEP, so its presence makes sense to me.

The other two methods, however, don't seem particularly useful as a developer working with text blocks. Both indentation stripping and escape translation are things that are automatically handled by the compiler with regards to text blocks. A code writer should never need to programmatically strip indentation from a Java text block, nor translate escapes in a text block. Furthermore, escape translation has been in the Java compiler since its initial release, so other than the two new escape sequences added to support text blocks (\s and \<line-terminator>), it's not even a new feature to Java.

The JEP explains that the methods are available for developer access, but not the reason for this decision.

The re-indentation algorithm will be normative in The Java Language Specification. Developers will have access to it via String::stripIndent, a new instance method.

Developers will have access to escape processing via String::translateEscapes, a new instance method.

Why were these methods added to the public String API alongside text blocks in Java 15, when they're not useful for manipulating text blocks outside of the compiler (or code that otherwise reads Java source code)?

I don't see it explained in the JEP, so I'm wondering if there is any official word or discussion explaining the inclusion of these methods in the public API.

M. Justin
  • 14,487
  • 7
  • 91
  • 130
  • 1
    Presumably, the authors disagree with you, and they think that the methods are useful. Sorry but this question is opinion based. – Stephen C Dec 24 '21 at 06:20
  • @StephenC Thanks, though I was hoping for something a little more authoritative than that. I didn't see anything in the JEP explaining it. – M. Justin Dec 24 '21 at 06:25
  • Well ... if it isn't in the JEP it won't be anywhere else. That and the javadocs are the only authoritative explanations published. But put it this way, if they *didn't* think those methods were useful, then they *wouldn't* have included them. – Stephen C Dec 24 '21 at 06:29
  • @StephenC Clearly. My question isn't whether they thought it was useful, it's _why_ they thought it was useful. This inclusion seems different than past Java API approaches, where such compiler-specific behaviors weren't generally included in the standard APIs, especially not something as core as `java.lang.String`. – M. Justin Dec 24 '21 at 06:31
  • How do we know why they thought that? Their thoughts aren't published :-) – Stephen C Dec 24 '21 at 06:31
  • @StephenC Mailing list discussions, official posts by the authors, etc. – M. Justin Dec 24 '21 at 06:32
  • And have you found anything? (Oracle employees don't post "official" statements ... unless they are management :-) ) – Stephen C Dec 24 '21 at 06:32
  • @StephenC I now found one thing; I expanded it into an answer. (https://stackoverflow.com/a/70470370/1108305) – M. Justin Dec 24 '21 at 07:05
  • excellent question! I was debating with myself why this exists, too. Could it be that some _other_ compilers can use that? let's say `scalac` wants such a translation - and to standardize it - put it into the library itself. For example `Objects::requireNonNull` is used by `javac` (and other compilers too)... I am referring to `translateEscapes` – Eugene Sep 07 '22 at 05:34

1 Answers1

1

I've done some online searching of the JDK mailing lists, bug trackers, etc. I haven't found a post that fully explains the thought process behind the decision.

I did however find the following comment in the JDK Bug System by Brian Goetz, Java Language Architect at Oracle (emphasis added by me):

I believe the tension here is that the stripIndent() method is caught in the following vise: the natural semantics for the language include stripping at both sides, and we want to have a library method that does what the language does (so users don't have to recreate that functionality), but the behavior of stripIndent() is potentially surprising if you don't make the connection with the language behavior. And the obvious solution is to split the entry points; allow something like indent() to cover the "reindent from the left only" use case that Joe believes is the natural interpretation for library users, while leaving stripIndent() as is (possibly with some renames to connect it better with the language feature.)

It seems the language & API designers want to have the logic used by the language available to developers. This doesn't explain fully explain why they feel it might be useful to users of the API, but it does at least partially explain the decision to include it.

M. Justin
  • 14,487
  • 7
  • 91
  • 130