lucene-java-3.4.0/lucene/src/java/org/apache/lucene/document/NumberTools.java

   1 package org.apache.lucene.document;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import org.apache.lucene.document.NumericField; // for javadocs
  21 import org.apache.lucene.search.NumericRangeQuery; // for javadocs
  22 import org.apache.lucene.util.NumericUtils; // for javadocs
  23
  24 // do not remove this class in 3.0, it may be needed to decode old indexes!
  25
  26 /**
  27  * Provides support for converting longs to Strings, and back again. The strings
  28  * are structured so that lexicographic sorting order is preserved.
  29  *
  30  * <p>
  31  * That is, if l1 is less than l2 for any two longs l1 and l2, then
  32  * NumberTools.longToString(l1) is lexicographically less than
  33  * NumberTools.longToString(l2). (Similarly for "greater than" and "equals".)
  34  *
  35  * <p>
  36  * This class handles <b>all</b> long values (unlike
  37  * {@link org.apache.lucene.document.DateField}).
  38  *
  39  * @deprecated For new indexes use {@link NumericUtils} instead, which
  40  * provides a sortable binary representation (prefix encoded) of numeric
  41  * values.
  42  * To index and efficiently query numeric values use {@link NumericField}
  43  * and {@link NumericRangeQuery}.
  44  * This class is included for use with existing
  45  * indices and will be removed in a future release (possibly Lucene 4.0).
  46  */
  47 @Deprecated
  48 public class NumberTools {
  49
  50     private static final int RADIX = 36;
  51
  52     private static final char NEGATIVE_PREFIX = '-';
  53
  54     // NB: NEGATIVE_PREFIX must be < POSITIVE_PREFIX
  55     private static final char POSITIVE_PREFIX = '0';
  56
  57     //NB: this must be less than
  58     /**
  59      * Equivalent to longToString(Long.MIN_VALUE)
  60      */
  61     public static final String MIN_STRING_VALUE = NEGATIVE_PREFIX
  62             + "0000000000000";
  63
  64     /**
  65      * Equivalent to longToString(Long.MAX_VALUE)
  66      */
  67     public static final String MAX_STRING_VALUE = POSITIVE_PREFIX
  68             + "1y2p0ij32e8e7";
  69
  70     /**
  71      * The length of (all) strings returned by {@link #longToString}
  72      */
  73     public static final int STR_SIZE = MIN_STRING_VALUE.length();
  74
  75     /**
  76      * Converts a long to a String suitable for indexing.
  77      */
  78     public static String longToString(long l) {
  79
  80         if (l == Long.MIN_VALUE) {
  81             // special case, because long is not symmetric around zero
  82             return MIN_STRING_VALUE;
  83         }
  84
  85         StringBuilder buf = new StringBuilder(STR_SIZE);
  86
  87         if (l < 0) {
  88             buf.append(NEGATIVE_PREFIX);
  89             l = Long.MAX_VALUE + l + 1;
  90         } else {
  91             buf.append(POSITIVE_PREFIX);
  92         }
  93         String num = Long.toString(l, RADIX);
  94
  95         int padLen = STR_SIZE - num.length() - buf.length();
  96         while (padLen-- > 0) {
  97             buf.append('0');
  98         }
  99         buf.append(num);
 100
 101         return buf.toString();
 102     }
 103
 104     /**
 105      * Converts a String that was returned by {@link #longToString} back to a
 106      * long.
 107      *
 108      * @throws IllegalArgumentException
 109      *             if the input is null
 110      * @throws NumberFormatException
 111      *             if the input does not parse (it was not a String returned by
 112      *             longToString()).
 113      */
 114     public static long stringToLong(String str) {
 115         if (str == null) {
 116             throw new NullPointerException("string cannot be null");
 117         }
 118         if (str.length() != STR_SIZE) {
 119             throw new NumberFormatException("string is the wrong size");
 120         }
 121
 122         if (str.equals(MIN_STRING_VALUE)) {
 123             return Long.MIN_VALUE;
 124         }
 125
 126         char prefix = str.charAt(0);
 127         long l = Long.parseLong(str.substring(1), RADIX);
 128
 129         if (prefix == POSITIVE_PREFIX) {
 130             // nop
 131         } else if (prefix == NEGATIVE_PREFIX) {
 132             l = l - Long.MAX_VALUE - 1;
 133         } else {
 134             throw new NumberFormatException(
 135                     "string does not begin with the correct prefix");
 136         }
 137
 138         return l;
 139     }
 140 }