Date and Time Values

Before you can fully understand date and time controls, you must first be familiar with how the .NET Framework deals with date and time values. Two different structures are provided for representing dates and times. The DateTime structure represents a specific point in time, while the TimeSpan structure represents a length of time. These structures are described in the next two sections.

16.2.1 DateTime Structure

Date and time values in the .NET Framework are typically represented with a DateTime structure. This structure is a value type representing a point in time, typically expressed with both a date and a time component. Like a class, it has constructors, fields, properties and methods, plus several operators, all for the purpose of allowing your code to represent and manipulate date and time values.

Time values in the .NET Framework are measured in units of ticks, each 100 nanoseconds long. Dates are measured as the number of ticks since midnight, January 1, 1 C.E. in the Gregorian calendar, unless a different calendar is explicitly specified.

The civil calendar in common use today is called the Gregorian calendar, named after Pope Gregory XIII. In 1582 he ordered changes to the calendar then in use to correct errors arising from the fact that a solar year is approximately 11 minutes short of 365 1/4 days. It is nominally based on the year of the birth of Jesus. Years prior to the birth of Jesus are referred to either as B.C. (Before Christ) or B.C.E. (Before the Common Era), and years after the birth of Jesus are referred to as A.D. (Latin abbreviation for Anno Domini, which translates to "in the year of the Lord") or C.E. (Common Era). The German astronomer Johannes Kepler (1571-1630) later showed that Jesus was actually born in the year 4 B.C.E.

Time values can be either positive or negative. They can be expressed in units of ticks, seconds, hours, or in instances of TimeSpan (described below). Time values can be added to or subtracted from DateTime objects. All DateTime calculations assume the same time zone, so your program must take differing time zones into account. All methods and properties of the DateTime class use the local time zone.

There are seven overloaded forms of the DateTime structure's constructor. Table 16-1 lists the arguments for each different constructor.

Table 16-1. DateTime constructors

Argument types

Description

Long

Number of ticks.

Integer, integer, integer

Year (1 through 9999), month (1 through 12), and day (1 through number of days in month).

Integer, integer, integer, Calendar

Year, month, and day using the specified calendar object.

Integer, integer, integer, integer, integer, integer

Year, month, day, hour (0 through 23), minute (0 through 59), and seconds (0 through 59).

Integer, integer, integer, integer, integer, integer, Calendar

Year, month, day, hour, minute, and seconds using the specified calendar object.

Integer, integer, integer, integer, integer, integer, integer

Year, month, day, hour, minute, seconds, and milliseconds.

Integer, integer, integer, integer, integer, integer, integer, Calendar

Year, month, day, hour, minute, seconds, and milliseconds using the specified calendar object.

The DateTime structure has two public read-only fields. MaxValue represents the largest possible value, corresponding to one tick before January 1, 10000, or 23:59:59.9999999 December 31, 9999. MinValue represents the smallest possible value, corresponding to 00:00:00.0000000 January 1, 0001.

A number of read-only properties, some static (Shared in VB.NET), provide date-time functionality, listed in Table 16-2.

Table 16-2. DateTime properties

Property

Value type

Description

Date

DateTime

The date component of the DateTime instance, with the time set to 12:00 AM (midnight 00:00:00).

Day

Integer

The day of the month of the DateTime instance. An integer between 1 and 31, inclusive.

DayOfWeek

DayOfWeek

The day of the week enumerated constant. Sunday corresponds to zero, Monday to one, and so forth.

DayOfYear

Integer

The day of the year, between 1 and 366, inclusive, of the DateTime instance.

Hour

Integer

The hour component of the DateTime instance. An integer between 0 and 23, inclusive.

Millisecond

Integer

The millisecond component of the DateTime instance. An integer between 0 and 999, inclusive.

Minute

Integer

The minute component of the DateTime instance. An integer between 0 and 59, inclusive.

Month

Integer

The month component of the DateTime instance. An integer between 1 and 12, inclusive.

Now

DateTime

Static. The current local date and time. The resolution depends on the OS: 55 milliseconds under Win98, 16 milliseconds under WinNT 3.1, and 10 milliseconds under WinNT 3.5 and later.

Second

Integer

The seconds component of the DateTime instance. An integer between 0 and 59, inclusive.

