You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2023/05/13 18:21:02 UTC
[lucenenet] 02/02: Lucene.Net.Documents.DateTools: Added exceptions to documentation and added nullable reference type support.
This is an automated email from the ASF dual-hosted git repository.
nightowl888 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit f1446f4c314c5df4c9743098e8e4e2670e54a4d6
Author: Shad Storhaug <sh...@shadstorhaug.com>
AuthorDate: Sun May 14 00:26:10 2023 +0700
Lucene.Net.Documents.DateTools: Added exceptions to documentation and added nullable reference type support.
---
src/Lucene.Net/Document/DateTools.cs | 63 +++++++++++++++++++++++++++---------
1 file changed, 48 insertions(+), 15 deletions(-)
diff --git a/src/Lucene.Net/Document/DateTools.cs b/src/Lucene.Net/Document/DateTools.cs
index 916d4c041..b503cc678 100644
--- a/src/Lucene.Net/Document/DateTools.cs
+++ b/src/Lucene.Net/Document/DateTools.cs
@@ -2,6 +2,7 @@
using Lucene.Net.Support;
using System;
using System.Globalization;
+#nullable enable
namespace Lucene.Net.Documents
{
@@ -49,7 +50,7 @@ namespace Lucene.Net.Documents
/// Returns the date format string for the specified <paramref name="resolution"/>
/// or <c>null</c> if the resolution is invalid.
/// </summary>
- private static string ToDateFormat(DateResolution resolution) => resolution switch
+ private static string? ToDateFormat(DateResolution resolution) => resolution switch
{
DateResolution.YEAR => "yyyy",
DateResolution.MONTH => "yyyyMM",
@@ -73,8 +74,11 @@ namespace Lucene.Net.Documents
/// <param name="date">The date to be converted.</param>
/// <param name="resolution">The desired resolution, see
/// <see cref="Round(DateTime, DateResolution)"/>.</param>
- /// <returns>A string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
+ /// <returns>An invariant string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
/// depending on <paramref name="resolution"/>; using UTC as the timezone.</returns>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="resolution"/> is not defined in the <see cref="DateResolution"/> enum.
+ /// </exception>
public static string DateToString(DateTime date, DateResolution resolution)
{
return DateToStringInternal(date, timeZone: null, resolution);
@@ -91,8 +95,12 @@ namespace Lucene.Net.Documents
/// <param name="timeZone">The time zone of the specified <paramref name="date"/>.</param>
/// <param name="resolution">The desired resolution, see
/// <see cref="Round(DateTime, DateResolution)"/>.</param>
- /// <returns>A string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
+ /// <returns>An invariant string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
/// depending on <paramref name="resolution"/>; using UTC as the timezone.</returns>
+ /// <exception cref="ArgumentNullException"><paramref name="timeZone"/> is <c>null</c>.</exception>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="resolution"/> is not defined in the <see cref="DateResolution"/> enum.
+ /// </exception>
public static string DateToString(DateTime date, TimeZoneInfo timeZone, DateResolution resolution)
{
if (timeZone is null)
@@ -101,9 +109,9 @@ namespace Lucene.Net.Documents
return DateToStringInternal(date, timeZone, resolution);
}
- private static string DateToStringInternal(DateTime date, TimeZoneInfo timeZone, DateResolution resolution)
+ private static string DateToStringInternal(DateTime date, TimeZoneInfo? timeZone, DateResolution resolution)
{
- string format = ToDateFormat(resolution);
+ string? format = ToDateFormat(resolution);
if (format is null)
throw new ArgumentException($"Unknown resolution {resolution}.");
@@ -125,11 +133,11 @@ namespace Lucene.Net.Documents
/// </summary>
/// <param name="date">The date to be converted.</param>
/// <param name="resolution">The desired resolution, see <see cref="Round(DateTime, DateResolution)"/>.</param>
- /// <returns>A string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
+ /// <returns>An invariant string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
/// depending on <paramref name="resolution"/>; using UTC as the timezone.</returns>
public static string DateToString(DateTimeOffset date, DateResolution resolution)
{
- string format = ToDateFormat(resolution);
+ string? format = ToDateFormat(resolution);
if (format is null)
throw new ArgumentException($"Unknown resolution {resolution}.");
DateTime d = Round(date.UtcDateTime, resolution);
@@ -146,12 +154,15 @@ namespace Lucene.Net.Documents
/// <param name="resolution">The desired resolution, see
/// <see cref="Round(long, DateResolution, NumericRepresentation, NumericRepresentation)"/>.</param>
/// <param name="inputRepresentation">The numeric representation of <paramref name="time"/>.</param>
- /// <returns>A string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
+ /// <returns>An invariant string in format <c>yyyyMMddHHmmssSSS</c> or shorter,
/// depending on <paramref name="resolution"/>; using GMT as timezone.</returns>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="inputRepresentation"/> is not defined in the <see cref="NumericRepresentation"/> enum.
+ /// </exception>
public static string TimeToString(long time, DateResolution resolution,
NumericRepresentation inputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)
{
- string format = ToDateFormat(resolution);
+ string? format = ToDateFormat(resolution);
if (format is null)
throw new ArgumentException($"Unknown resolution {resolution}.");
DateTime date = new DateTime(Round(time, resolution, inputRepresentation, NumericRepresentation.TICKS), DateTimeKind.Utc);
@@ -169,7 +180,11 @@ namespace Lucene.Net.Documents
/// <param name="outputRepresentation">The numeric representation of the return value.</param>
/// <returns>A numeric representation of <paramref name="dateString"/> represented as specified by
/// <paramref name="outputRepresentation"/>.</returns>
- /// <exception cref="FormatException"><paramref name="dateString"/> is not in the expected format.</exception>
+ /// <exception cref="ParseException"><paramref name="dateString"/> is not in the expected format.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="dateString"/> is <c>null</c>.</exception>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="outputRepresentation"/> is not defined in the <see cref="NumericRepresentation"/> enum.
+ /// </exception>
public static long StringToTime(string dateString, NumericRepresentation outputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)
{
long ticks = StringToDate(dateString).Ticks;
@@ -189,11 +204,15 @@ namespace Lucene.Net.Documents
/// </summary>
/// <param name="dateString"> the date string to be converted </param>
/// <returns> the parsed time as a <see cref="DateTime"/> object </returns>
- /// <exception cref="FormatException"> if <paramref name="dateString"/> is not in the
+ /// <exception cref="ParseException"> if <paramref name="dateString"/> is not in the
/// expected format </exception>
+ /// <exception cref="ArgumentNullException"><paramref name="dateString"/> is <c>null</c>.</exception>
public static DateTime StringToDate(string dateString)
{
- string format = ToDateFormat((DateResolution)dateString.Length);
+ if (dateString is null)
+ throw new ArgumentNullException(nameof(dateString));
+
+ string? format = ToDateFormat((DateResolution)dateString.Length);
if (format is null || !DateTimeOffset.TryParseExact(dateString, format, DateTimeFormatInfo.InvariantInfo, DateTimeStyles.AssumeUniversal, out DateTimeOffset dateOffset))
throw new ParseException($"Input is not valid date string: '{dateString}'.", 0);
@@ -209,6 +228,9 @@ namespace Lucene.Net.Documents
/// <param name="resolution"> The desired resolution of the <see cref="DateTime"/> to be returned. </param>
/// <returns> The <see cref="DateTime"/> with all values more precise than <paramref name="resolution"/>
/// set to their minimum value (0 or 1 depending on the field).</returns>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="resolution"/> is not defined in the <see cref="DateResolution"/> enum.
+ /// </exception>
public static DateTime Round(DateTime date, DateResolution resolution)
{
return new DateTime(Round(date.Ticks, resolution,
@@ -241,6 +263,17 @@ namespace Lucene.Net.Documents
/// <param name="outputRepresentation">The numeric representation of the return value.</param>
/// <returns>The date with all values more precise than <paramref name="resolution"/>
/// set to their minimum value (0 or 1 depending on the field). The return value is expressed in ticks.</returns>
+ /// <exception cref="ArgumentException">
+ /// <paramref name="resolution"/> is not defined in the <see cref="DateResolution"/> enum.
+ /// <para/>
+ /// -or-
+ /// <para/>
+ /// <paramref name="inputRepresentation"/> is not defined in the <see cref="NumericRepresentation"/> enum.
+ /// <para/>
+ /// -or-
+ /// <para/>
+ /// <paramref name="outputRepresentation"/> is not defined in the <see cref="NumericRepresentation"/> enum.
+ /// </exception>
public static long Round(long time, DateResolution resolution,
NumericRepresentation inputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS,
NumericRepresentation outputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)
@@ -384,13 +417,13 @@ namespace Lucene.Net.Documents
/// UTC (also known as the "epoch"). This is the format that Lucene
/// uses, and it is recommended to store this value in the index for compatibility.
/// </summary>
- UNIX_TIME_MILLISECONDS,
+ UNIX_TIME_MILLISECONDS = 0,
/// <summary>
/// The .NET ticks representing a date. Specify this to pass the raw ticks from <see cref="DateTime.Ticks"/>
/// or to instantiate a new <see cref="DateTime"/> from the result.
/// </summary>
- TICKS,
+ TICKS = 1,
/// <summary>
/// .NET ticks as total milliseconds.
@@ -400,6 +433,6 @@ namespace Lucene.Net.Documents
/// This option is provided for compatibility with Lucene.NET 3.0.3 and Lucene.NET 4.8.0-beta00001 through 4.8.0-beta00015,
/// since it was the only option for input representation.
/// </summary>
- TICKS_AS_MILLISECONDS,
+ TICKS_AS_MILLISECONDS = 2,
}
}
\ No newline at end of file