lucene.net源码学习笔记（二）

今天看了一下DateTool.cs里面的源码，这个文件里的代码还是比较简单的。DateTool类提供一些日期字符串与日期时间类型之间的互相转换。与DateField类不同是，DateField中的日期字符串是一串36进制的字符串，而这里的日期字符串是我们常见的格式，如"yyyy","yyyymm"等。DateTool类里面还嵌套了一个Resolution类。该类采用多例模式，内置了YEAR,MONTH,DAY,HOUR,MINUTE,SECOND,MILLISECOND 7个实例，用以表示时间的分辨率。当日期时间类型转换成日期字符串时，需要一个Resolution作为参数，例如日期时间为2009年2月24日，Resolution参数为MONTH，转换之后的日期字符串则为"200902"("yyyymm")。下面是我对源码的一些分析。

 

  1 /**/ /*
  2 * Licensed to the Apache Software Foundation (ASF) under one or more
  3 * contributor license agreements.  See the NOTICE file distributed with
  4 * this work for additional information regarding copyright ownership.
  5 * The ASF licenses this file to You under the Apache License, Version 2.0
  6 * (the "License"); you may not use this file except in compliance with
  7 * the License.  You may obtain a copy of the License at
  8 * 
  9 * http://www.apache.org/licenses/LICENSE-2.0
 10 * 
 11 * Unless required by applicable law or agreed to in writing, software
 12 * distributed under the License is distributed on an "AS IS" BASIS,
 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14 * See the License for the specific language governing permissions and
 15 * limitations under the License.
 16 */
 17
 18 using  System;
 19
 20 namespace  Lucene.Net.Documents
 21 {
 22    
 23    /**//// <summary> Provides support for converting dates to strings and vice-versa.
 24    /// The strings are structured so that lexicographic sorting orders 
 25    /// them by date, which makes them suitable for use as field values 
 26    /// and search terms.
 27    /// 
 28    /// <P>This class also helps you to limit the resolution of your dates. Do not
 29    /// save dates with a finer resolution than you really need, as then
 30    /// RangeQuery and PrefixQuery will require more memory and become slower.
 31    /// 
 32    /// <P>Compared to {@link DateField} the strings generated by the methods
 33    /// in this class take slightly more space, unless your selected resolution
 34    /// is set to <code>Resolution.DAY</code> or lower.
 35    /// </summary>
 36    public class DateTools
 37    {
 38
 39        //私有的构造函数，由于该类只是提供一些静态方法，因此无需被实例化
 40        private DateTools()
 41        {
 42        }
 43        
 44        /**//// <summary> Converts a Date to a string suitable for indexing.
 45        /// 将日期时间类型对象转换成日期字符串（yyyy,yyyymm,yyyymmdd.）
 46        /// </summary>
 47        /// <param name="date">the date to be converted
 48        /// </param>
 49        /// <param name="resolution">the desired resolution, see
 50        /// {@link #Round(Date, DateTools.Resolution)}
 51        /// </param>
 52        /// <returns> a string in format <code>yyyyMMddHHmmssSSS</code> or shorter,
 53        /// depeding on <code>resolution</code>
 54        /// </returns>
 55        public static System.String DateToString(System.DateTime date, Resolution resolution)
 56        {
 57            return TimeToString(date.Ticks, resolution);
 58        }
 59        
 60        /**//// <summary> Converts a millisecond time to a string suitable for indexing.
 61        /// 将长整型日期time转换成日期字符串，通过DateTime对象的Ticks可以得到这样的time值，Ticks的单位是100纳秒，而这里的英文注释说是毫秒，应该是错误的
 62        /// </summary>
 63        /// <param name="time">the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
 64        /// 看不出这里的代码与1970年1月1日有什么关联，可能是受DateField能表示的最小时间影响吧
 65        /// </param>
 66        /// <param name="resolution">the desired resolution, see
 67        /// {@link #Round(long, DateTools.Resolution)}
 68        /// </param>
 69        /// <returns> a string in format <code>yyyyMMddHHmmssSSS</code> or shorter,
 70        /// depeding on <code>resolution</code>; using UTC as timezone
 71        /// </returns>
 72        public static System.String TimeToString(long time, Resolution resolution)
 73        {
 74            // cal这个对象似乎在这里是没有用处的
 75            System.Globalization.Calendar cal = new System.Globalization.GregorianCalendar(); // {{Aroush}} do we care about 'cal'
 76            
 77            //protected in JDK's prior to 1.4
 78            // 下面的setTimeInMillis在.net找不着，应该是java里面的
 79            //cal.setTimeInMillis(round(time, resolution));
 80            
 81            // 调用Round方法对time进行舍入操作，不过这个舍入操作在这里似乎是多余的，调用ToString函数应该可以完成转换了，不明白为什么要在这里进行舍入操作
 82            System.DateTime dt = new System.DateTime(Round(time, resolution));
 83
 84            System.String t = "";
 85
 86            // 根据不同分辨率转换成不同的日期字符串
 87            if (resolution == Resolution.YEAR)
 88            {
 89                t = dt.ToString("yyyy");
 90            }
 91            else if (resolution == Resolution.MONTH)
 92            {
 93                t = dt.ToString("yyyyMM");
 94            }
 95            else if (resolution == Resolution.DAY)
 96            {
 97                t = dt.ToString("yyyyMMdd");
 98            }
 99            else if (resolution == Resolution.HOUR)
100            {
101                t = dt.ToString("yyyyMMddHH");
102            }
103            else if (resolution == Resolution.MINUTE)
104            {
105                t = dt.ToString("yyyyMMddHHmm");
106            }
107            else if (resolution == Resolution.SECOND)
108            {
109                t = dt.ToString("yyyyMMddHHmmss");
110            }
111            else if (resolution == Resolution.MILLISECOND)
112            {
113                t = dt.ToString("yyyyMMddHHmmssfff");
114            }
115            else
116            {
117                throw new System.ArgumentException("unknown resolution " + resolution);
118            }
119
120            return t;
121        }
122        
123        /**//// <summary> Converts a string produced by <code>timeToString</code> or
124        /// <code>DateToString</code> back to a time, represented as the
125        /// number of milliseconds since January 1, 1970, 00:00:00 GMT.
126        /// 将日期字符串转换成对应时间的长整型值
127        /// </summary>
128        /// <param name="dateString">the date string to be converted
129        /// </param>
130        /// <returns> the number of milliseconds since January 1, 1970, 00:00:00 GMT
131        /// </returns>
132        /// <throws>  ParseException if <code>dateString</code> is not in the  </throws>
133        /// <summary>  expected format 
134        /// </summary>
135        public static long StringToTime(System.String dateString)
136        {
137            return StringToDate(dateString).Ticks;
138        }
139        
140        /**//// <summary> Converts a string produced by <code>timeToString</code> or
141        /// <code>DateToString</code> back to a time, represented as a
142        /// Date object.
143        /// 将日期字符串转换成对应的日期时间类型
144        /// </summary>
145        /// <param name="dateString">the date string to be converted
146        /// </param>
147        /// <returns> the parsed time as a Date object 
148        /// </returns>
149        /// <throws>  ParseException if <code>dateString</code> is not in the  </throws>
150        /// <summary>  expected format 
151        /// </summary>
152        public static System.DateTime StringToDate(System.String dateString)
153        {
154            System.String yyyy = "1";
155            System.String MM = "1";
156            System.String dd = "1";
157            System.String HH = "0";
158            System.String mm = "0";
159            System.String ss = "0";
160            System.String SSS = "0";
161
162            if (dateString.Length == 4)     // "yyyy"
163            {
164                yyyy = dateString.Substring(0, 4);
165            }
166            else if (dateString.Length == 6)     // "yyyyMM";
167            {
168                yyyy = dateString.Substring(0, 4);
169                MM = dateString.Substring(4, 2);
170            }
171            else if (dateString.Length == 8)     // "yyyyMMdd"
172            {
173                yyyy = dateString.Substring(0, 4);
174                MM = dateString.Substring(4, 2);
175                dd = dateString.Substring(6, 2);
176            }
177            else if (dateString.Length == 10)    // "yyyyMMddHH"
178            {
179                yyyy = dateString.Substring(0, 4);
180                MM = dateString.Substring(4, 2);
181                dd = dateString.Substring(6, 2);
182                HH = dateString.Substring(8, 2);
183            }
184            else if (dateString.Length == 12)    // "yyyyMMddHHmm";
185            {
186                yyyy = dateString.Substring(0, 4);
187                MM = dateString.Substring(4, 2);
188                dd = dateString.Substring(6, 2);
189                HH = dateString.Substring(8, 2);
190                mm = dateString.Substring(10, 2);
191            }
192            else if (dateString.Length == 14)    // "yyyyMMddHHmmss";
193            {
194                yyyy = dateString.Substring(0, 4);
195                MM = dateString.Substring(4, 2);
196                dd = dateString.Substring(6, 2);
197                HH = dateString.Substring(8, 2);
198                mm = dateString.Substring(10, 2);
199                ss = dateString.Substring(12, 2);
200            }
201            else if (dateString.Length == 17)    // "yyyyMMddHHmmssSSS";
202            {
203                yyyy = dateString.Substring(0, 4);
204                MM = dateString.Substring(4, 2);
205                dd = dateString.Substring(6, 2);
206                HH = dateString.Substring(8, 2);
207                mm = dateString.Substring(10, 2);
208                ss = dateString.Substring(12, 2);
209                SSS = dateString.Substring(14, 3);
210            }
211            else
212            {
213                throw new System.FormatException("Input is not valid date string: " + dateString);
214            }
215
216            int y, M, d, H, m, s, S;
217            y = Convert.ToInt16(yyyy);
218            M = Convert.ToInt16(MM);
219            d = Convert.ToInt16(dd);
220            H = Convert.ToInt16(HH);
221            m = Convert.ToInt16(mm);
222            s = Convert.ToInt16(ss);
223            S = Convert.ToInt16(SSS);
224
225            return new System.DateTime(y, 
226                M, d, H, 
227                m, s, S);
228
229            // 没用的代码为什么不删掉
230            //return new System.DateTime(Convert.ToInt16(yyyy), 
231            //    Convert.ToInt16(MM), Convert.ToInt16(dd), Convert.ToInt16(HH), 
232            //    Convert.ToInt16(mm), Convert.ToInt16(ss), Convert.ToInt16(SSS));
233        }
234        
235        /**//// <summary> Limit a date's resolution. For example, the date <code>2004-09-21 13:50:11</code>
236        /// will be changed to <code>2004-09-01 00:00:00</code> when using
237        /// <code>Resolution.MONTH</code>. 
238        /// 根据Resolution参数对日期时间类型进行舍入操作，例如2009年2月24日8点30分30秒，若Resolution为Month，则舍入的结果为2009年2月1日0点0分0秒
239        /// </summary>
240        /// <param name="resolution">The desired resolution of the date to be returned
241        /// </param>
242        /// <returns> the date with all values more precise than <code>resolution</code>
243        /// set to 0 or 1
244        /// </returns>
245        public static System.DateTime Round(System.DateTime date, Resolution resolution)
246        {
247            return new System.DateTime(Round(date.Ticks, resolution));
248        }
249        
250        /**//// <summary> Limit a date's resolution. For example, the date <code>1095767411000</code>
251        /// (which represents 2004-09-21 13:50:11) will be changed to 
252        /// <code>1093989600000</code> (2004-09-01 00:00:00) when using
253        /// <code>Resolution.MONTH</code>.
254        /// 根据Resolution参数对日期时间类型进行舍入操作
255        /// </summary>
256        /// <param name="resolution">The desired resolution of the date to be returned
257        /// </param>
258        /// <returns> the date with all values more precise than <code>resolution</code>
259        /// set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT
260        /// </returns>
261        public static long Round(long time, Resolution resolution)
262        {
263            System.Globalization.Calendar cal = new System.Globalization.GregorianCalendar(); // {{Aroush}} do we care about 'cal'
264            
265            // protected in JDK's prior to 1.4
266            //cal.setTimeInMillis(time);
267            
268            System.DateTime dt = new System.DateTime(time);
269            
270            //根据不同分辨率，减去相应的时间偏移量
271            if (resolution == Resolution.YEAR)
272            {
273                dt = dt.AddMonths(1 - dt.Month);
274                dt = dt.AddDays(1 - dt.Day);
275                dt = dt.AddHours(0 - dt.Hour);
276                dt = dt.AddMinutes(0 - dt.Minute);
277                dt = dt.AddSeconds(0 - dt.Second);
278                dt = dt.AddMilliseconds(0 - dt.Millisecond);
279            }
280            else if (resolution == Resolution.MONTH)
281            {
282                dt = dt.AddDays(1 - dt.Day);
283                dt = dt.AddHours(0 - dt.Hour);
284                dt = dt.AddMinutes(0 - dt.Minute);
285                dt = dt.AddSeconds(0 - dt.Second);
286                dt = dt.AddMilliseconds(0 - dt.Millisecond);
287            }
288            else if (resolution == Resolution.DAY)
289            {
290                dt = dt.AddHours(0 - dt.Hour);
291                dt = dt.AddMinutes(0 - dt.Minute);
292                dt = dt.AddSeconds(0 - dt.Second);
293                dt = dt.AddMilliseconds(0 - dt.Millisecond);
294            }
295            else if (resolution == Resolution.HOUR)
296            {
297                dt = dt.AddMinutes(0 - dt.Minute);
298                dt = dt.AddSeconds(0 - dt.Second);
299                dt = dt.AddMilliseconds(0 - dt.Millisecond);
300            }
301            else if (resolution == Resolution.MINUTE)
302            {
303                dt = dt.AddSeconds(0 - dt.Second);
304                dt = dt.AddMilliseconds(0 - dt.Millisecond);
305            }
306            else if (resolution == Resolution.SECOND)
307            {
308                dt = dt.AddMilliseconds(0 - dt.Millisecond);
309            }
310            else if (resolution == Resolution.MILLISECOND)
311            {
312                // don't cut off anything
313            }
314            else
315            {
316                throw new System.ArgumentException("unknown resolution " + resolution);
317            }
318            return dt.Ticks;
319        }
320        
321        /**//// <summary>Specifies the time granularity. 
322        /// 采用多例模式，内置了YEAR,MONTH,DAY,HOUR,MINUTE,SECOND,MILLISECOND 7个实例
323        /// </summary>
324        public class Resolution
325        {
326            public static readonly Resolution YEAR = new Resolution("year");
327            public static readonly Resolution MONTH = new Resolution("month");
328            public static readonly Resolution DAY = new Resolution("day");
329            public static readonly Resolution HOUR = new Resolution("hour");
330            public static readonly Resolution MINUTE = new Resolution("minute");
331            public static readonly Resolution SECOND = new Resolution("second");
332            public static readonly Resolution MILLISECOND = new Resolution("millisecond");
333            
334            private System.String resolution;
335            
336            internal Resolution()
337            {
338            }
339            
340            internal Resolution(System.String resolution)
341            {
342                this.resolution = resolution;
343            }
344            
345            public override System.String ToString()
346            {
347                return resolution;
348            }
349        }
350    }
351}

转载于:https://www.cnblogs.com/laizhenyuan/archive/2009/02/24/1397500.html