1 package org.apache.lucene.document;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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
24 // do not remove this class in 3.0, it may be needed to decode old indexes!
27 * Provides support for converting longs to Strings, and back again. The strings
28 * are structured so that lexicographic sorting order is preserved.
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".)
36 * This class handles <b>all</b> long values (unlike
37 * {@link org.apache.lucene.document.DateField}).
39 * @deprecated For new indexes use {@link NumericUtils} instead, which
40 * provides a sortable binary representation (prefix encoded) of numeric
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).
48 public class NumberTools {
50 private static final int RADIX = 36;
52 private static final char NEGATIVE_PREFIX = '-';
54 // NB: NEGATIVE_PREFIX must be < POSITIVE_PREFIX
55 private static final char POSITIVE_PREFIX = '0';
57 //NB: this must be less than
59 * Equivalent to longToString(Long.MIN_VALUE)
61 public static final String MIN_STRING_VALUE = NEGATIVE_PREFIX
65 * Equivalent to longToString(Long.MAX_VALUE)
67 public static final String MAX_STRING_VALUE = POSITIVE_PREFIX
71 * The length of (all) strings returned by {@link #longToString}
73 public static final int STR_SIZE = MIN_STRING_VALUE.length();
76 * Converts a long to a String suitable for indexing.
78 public static String longToString(long l) {
80 if (l == Long.MIN_VALUE) {
81 // special case, because long is not symmetric around zero
82 return MIN_STRING_VALUE;
85 StringBuilder buf = new StringBuilder(STR_SIZE);
88 buf.append(NEGATIVE_PREFIX);
89 l = Long.MAX_VALUE + l + 1;
91 buf.append(POSITIVE_PREFIX);
93 String num = Long.toString(l, RADIX);
95 int padLen = STR_SIZE - num.length() - buf.length();
96 while (padLen-- > 0) {
101 return buf.toString();
105 * Converts a String that was returned by {@link #longToString} back to a
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
114 public static long stringToLong(String str) {
116 throw new NullPointerException("string cannot be null");
118 if (str.length() != STR_SIZE) {
119 throw new NumberFormatException("string is the wrong size");
122 if (str.equals(MIN_STRING_VALUE)) {
123 return Long.MIN_VALUE;
126 char prefix = str.charAt(0);
127 long l = Long.parseLong(str.substring(1), RADIX);
129 if (prefix == POSITIVE_PREFIX) {
131 } else if (prefix == NEGATIVE_PREFIX) {
132 l = l - Long.MAX_VALUE - 1;
134 throw new NumberFormatException(
135 "string does not begin with the correct prefix");