java.lang.String(String original) is inadequately documented

Question

Specifically, it throws a NullPointerException if original is null. Yet the javadocs do not mention it.

I know, it says this constructor should not be necessary unless an explicit copy is needed, but I am writing copy constructors for some larger objects that contain Strings, and while it probably isn't strictly necessary to make an explicit copy, since everything else is getting an explicit copy in this case, I'm willing to pay a small price in inefficiency.

But shouldn't there be a throws in this javadoc?

I'm sorry, I didn't mean a throws declaration in the signature, I meant a @throws tag in the javadoc. — Steve Cohen, Dec 14 '12 at 23:49
Frankly, unless otherwise noted, you should assume nulls are not permitted. (Null intolerance is a _good_ default.) — Louis Wasserman, Dec 14 '12 at 23:56

score 7 · Accepted Answer · answered Dec 14 '12 at 23:50

7

From JavaTM 2 Platform Std. Ed. v1.4.2:

Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

answered Dec 14 '12 at 23:50

Richard JP Le Guen

28,364
7
89
119

score 1 · Answer 2 · answered Dec 14 '12 at 23:48

1

Strings are immutable. You do not want to create a String myString = new String("blah"); since this would result in a new object in heap. It is better to do String myString = "blah"; and link to the strings pool.

String myString = "blah";
String myOtherString = myString;

myOtherString = "";
// at this point myString == "blah"

answered Dec 14 '12 at 23:48

ssedano

8,322
9
60
98

This is normally true, but not always. Sometimes you *need* to make a string that has the same value as the original ... but different object identity. – Stephen C Dec 15 '12 at 00:09

score 1 · Answer 3 · answered Dec 14 '12 at 23:48

1

NullPointerException is an unchecked exception so although if you're very pedantic, you can add a @throws line to the javadoc, it's better not to. It's assumed that if you pass null where it doesn't make sense, you get an NPE. (Unchecked exceptions are more often than not signal a coding error, rather than an exceptional but valid scenario.)

And new String( null ) doesn't make sense, as a constructor couldn't result in an exact "copy" of null.

Copying strings is totally unnecessary too as they're immutable.

answered Dec 14 '12 at 23:48

biziclop

48,926
12
77
104

But that assumes it doesn't make sense to pass null. Suppose you are copying some Object that has many data member fields, some of which are Strings, and which may or may not be null. In that case I want String(String) to return null, specifically, I want it to copy the null value. – Steve Cohen Dec 14 '12 at 23:52
2

What you ask is impossible: a constructor cannot return `null`. – Richard JP Le Guen Dec 14 '12 at 23:53
See also [Java: Can creating an object “return” a null reference?](http://stackoverflow.com/questions/11103444/java-can-creating-an-object-return-a-null-reference) – Richard JP Le Guen Dec 14 '12 at 23:53
Hmm. Okay, that one makes sense. – Steve Cohen Dec 14 '12 at 23:53
@SteveCohen Yep, that's exactly what I meant. – biziclop Dec 15 '12 at 00:01

score 0 · Answer 4 · answered Dec 14 '12 at 23:52

0

The javadoc for this constructor says:

Unless an explicit copy of original is needed, use of this constructor is unnecessary since Strings are immutable

So you really shouldn't be calling it.

Also, I think it's reasonable to throw an NPE if you pass a null in

answered Dec 14 '12 at 23:52

Bohemian

412,405
93
575
722

then why don't they deprecate it? Do you really mean to say, "If you are stupid enough to use an unnecessary method, you deserve to get a null pointer exception if you pass null into it?" – Steve Cohen Dec 14 '12 at 23:55
@Bohemian - there are cases where calling this constructor IS warranted. I think we can assume that the OP has one of those situations. – Stephen C Dec 15 '12 at 00:05

score 0 · Answer 5 · answered Dec 14 '12 at 23:53

0

RuntimeException is reserved for exceptions that indicate incorrect use of an API (using a null object), which can occur anywhere in a Java program, so it's not particular to the String class (or any specific class)

answered Dec 14 '12 at 23:53

Bizmarck

2,663
2
33
48

This doesn't really address the question. Yea, sure if you treat the libraries as a black box and ignore the javadoc, any call could throw any unchecked exception. In practice unchecked exceptions are only thrown in specific situations, and those situations *should* be documented. (In this case it is ...) – Stephen C Dec 15 '12 at 00:04
It would not make sense to include a 'throws NullPointerException' in every documented Java class. I think it is sufficiently documented as is, since it's an API misuse. – Bizmarck Dec 15 '12 at 00:48

score 0 · Answer 6 · answered Dec 15 '12 at 00:17

The issue of the documentation has been addressed by the accepted answer.

I just want to respond to this comment ... which is probably the root of your problem.

But that assumes it doesn't make sense to pass null. Suppose you are copying some Object that has many data member fields, some of which are Strings, and which may or may not be null. In that case I want String(String) to return null, specifically, I want it to copy the null value.

That is not possible. The JLS specifically states that the new operation yields a new object and not a null.

If you want to be able to "create and return an object or null" you have to embed this logic in a factory method of some kind; e.g.

String myNewString(String s) {
    return s == null ? s : new String(s);
}

But it is also worth noting that in most circumstances copying a String in Java is unnecessary and wasteful. You should only do this if your application is specifically making use of the object identity of the strings; i.e. that it uses == to compare string objects and depends on strings with the same characters comparing as false. (Applications that require that are pretty rare ...)

java.lang.String(String original) is inadequately documented

6 Answers6