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 System.DateTime, just get the UnixTimeMillisecondsToTicks(Int64) from System.DateTime.Ticks and index this as a numeric value with Int64Field and use NumericRangeQuery<T> to query it.

Inheritance

System.Object

DateTools

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Lucene.Net.Documents

Assembly: Lucene.Net.dll

Syntax

public static class DateTools

Methods

| Improve this Doc View Source

DateToString(DateTime, DateResolution)

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

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

Declaration

public static string DateToString(DateTime date, DateResolution resolution)

Parameters

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

Returns

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

| Improve this Doc View Source

DateToString(DateTime, TimeZoneInfo, DateResolution)

Converts a System.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
System.DateTime	date	The date to be converted.
System.TimeZoneInfo	timeZone	The time zone of the specified `date`.
DateResolution	resolution	The desired resolution, see Round(DateTime, DateResolution).

Returns

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

| Improve this Doc View Source

DateToString(DateTimeOffset, DateResolution)

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

The date is converted using its System.DateTimeOffset.UtcDateTime property.

Declaration

public static string DateToString(DateTimeOffset date, DateResolution resolution)

Parameters

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

Returns

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

| Improve this Doc View Source

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
System.DateTime	date	The System.DateTime to be rounded.
DateResolution	resolution	The desired resolution of the System.DateTime to be returned.

Returns

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

| Improve this Doc View Source

Round(Int64, 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
System.Int64	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
System.Int64	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.

| Improve this Doc View Source

StringToDate(String)

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

Declaration

public static DateTime StringToDate(string dateString)

Parameters

Type	Name	Description
System.String	dateString	the date string to be converted

Returns

Type	Description
System.DateTime	the parsed time as a System.DateTime object

Exceptions

Type	Condition
System.FormatException	if `dateString` is not in the expected format

| Improve this Doc View Source

StringToTime(String, NumericRepresentation)

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

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
System.String	dateString	The date string to be converted.
NumericRepresentation	outputRepresentation	The numeric representation of the return value.

Returns

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

Exceptions

Type	Condition
System.FormatException	`dateString` is not in the expected format.

| Improve this Doc View Source

TicksToUnixTimeMilliseconds(Int64)

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
System.Int64	ticks	The .NET ticks to be converted.

Returns

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

| Improve this Doc View Source

TimeToString(Int64, 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
System.Int64	time	The ticks that represent the date to be converted.
DateResolution	resolution	The desired resolution, see Round(Int64, DateResolution, NumericRepresentation, NumericRepresentation).
NumericRepresentation	inputRepresentation	The numeric representation of `time`.

Returns

Type	Description
System.String	A string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using GMT as timezone.

| Improve this Doc View Source

UnixTimeMillisecondsToTicks(Int64)

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
System.Int64	unixTimeMilliseconds	The number of milliseconds since January 1, 1970, 00:00:00 UTC (also known as the "epoch") to be converted.

Returns

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