Class DateTools

Provides support for converting dates to strings and vice-versa. The strings are structured so that lexicographic sorting orders them by date, which makes them suitable for use as field values and search terms.

This class also helps you to limit the resolution of your dates. Do not save dates with a finer resolution than you really need, as then TermRangeQuery and PrefixQuery will require more memory and become slower.

Another approach is NumericUtils, which provides a sortable binary representation (prefix encoded) of numeric values, which date/time are.

For indexing a DateTime, just get the UnixTimeMillisecondsToTicks(long) from Ticks and index this as a numeric value with Int64Field and use NumericRangeQuery<T> to query it.

Inheritance

object

DateTools

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Lucene.Net.Documents

Assembly: Lucene.Net.dll

Syntax

public static class DateTools

Methods

DateToString(DateTime, DateResolution)

Converts a DateTime to a string suitable for indexing using the specified resolution.

The date is converted according to its Kind property to the Universal Coordinated Time (UTC) prior to rounding to the the specified resolution. If Kind is Unspecified, Local is assumed.

Declaration

public static string DateToString(DateTime date, DateResolution resolution)

Parameters

Type	Name	Description
DateTime	date	The date to be converted.
DateResolution	resolution	The desired resolution, see Round(DateTime, DateResolution).

Returns

Type	Description
string	An invariant string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using UTC as the timezone.

Exceptions

Type	Condition
ArgumentException	`resolution` is not defined in the DateResolution enum.

DateToString(DateTime, TimeZoneInfo, DateResolution)

Converts a DateTime to a string suitable for indexing using the specified timeZone and resolution.

The date is converted from the specified timeZone to Universal Coordinated Time (UTC) prior to rounding to the the specified resolution.

Declaration

public static string DateToString(DateTime date, TimeZoneInfo timeZone, DateResolution resolution)

Parameters

Type	Name	Description
DateTime	date	The date to be converted.
TimeZoneInfo	timeZone	The time zone of the specified `date`.
DateResolution	resolution	The desired resolution, see Round(DateTime, DateResolution).

Returns

Type	Description
string	An invariant string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using UTC as the timezone.

Exceptions

Type	Condition
ArgumentNullException	`timeZone` is `null`.
ArgumentException	`resolution` is not defined in the DateResolution enum.

DateToString(DateTimeOffset, DateResolution)

Converts a DateTimeOffset to a string suitable for indexing using the specified resolution.

The date is converted using its UtcDateTime property.

Declaration

public static string DateToString(DateTimeOffset date, DateResolution resolution)

Parameters

Type	Name	Description
DateTimeOffset	date	The date to be converted.
DateResolution	resolution	The desired resolution, see Round(DateTime, DateResolution).

Returns

Type	Description
string	An invariant string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using UTC as the timezone.

Round(DateTime, DateResolution)

Limit a date's resolution. For example, the date 2004-09-21 13:50:11 will be changed to 2004-09-01 00:00:00 when using MONTH.

Declaration

public static DateTime Round(DateTime date, DateResolution resolution)

Parameters

Type	Name	Description
DateTime	date	The DateTime to be rounded.
DateResolution	resolution	The desired resolution of the DateTime to be returned.

Returns

Type	Description
DateTime	The DateTime with all values more precise than `resolution` set to their minimum value (0 or 1 depending on the field).

Exceptions

Type	Condition
ArgumentException	`resolution` is not defined in the DateResolution enum.

Round(long, DateResolution, NumericRepresentation, NumericRepresentation)

Limit a date's resolution.

For example, the time 1095774611000 (which represents 2004-09-21 13:50:11) will be changed to 1093996800000 (2004-09-01 00:00:00) when using MONTH and UNIX_TIME_MILLISECONDS for both inputRepresentation and outputRepresentation.

The ticks 632313714110000000 (which represents 2004-09-21 13:50:11) will be changed to 632295936000000000 (2004-09-01 00:00:00) when using MONTH and TICKS for both inputRepresentation and outputRepresentation.

NOTE: For compatibility with Lucene.NET 3.0.3 and Lucene.NET 4.8.0-beta00001 through 4.8.0-beta00015 specify inputRepresentation as TICKS_AS_MILLISECONDS and outputRepresentation as TICKS.

Declaration

public static long Round(long time, DateResolution resolution, NumericRepresentation inputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS, NumericRepresentation outputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)

