Summary

Starting with RFC 2781 (published February 2000), Unicode grew to include characters larger than 16 bits. While most of the Java documentation was updated to reflect this, these two overlooked JNI functions remain unchanged. A minimal modification of the current documentation is needed for it to be accurate again.

Problem

Currently, NewString() has an ambiguous description and GetStringLength() has an incorrect description. The documentation refers to the length of these strings as "the count of Unicode characters," which is definitionally equivalent to "the count of Unicode code points." However, the length expected by NewString() and returned by GetStringLength() is the number of 16-bit words used to represent the string.

Solution

An overview of the solution. Alternative solutions may be discussed; links to rationale documents or review threads welcome to provide additional background to reviewers.

Specification

EXPECTED VERSUS ACTUAL BEHAVIOR : EXPECTED - To be correct: * Specify that the value returned by GetStringLength() is the number of 16-bit words used to represent the string * Specify that the "len" parameter of NewString is the number of 16-bit words used to represent the string

Ideally: * Specify that NewString() requires a UTF-16 string as input * Specify that the length returned by GetStringLength() corresponds to a UTF-16 string ACTUAL - NewString(), which takes a length parameter, describes the parameter as: "len: length of the Unicode string."

GetStringLength(), which returns string length, is described as: "Returns the length (the count of Unicode characters) of a Java string."

URL OF FAULTY DOCUMENTATION : http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#NewString