svn commit: r1353098 - in /lucene/dev/branches/branch_4x: ./ lucene/ lucene/core/ lucene/core/src/java/org/apache/lucene/util/BytesRef.java

[us...@apache.org]

Author: uschindler
Date: Sat Jun 23 09:21:50 2012
New Revision: 1353098

URL: http://svn.apache.org/viewvc?rev=1353098&view=rev
Log:
Merged revision(s) 1353097 from lucene/dev/trunk:
Prevent incorrect usage of BytesRef as I have seen quite often on the net!

Modified:
    lucene/dev/branches/branch_4x/   (props changed)
    lucene/dev/branches/branch_4x/lucene/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/util/BytesRef.java

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/util/BytesRef.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/util/BytesRef.java?rev=1353098&r1=1353097&r2=1353098&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/util/BytesRef.java (original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/util/BytesRef.java Sat Jun 23 09:21:50 2012
@@ -23,7 +23,13 @@ import java.util.Comparator;
  *  existing byte[].  The {@link #bytes} member should never be null;
  *  use {@link #EMPTY_BYTES} if necessary.
  *
- *  @lucene.experimental */
+ * <p><b>Important note:</b> Unless otherwise noted, Lucene uses this class to
+ * represent terms that are encoded as <b>UTF8</b> bytes in the index. To
+ * convert them to a Java {@link String} (which is UTF16), use {@link #utf8ToString}.
+ * Using code like {@code new String(bytes, offset, length)} to do this
+ * is <b>wrong</b>, as it does not respect the correct character set
+ * and may return wrong results (depending on the platform's defaults)!
+ */
 public final class BytesRef implements Comparable<BytesRef>,Cloneable {
   /** An empty byte array for convenience */
   public static final byte[] EMPTY_BYTES = new byte[0];