Why do I see a constructor in the String source code, but not in the JavaDocs?

Question

I am trying to become more familiar with using the JavaDocs. I was looking at the String function and I thought it was interesting how a String is really just an array of characters held in a private reference variable.

When I was looking at the source code of the String it shows one of the constructors as the following:

String(int offset, int count, char value[]) {
    this.value = value;
    this.offset = offset;
    this.count = count;
}

Then I go over to look at the String JavaDoc, and it doesn't show a constructor with that type of signature.. what gives?

Note that you can use this constructor using Reflection: http://stackoverflow.com/questions/6636734/does-instanceof-void-always-return-false — Eng.Fouad, Jan 22 '12 at 04:57

score 7 · Answer 1 · answered Jan 22 '12 at 03:58

7

As Oli alluded to in the comments above, the constructor is not public. At least in the OpenJDK, the code is shown with a comment:

// Package private constructor which shares value array for speed.
String(int offset, int count, char value[]) {

As an additional note, if you really wanted that constructor, there is one that is virtually the same, but in different order:

String(char[] value, int offset, int count)

answered Jan 22 '12 at 03:58

Dominic K

6,975
11
53
62

ahh it's package private, I see. So this means that any class under the package java.lang can still use it right? – PMull34 Jan 22 '12 at 04:03
Yup, by its parent class or any other class in the package. For future reference, if it has no access modifier in front of it, then it is `package-private` by default. – Dominic K Jan 22 '12 at 04:08

score 3 · Answer 2 · answered Jan 22 '12 at 03:58

3

According to some random version of the Java documentation, there is no public constructor for String that has the signature that you posted. Therefore, this appears to be an implementation-internal (private) constructor that you are not meant to use directly, and thus it is not documented.

Standard libraries often employ internal helper functions that condense the many similar and related public interface functions into a small number of actual worker functions.

answered Jan 22 '12 at 03:58

Kerrek SB

464,522
92
875
1,084

1

In fact, since it is package private (and the `java.lang` package is protected against adding new classes) it is impossible for a kosher Java program to use it without resorting to reflection. – Stephen C Jan 22 '12 at 04:01

score 3 · Answer 3 · answered Jan 22 '12 at 03:58

There's a comment right above that constructor in the source code:

// Package private constructor which shares value array for speed.
String(int offset, int count, char value[]) {
    this.value = value;
    this.offset = offset;
    this.count = count;
}

That explains why the documentation of this non-public constructor is not included in the public documentation.

score 3 · Answer 4 · edited Jan 22 '12 at 04:04

3

From the source:

644 // Package private constructor which shares value array for speed.

Non-public methods are often not part of javadoc, as it's not something you can rely on (or use, in this case, since you're not in java.lang and it's package private).

edited Jan 22 '12 at 04:04

Umesh Awasthi

23,407
37
132
204

answered Jan 22 '12 at 04:00

James

8,512
1
26
28

score 2 · Answer 5 · answered Jan 22 '12 at 04:10

// Package private constructor which shares value array for speed.
String(int offset, int count, char value[])

so that we can not create object from out side of the class, in this way it can provide security to String class. This constructor is implemented in singletons.

Why do I see a constructor in the String source code, but not in the JavaDocs?

5 Answers5