Parameters

Type	Name	Description
long	time	The ticks that represent the date to be rounded.
DateResolution	resolution	The desired resolution of the date to be returned.
NumericRepresentation	inputRepresentation	The numeric representation of `time`.
NumericRepresentation	outputRepresentation	The numeric representation of the return value.

Returns

Type	Description
long	The date with all values more precise than `resolution` set to their minimum value (0 or 1 depending on the field). The return value is expressed in ticks.

Exceptions

Type	Condition
ArgumentException	`resolution` is not defined in the DateResolution enum. -or- `inputRepresentation` is not defined in the NumericRepresentation enum. -or- `outputRepresentation` is not defined in the NumericRepresentation enum.

StringToDate(string)

Converts a string produced by TimeToString(long, DateResolution, NumericRepresentation) or DateToString(DateTime, DateResolution) back to a time, represented as a DateTime object.

Declaration

public static DateTime StringToDate(string dateString)

Parameters

Type	Name	Description
string	dateString	the date string to be converted

Returns

Type	Description
DateTime	the parsed time as a DateTime object

Exceptions

Type	Condition
ParseException	if `dateString` is not in the expected format
ArgumentNullException	`dateString` is `null`.

StringToTime(string, NumericRepresentation)

Converts a string produced by TimeToString(long, DateResolution, NumericRepresentation) or DateToString(DateTime, DateResolution) back to a time, represented as a long.

NOTE: For compatibility with Lucene.NET 3.0.3 and Lucene.NET 4.8.0-beta00001 through 4.8.0-beta00015 specify outputRepresentation as TICKS.

Declaration

public static long StringToTime(string dateString, NumericRepresentation outputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)

Parameters

Type	Name	Description
string	dateString	The date string to be converted.
NumericRepresentation	outputRepresentation	The numeric representation of the return value.

Returns

Type	Description
long	A numeric representation of `dateString` represented as specified by `outputRepresentation`.

Exceptions

Type	Condition
ParseException	`dateString` is not in the expected format.
ArgumentNullException	`dateString` is `null`.
ArgumentException	`outputRepresentation` is not defined in the NumericRepresentation enum.

TicksToUnixTimeMilliseconds(long)

Converts from .NET ticks to the number of milliseconds since January 1, 1970, 00:00:00 UTC (also known as the "epoch").

This is the value that is stored in Java Lucene indexes and can be used for storing values that can be read by Java Lucene.

Declaration

public static long TicksToUnixTimeMilliseconds(long ticks)

Parameters

Type	Name	Description
long	ticks	The .NET ticks to be converted.

Returns

Type	Description
long	The converted ticks to number of milliseconds since January 1, 1970, 00:00:00 UTC (also known as the "epoch").

TimeToString(long, DateResolution, NumericRepresentation)

Converts from a numeric representation of a time to a string suitable for indexing.

NOTE: For compatibility with Lucene.NET 3.0.3 and Lucene.NET 4.8.0-beta00001 through 4.8.0-beta00015 specify inputRepresentation as TICKS_AS_MILLISECONDS.

Declaration

public static string TimeToString(long time, DateResolution resolution, NumericRepresentation inputRepresentation = NumericRepresentation.UNIX_TIME_MILLISECONDS)

Parameters

Type	Name	Description
long	time	The ticks that represent the date to be converted.
DateResolution	resolution	The desired resolution, see Round(long, DateResolution, NumericRepresentation, NumericRepresentation).
NumericRepresentation	inputRepresentation	The numeric representation of `time`.

Returns

Type	Description
string	An invariant string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using GMT as timezone.

Exceptions

Type	Condition
ArgumentException	`inputRepresentation` is not defined in the NumericRepresentation enum.

UnixTimeMillisecondsToTicks(long)

Converts from the number of milliseconds since January 1, 1970, 00:00:00 UTC (also known as the "epoch") to .NET ticks.

Declaration

public static long UnixTimeMillisecondsToTicks(long unixTimeMilliseconds)

Parameters

Type	Name	Description
long	unixTimeMilliseconds	The number of milliseconds since January 1, 1970, 00:00:00 UTC (also known as the "epoch") to be converted.

Returns

Type	Description
long	The converted .NET ticks that can be used to create a DateTime or DateTimeOffset.