Ticks

Long

The number of 100 nanosecond ticks representing the DateTime instance. It is a number between MinValue and MaxValue.

TimeOfDay

TimeSpan

The span of time since midnight of the current day.

Today

DateTime

Static. The current local date. The time portion of the DateTime is 12:00 AM (midnight 00:00:00).

UtcNow

DateTime

Static. The current local date and time expressed as coordinated universal time (UTC), previously known as Greenwich Mean Time (GMT). The resolution is the same as for the Now property.

Year

Integer

The year component of the DateTime instance. An integer between 1 and 9999, inclusive.

The DateTime methods, the most commonly used of which are listed in Table 16-3, perform DateTime manipulation, such as adding and subtracting date-time values, comparing values, and converting from one format to another.

Table 16-3. DateTime methods

Method

Description

Add

Adds TimeSpan object to DateTime. Returns a new DateTime.

AddDays

Adds number of whole and fractional days, positive or negative, to DateTime. Returns a new DateTime.

AddHours

Adds number of whole and fractional hours, positive or negative, to DateTime. Returns a new DateTime.

AddMilliseconds

Adds number of whole and fractional milliseconds, positive or negative, to DateTime. Returns a new DateTime.

AddMinutes

Adds number of whole and fractional minutes, positive or negative, to DateTime. Returns a new DateTime.

AddMonths

Adds integer number of months, positive or negative, to DateTime. Returns a new DateTime.

AddSeconds

Adds number of whole and fractional seconds, positive or negative, to DateTime. Returns a new DateTime.

AddTicks

Adds number of ticks, positive or negative, to DateTime. Returns a new DateTime.

AddYears

Adds integer number of years, positive or negative, to DateTime. Returns a new DateTime.

Compare

Static. Compares two DateTime objects. Returns zero if they are equal, less then zero if the first is less than the second, and greater then zero if the first is greater than the second.

CompareTo

Compares this instance to a specified DateTime object. Returns same as Compare method, except it also returns greater than zero if specified DateTime object is null (Nothing).

DaysInMonth

Static. Returns number of days in specified year and month (number from 1 to 12). Takes leap year into account.

Equals

Overloaded. Static version returns true if two DateTimes represent the same date-time value. Instance version returns true if DateTime represents the same date-time value as the instance.

FromFileTime

Static. Returns DateTime object representing OS file timestamp.

GetDateTimeFormats

Overloaded. Returns string array containing all the representations supported by standard DateTime format specifiers.

IsLeapYear

Static. Returns true if specified year is leap year, false otherwise.

Parse

Static. Overloaded. Converts specified string to DateTime object.

ParseExact

Static. Overloaded. Converts specified string, which must precisely match a specified format, to DateTime object.

Subtract

Overloaded. Subtracts the specified DateTime or TimeSpan and returns a TimeSpan or DateTime object, respectively.

ToFileTime

Converts this instance to local system file time format, which is 64-bit unsigned value representing number of ticks since January 1, 1601 12:00 AM.

ToLocalTime

Returns local DateTime object equivalent to current UTC time adjusted for local time zone and daylight saving time.

ToLongDateString

Returns equivalent long date string representation, containing name of the day, name of the month, numeric day of month, and year. Equivalent to ToString or to using "D" format character from Table 16-10.

ToLongTimeString

Returns equivalent long time string representation. Equivalent to using "T" format character from Table 16-10.

ToShortDateString

Returns equivalent short date string representation, containing numeric month, numeric day of month, and year. Equivalent to using "d" format character from Table 16-10.

ToShortTimeString

Returns equivalent short time string representation. Equivalent to using "t" format character from Table 16-10.

ToString

Overloaded, overrides. Returns string representation, optionally using specified format and culture information.

ToUniversalTime

Returns UTC DateTime object equivalent to current local time.

The DateTime structure provides several arithmetic and logical operators, listed in Table 16-4. All of these operators have equivalent methods.

Table 16-4. DateTime operators

Operator

Description

Addition

Adds a DateTime and a TimeSpan, returning a DateTime. In C#, use the plus sign (+). In VB.NET, use DateTime.op_Addition. Equivalent to Add method.

Equality

