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

[us...@apache.org]

Author: uschindler
Date: Sat Jun 23 09:23:39 2012
New Revision: 1353099

URL: http://svn.apache.org/viewvc?rev=1353099&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/lucene_solr_3_6/   (props changed)
    lucene/dev/branches/lucene_solr_3_6/lucene/   (props changed)
    lucene/dev/branches/lucene_solr_3_6/lucene/core/src/   (props changed)
    lucene/dev/branches/lucene_solr_3_6/lucene/core/src/java/org/apache/lucene/util/BytesRef.java

Modified: lucene/dev/branches/lucene_solr_3_6/lucene/core/src/java/org/apache/lucene/util/BytesRef.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene_solr_3_6/lucene/core/src/java/org/apache/lucene/util/BytesRef.java?rev=1353099&r1=1353098&r2=1353099&view=diff
==============================================================================
--- lucene/dev/branches/lucene_solr_3_6/lucene/core/src/java/org/apache/lucene/util/BytesRef.java (original)
+++ lucene/dev/branches/lucene_solr_3_6/lucene/core/src/java/org/apache/lucene/util/BytesRef.java Sat Jun 23 09:23:39 2012
@@ -23,7 +23,15 @@ import java.io.UnsupportedEncodingExcept
 /** Represents byte[], as a slice (offset + length) into an
  *  existing byte[].
  *
- *  @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)!
+ *
+ * @lucene.experimental
+ */
 public final class BytesRef implements Comparable<BytesRef>,Cloneable {
   /** An empty byte array for convenience */
   public static final byte[] EMPTY_BYTES = new byte[0];