Returns true if two DateTimes are equal. In C#, use two equal signs (==). In VB.NET, use DateTime.op_Equality. Equivalent to Equals method.

Greater Than

Returns true if first DateTime is greater than the second. In C#, use the greater-than sign (>). In VB.NET, use DateTime.op_GreaterThan. Equivalent to Compare method.

Greater Than or Equal

Returns true if first DateTime is greater than the second. In C#, use the greater than or equal signs (>=). In VB.NET, use DateTime.op_GreaterThanOrEqual. Equivalent to Compare method.

Inequality

Returns true if the two DateTimes do not represent the same date and time. In C#, use the inequality signs (!=). In VB.NET, use DateTime.op_Inequality. Equivalent to Equals method.

Less Than

Returns true if first DateTime is less than the second. In C#, use the less-than sign (<). In VB.NET, use DateTime.op_LessThan. Equivalent to Compare method.

Less Than or Equal

Returns true if first DateTime is less than or equal to the second. In C#, use the less than or equal signs (<=). In VB.NET, use DateTime.op_LessThanOrEqual. Equivalent to Compare method.

Subtraction

Overloaded. Either subtracts one DateTime from another, returning a TimeSpan, or subtracts a TimeSpan from a DateTime, returning a DateTime. In C#, use the minus sign (-). In VB.NET, use DateTime.op_Subtraction. Equivalent to Subtract method.

16.2.2 TimeSpan Structure

The TimeSpan object, also a structure, represents a period of time, in number of ticks. TimeSpan values can be either positive or negative. It resembles the DateTime object in constructors, properties, methods and operators, with just enough differences to drive you crazy.

There are four overloaded forms of the constructor for the TimeSpan structure. Table 16-5 lists the arguments for each constructor.

Table 16-5. TimeSpan constructors

Argument types

Description

long

Number of ticks.

integer, integer, integer

Hours, minutes, and seconds.

integer, integer, integer, integer

Days, hours, minutes, and seconds.

integer, integer, integer, integer, integer

Days, hours, minutes, seconds, and milliseconds.

The string representation of TimeSpan objects includes components for the sign, days, hours, minutes, seconds, and fractional seconds to seven decimal places, of the form [-][d.]hh:mm:ss[.ff], where characters in brackets are optional. So, for example, you could create a new TimeSpan object with the following line of code:

TimeSpan ts = new TimeSpan(1,2,10,10,500)

This TimeSpan instance would represent a period of 1 day, 2 hours, 10 minutes, 10 seconds, and 500 milliseconds. The string representation of this object, obtained by using the ToString method listed in Table 16-7, would be:

1.02:10:10.5000000

Conversely, the Parse method, also listed in Table 16-7, can convert strings to TimeSpan objects. So for example, the following two lines of code:

TimeSpan ts = new TimeSpan( )
ts = TimeSpan.Parse("-1:15:15.1234")

result in a TimeSpan object representing negative one hour, 15 minutes, 15.1234 seconds, with the following string representation:

-01:15:15.1234000

The properties of the TimeSpan structure, all of which are read-only and apply to specific instances of the structure, are listed in Table 16-6.

Table 16-6. TimeSpan properties

Property

Value type

Description

Days

Integer

Read-only. The day component of the TimeSpan object.

Hours

Integer

Read-only. The hour component of the TimeSpan object.

Milliseconds

Integer

Read-only. The millisecond component of the TimeSpan object.

Minutes

Integer

Read-only. The minute component of the TimeSpan object.

Seconds

Integer

Read-only. The second component of the TimeSpan object.

Ticks

Long

Read-only. The number of 100 nanosecond ticks contained in the TimeSpan object.

TotalDays

Double

Read-only. The number of whole and fractional days contained in the TimeSpan object.

TotalHours

Double

Read-only. The number of whole and fractional hours contained in the TimeSpan object.

TotalMilliseconds

Double

Read-only. The number of whole and fractional milliseconds contained in the TimeSpan object.

TotalMinutes

Double

Read-only. The number of whole and fractional minutes contained in the TimeSpan object.

TotalSeconds

Double

Read-only. The number of whole and fractional seconds contained in the TimeSpan object.

The commonly used methods of the TimeSpan structure are listed in Table 16-7. Notice that some methods are static (shared in VB.NET).

Table 16-7. TimeSpan methods

Method

Description

Add

Adds TimeSpan object to TimeSpan. Returns a new TimeSpan.

Compare

Static. Compares two TimeSpan objects. Returns zero if they are equal, less then zero if the first is less than the second, and greater then zero if the first is greater than the second.

CompareTo

Compares this instance to a specified TimeSpan object. Returns the same as Compare method, except it also returns greater than zero if specified TimeSpan object is null (Nothing).

Duration

Returns a TimeSpan object that is the absolute value (i.e., always positive) of this TimeSpan instance.

Equals

Overloaded. Static version returns true if two TimeSpans represent the same value. Instance version returns true if the specified TimeSpan represents the same value as the instance.

FromDays

Static. Returns a TimeSpan representing the specified number of days, accurate to the nearest millisecond.

FromHours

Static. Returns a TimeSpan representing the specified number of hours, accurate to the nearest millisecond.

FromMilliseconds

Static. Returns a TimeSpan representing the specified number of milliseconds.

FromMinutes

Static. Returns a TimeSpan representing the specified number of minutes, accurate to the nearest millisecond.

FromSeconds

Static. Returns a TimeSpan representing the specified number of seconds, accurate to the nearest millisecond.

FromTicks

Static. Returns a TimeSpan representing the specified number of ticks.

Negate

Returns a TimeSpan object with the same value as the instance, but of the opposite sign.

Parse

Static. Converts specified string to TimeSpan object.

Subtract

Subtracts the specified TimeSpan and returns a TimeSpan object.

ToString

Returns a string representation of the TimeSpan instance in the form [-][d.]hh:mm:ss[.ff], where characters in brackets are optional. Does not accept any formatting strings as arguments.

The TimeSpan structure provides several arithmetic and logical operators, listed in Table 16-8. Except for the two unary operators, all of these operators have equivalent methods.

Table 16-8. TimeSpan operators

Operator

Description

Addition

Adds two TimeSpan objects, returning a TimeSpan. In C#, use the plus sign (+). In VB.NET, use TimeSpan.op_Addition. Equivalent to Add method.

Equality

Returns true if two TimeSpans are equal. In C#, use the two equal signs (==). In VB.NET, use TimeSpan.op_Equality. Equivalent to Equals method.

Greater Than

Returns true if first TimeSpan is greater than the second. In C#, use the greater-than sign (>). In VB.NET, use TimeSpan.op_GreaterThan. Equivalent to Compare method.

Greater Than or Equal

Returns true if first TimeSpan is greater than the second. In C#, use the greater than or equal signs (>=). In VB.NET, use TimeSpan.op_GreaterThanOrEqual. Equivalent to Compare method.

Inequality

Returns true if the two TimeSpans do not represent the same value. In C#, use the inequality signs (!=). In VB.NET, use TimeSpan.op_Inequality. Equivalent to Equals method returning the opposite value.

Less Than

Returns true if first TimeSpan is less than the second. In C#, use the less-than sign (<). In VB.NET, use TimeSpan.op_LessThan. Equivalent to Compare method.

Less Than or Equal

Returns true if first TimeSpan is less than or equal to the second. In C#, use the less-than or equal signs (<=). In VB.NET, use TimeSpan.op_LessThanOrEqual. Equivalent to Compare method.

Subtraction

Subtracts one TimeSpan from another, returning a TimeSpan. In C#, use the minus sign (-). In VB.NET, use TimeSpan.op_Subtraction. Equivalent to Subtract method.

Unary Negation

Returns a TimeSpan with the same numeric value as the specified TimeSpan but of opposite sign. In C#, use the minus sign (-). In VB.NET, use TimeSpan.op_UnaryNegation.

Unary Plus

Returns the specified TimeSpan. In C#, use the plus sign (+). In VB.NET, use TimeSpan.op_UnaryPlus.

You will see many of these DateTime and TimeSpan members used throughout this chapter, especially in the CountDownTimer application in Example 16-6 and Example 16-7.

16.2.3 Date and Time Format Strings

There are an infinite number of ways to format text representations of date and time. Days and months can be expressed as single digits, two digits, abbreviations of names, or full names. Hours can be single digits or two digits in a 12-hour format, either followed by AM/PM, A/P, or nothing, or in 24-hour format. Years can be one, two, or four digits. Times can include seconds or milliseconds, or neither. This list doesn't even begin to include all the custom formats you or your clients can dream up: "Saturday, the 8th of January, `05 at 2:08 in the afternoon," for example.

Looking at the DateTime methods in Table 16-3, you see several methods that convert to long and short date and time strings. These and other methods and properties depend on the regional settings of the end-user machine.

The Regional settings for a machine are set via Regional Options in the Control Panel. In Windows 2000, the Locale is set in the General tab of the Regional Options dialog box. Time and Date tabs customize time formats and both short and long date formats. In Windows XP, the Locale is set in the Regional Options tab of the Regional and Language Options dialog box, and the time and date formats are customized by clicking the Customize button. Both operating systems use the formatting characters listed in Table 16-9.

In addition, the DateTime.ToString method listed in Table 16-3, which overrides Control.ToString, has overloaded forms that take format strings to allow you to customize the resulting string. Those format strings are comprised of the characters found in Tables Table 16-9 and Table 16-10. If a string contains characters contained in both Tables Table 16-9 and Table 16-10, the meaning listed in Table 16-10 will prevail.

As you will see in the next section, the DateTimePicker control has two properties that control how the date-time value is displayed in the control. The Format property determines if the display format is Short, Long, Time, or Custom. If it is set to DateTimePickerFormat.Custom, then the CustomFormat property must contain a text string comprised of the formatting characters contained in Table 16-9.

Literal string characters can be included in format strings. If there is any ambiguity about whether the characters will be interpreted as literal strings or formatting characters, they should be escaped using single quotes, as shown in examples later in the chapter.

Table 16-9. DateTime format strings

Format string

Description

d

One- or two-digit days.

dd

Two-digit days. Single-digit values are padded with a leading zero.

ddd

Three-character day of the week abbreviatione.g., Mon.

dddd

Full day of the week namee.g., Monday.

h

One- or two-digit hours in 12-hour format.

hh

Two-digit hours in 12-hour format. Single-digit values are padded with a leading zero.

H

One- or two-digit hours in 24-hour format.

HH

Two-digit hours in 24-hour format. Single-digit values are padded with a leading zero.

m

One- or two-digit minutes.

mm

Two-digit minutes. Single-digit values are padded with a leading zero.

M

One- or two-digit month.

MM

Two-digit month. Single-digit values are padded with a leading zero.

MMM

Three-character month abbreviatione.g., Jan.

MMMM

Full month namee.g., January.

s

One- or two-digit seconds.

ss

Two-digit seconds. Single-digit values are padded with a leading zero.

t

One-letter AM/PM abbreviatione.g., A.

tt

Two-letter AM/PM abbreviatione.g., AM.

y

One-digit yeare.g., 2001 is "1".

yy

Last two digits of the year.

yyyy

Full year.

Table 16-10. DateTimeFormatInfo format characters

Format string

Description

d

Short datee.g., M/d/yyyy

D

Long datee.g., dddd, dd MMMM yyyy

f

Full datee.g., dddd, MMMM dd, yyyy hh:mm tt

F

Full datee.g., dddd, MMMM dd, yyyy hh:mm:ss tt

g

Generale.g., M/d/yyyy hh:mm tt

G

Generale.g., M/d/yyyy hh:mm:ss tt

m, M

Month and daye.g., MMMM dd

r, R

RFC1123e.g., ddd,dd MMM yyyy HH':'mm':'ss `GMT'

s

Sortable DateTimee.g., yyyy'-'MM'-'dd'T'HH':'mm':'ss

t

Short timee.g., hh:mm tt

T

Long timee.g., hh:mm:ss tt

u

Universal sortable DateTimee.g., yyyy'-'MM'-'dd HH':'mm':'ss'Z'

U

Full date and time using universal timee.g., dddd, MMMM dd, yyyy hh:mm:ss tt

y,Y

YearMonthe.g., MMMM, yyyy





Programming. NET Windows Applications
Programming .Net Windows Applications
ISBN: 0596003218
EAN: 2147483647
Year: 2003
Pages: 148
Simiral book on Amazon

Flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net