Constructing strings

The simplest way to construct a string is to assign a literal, as we saw in Chapter 2:

string s1 = "Hello";
string s2 = "First Line
Second Line";
string s3 = @"\serverfilesharehelloworld.cs";

To create a repeating sequence of characters, you can use string’s constructor:

Console.Write (new string ('*', 10));      // **********

You can also construct a string from a char array. The ToCharArray method does the reverse:

char[] ca = "Hello".ToCharArray();
string s = new string (ca);              // s = "Hello"

string’s constructor is also overloaded to accept various (unsafe) pointer types, in order to create strings from types such as char*.

Null and empty strings

An empty string has a length of zero. To create an empty string, you can use either a literal or the static string.Empty field; to test for an empty string, you can either perform an equality comparison or test its Length property:

string empty = "";
Console.WriteLine (empty == "");              // True
Console.WriteLine (empty == string.Empty);    // True
Console.WriteLine (empty.Length == 0);        // True

Because strings are reference types, they can also be null:

string nullString = null;
Console.WriteLine (nullString == null);        // True
Console.WriteLine (nullString == "");          // False
Console.WriteLine (nullString.Length == 0);    // NullReferenceException

The static string.IsNullOrEmpty method is a useful shortcut for testing whether a given string is either null or empty.

Accessing characters within a string

A string’s indexer returns a single character at the given index. As with all functions that operate on strings, this is zero-indexed:

string str  = "abcde";
char letter = str[1];        // letter == 'b'

string also implements IEnumerable<char>, so you can foreach over its characters:

foreach (char c in "123") Console.Write (c + ",");    // 1,2,3,

Searching within strings

The simplest methods for searching within strings are StartsWith, EndsWith and Contains. These all return true or false:

Console.WriteLine ("quick brown fox".EndsWith ("fox"));      // True
Console.WriteLine ("quick brown fox".Contains ("brown"));    // True

StartsWith and EndsWith are overloaded to let you specify a StringComparison enum or a CultureInfo object to control case and culture sensitivity (see “Ordinal versus culture comparison”). The default is to perform a case-sensitive match using rules applicable to the current (localized) culture. The following instead performs a case-insensitive search using the invariant culture’s rules:

"abcdef".StartsWith ("abc", StringComparison.InvariantCultureIgnoreCase)

The Contains method doesn’t offer the convenience of this overload, although you can achieve the same result with the IndexOf method.

IndexOf is more powerful: it returns the first position of a given character or substring (or –1 if the substring isn’t found):

Console.WriteLine ("abcde".IndexOf ("cd"));   // 2

IndexOf is also overloaded to accept a startPosition (an index from which to begin searching), as well as a StringComparison enum:

Console.WriteLine ("abcde abcde".IndexOf ("CD", 6,
                   StringComparison.CurrentCultureIgnoreCase));    // 8

LastIndexOf is like IndexOf but works backward through the string.

IndexOfAny returns the first matching position of any one of a set of characters:

Console.Write ("ab,cd ef".IndexOfAny (new char[] {' ', ','} ));       // 2
Console.Write ("pas5w0rd".IndexOfAny ("0123456789".ToCharArray() ));  // 3

LastIndexOfAny does the same in the reverse direction.

Manipulating strings

Because String is immutable, all the methods that “manipulate” a string return a new one, leaving the original untouched (the same goes for when you reassign a string variable).

Substring extracts a portion of a string:

string left3 = "12345".Substring (0, 3);     // left3 = "123";
string mid3  = "12345".Substring (1, 3);     // mid3 = "234";

If you omit the length, you get the remainder of the string:

string end3  = "12345".Substring (2);        // end3 = "345";

Insert and Remove insert or remove characters at a specified position:

string s1 = "helloworld".Insert (5, ", ");    // s1 = "hello, world"
string s2 = s1.Remove (5, 2);                 // s2 = "helloworld";

PadLeft and PadRight pad a string to a given length with a specified character (or a space if unspecified):

Console.WriteLine ("12345".PadLeft (9, '*'));  // ****12345
Console.WriteLine ("12345".PadLeft (9));       //     12345

If the input string is longer than the padding length, the original string is returned unchanged.

TrimStart and TrimEnd remove specified characters from the beginning or end of a string; Trim does both. By default, these functions remove whitespace characters (including spaces, tabs, new lines, and Unicode variations of these):

Console.WriteLine ("  abc 	
 ".Trim().Length);   // 3

Replace replaces all (nonoverlapping) occurrences of a particular character or substring:

Console.WriteLine ("to be done".Replace (" ", " | ") );  // to | be | done
Console.WriteLine ("to be done".Replace (" ", "")    );  // tobedone

ToUpper and ToLower return upper- and lowercase versions of the input string. By default, they honor the user’s current language settings; ToUpperInvariant and ToLowerInvariant always apply English alphabet rules.

Splitting and joining strings

Split divides a string up into pieces:

string[] words = "The quick brown fox".Split();

foreach (string word in words)
  Console.Write (word + "|");    // The|quick|brown|fox|

By default, Split uses whitespace characters as delimiters; it’s also overloaded to accept a params array of char or string delimiters. Split also optionally accepts a StringSplitOptions enum, which has an option to remove empty entries: this is useful when words are separated by several delimiters in a row.

The static Join method does the reverse of Split. It requires a delimiter and string array:

string[] words = "The quick brown fox".Split();
string together = string.Join (" ", words);      // The quick brown fox

The static Concat method is similar to Join but accepts only a params string array and applies no separator. Concat is exactly equivalent to the + operator (the compiler, in fact, translates + to Concat):

string sentence     = string.Concat ("The", " quick", " brown", " fox");
string sameSentence = "The" + " quick" + " brown" + " fox";

String.Format and composite format strings

The static Format method provides a convenient way to build strings that embed variables. The embedded variables (or values) can be of any type; the Format simply calls ToString on them.

The master string that includes the embedded variables is called a composite format string. When calling String.Format, you provide a composite format string followed by each of the embedded variables. For example:

string composite = "It's {0} degrees in {1} on this {2} morning";
string s = string.Format (composite, 35, "Perth", DateTime.Now.DayOfWeek);

// s == "It's 35 degrees in Perth on this Friday morning"

(And that’s Celsius!)

From C# 6, we can use interpolated string literals to the same effect (see “String Type” in Chapter 2). Just precede the string with the $ symbol and put the expressions in braces:

string s = $"It's hot this {DateTime.Now.DayOfWeek} morning";

Each number in curly braces is called a format item. The number corresponds to the argument position and is optionally followed by:

• A comma and a minimum width to apply

• A colon and a format string

The minimum width is useful for aligning columns. If the value is negative, the data is left-aligned; otherwise, it’s right-aligned. For example:

string composite = "Name={0,-20} Credit Limit={1,15:C}";

Console.WriteLine (string.Format (composite, "Mary", 500));
Console.WriteLine (string.Format (composite, "Elizabeth", 20000));

Here’s the result:

Name=Mary                 Credit Limit=        $500.00
Name=Elizabeth            Credit Limit=     $20,000.00

The equivalent without using string.Format is this:

string s = "Name=" + "Mary".PadRight (20) +
           " Credit Limit=" + 500.ToString ("C").PadLeft (15);

The credit limit is formatted as currency by virtue of the "C" format string. We describe format strings in detail in “Formatting and parsing”.

Ordinal versus culture comparison

There are two basic algorithms for string comparison: ordinal and culture-sensitive. Ordinal comparisons interpret characters simply as numbers (according to their numeric Unicode value); culture-sensitive comparisons interpret characters with reference to a particular alphabet. There are two special cultures: the “current culture,” which is based on settings picked up from the computer’s control panel; and the “invariant culture,” which is the same on every computer (and closely matches American culture).

For equality comparison, both ordinal and culture-specific algorithms are useful. For ordering, however, culture-specific comparison is nearly always preferable: to order strings alphabetically, you need an alphabet. Ordinal relies on the numeric Unicode point values, which happen to put English characters in alphabetical order—but even then not exactly as you might expect. For example, assuming case sensitivity, consider the strings “Atom”, “atom”, and “Zamia”. The invariant culture puts them in the following order:

"Atom", "atom", "Zamia"

Ordinal arranges them instead as follows:

"Atom", "Zamia", "atom"

This is because the invariant culture encapsulates an alphabet, which considers uppercase characters adjacent to their lowercase counterparts (aAbBcCdD...). The ordinal algorithm, however, puts all the uppercase characters first, and then all lowercase characters (A...Z, a...z). This is essentially a throwback to the ASCII character set invented in the 1960s.

String equality comparison

Despite ordinal’s limitations, string’s == operator always performs ordinal case-sensitive comparison. The same goes for the instance version of string.Equals when called without arguments; this defines the “default” equality-comparison behavior for the string type.

The following methods allow culture-aware or case-insensitive comparisons:

public bool Equals(string value, StringComparison comparisonType);

public static bool Equals (string a, string b,
                           StringComparison comparisonType);

The static version is advantageous in that it still works if one or both of the strings are null. StringComparison is an enum defined as follows:

public enum StringComparison
{
  CurrentCulture,               // Case-sensitive
  CurrentCultureIgnoreCase,
  InvariantCulture,             // Case-sensitive
  InvariantCultureIgnoreCase,
  Ordinal,                      // Case-sensitive
  OrdinalIgnoreCase
}

For example:

Console.WriteLine (string.Equals ("foo", "FOO",
                   StringComparison.OrdinalIgnoreCase));   // True

Console.WriteLine ("ṻ" == "ǖ");                            // False

Console.WriteLine (string.Equals ("ṻ", "ǖ",
                   StringComparison.CurrentCulture));      // ?

(The result of the third example is determined by the computer’s current language settings.)

String-order comparison

String’s CompareTo instance method performs culture-sensitive, case-sensitive order comparison. Unlike the == operator, CompareTo does not use ordinal comparison: for ordering, a culture-sensitive algorithm is much more useful.

Here’s the method’s definition:

public int CompareTo (string strB);

For other kinds of comparison, you can call the static Compare and CompareOrdinal methods:

public static int Compare (string strA, string strB,
                           StringComparison comparisonType);

public static int Compare (string strA, string strB, bool ignoreCase,
                           CultureInfo culture);

public static int Compare (string strA, string strB, bool ignoreCase);

public static int CompareOrdinal (string strA, string strB);

The last two methods are simply shortcuts for calling the first two methods.

All of the order-comparison methods return a positive number, a negative number, or zero, depending on whether the first value comes after, before, or alongside the second value:

Console.WriteLine ("Boston".CompareTo ("Austin"));    // 1
Console.WriteLine ("Boston".CompareTo ("Boston"));    // 0
Console.WriteLine ("Boston".CompareTo ("Chicago"));   // -1
Console.WriteLine ("ṻ".CompareTo ("ǖ"));              // 0
Console.WriteLine ("foo".CompareTo ("FOO"));          // -1

The following performs a case-insensitive comparison using the current culture:

Console.WriteLine (string.Compare ("foo", "FOO", true));   // 0

By supplying a CultureInfo object, you can plug in any alphabet:

// CultureInfo is defined in the System.Globalization namespace

CultureInfo german = CultureInfo.GetCultureInfo ("de-DE");
int i = string.Compare ("Müller", "Muller", false, german);

Obtaining an Encoding object

The Encoding class in System.Text is the common base type for classes that encapsulate text encodings. There are several subclasses—their purpose is to encapsulate families of encodings with similar features. The easiest way to instantiate a correctly configured class is to call Encoding.GetEncoding with a standard IANA (Internet Assigned Numbers Authority) Character Set name:

Encoding utf8 = Encoding.GetEncoding ("utf-8");
Encoding chinese = Encoding.GetEncoding ("GB18030");

The most common encodings can also be obtained through dedicated static properties on Encoding:

The static GetEncodings method returns a list of all supported encodings, with their standard IANA names:

foreach (EncodingInfo info in Encoding.GetEncodings())
  Console.WriteLine (info.Name);

The other way to obtain an encoding is to directly instantiate an encoding class. Doing so allows you to set various options via constructor arguments, including:

• Whether to throw an exception if an invalid byte sequence is encountered when decoding. The default is false.

• Whether to encode/decode UTF-16/UTF-32 with the most significant bytes first (big endian) or the least significant bytes first (little endian). The default is little endian, the standard on the Windows operating system.

• Whether to emit a byte-order mark (a prefix that indicates endianness).

Encoding for file and stream I/O

The most common application for an Encoding object is to control how text is read and written to a file or stream. For example, the following writes “Testing...” to a file called data.txt in UTF-16 encoding:

System.IO.File.WriteAllText ("data.txt", "Testing...", Encoding.Unicode);

If you omit the final argument, WriteAllText applies the ubiquitous UTF-8 encoding.

We resume this subject in Chapter 15, in “Stream Adapters”.

Encoding to byte arrays

You can also use an Encoding object to go to and from a byte array. The GetBytes method converts from string to byte[] with the given encoding; GetString converts from byte[] to string:

byte[] utf8Bytes  = System.Text.Encoding.UTF8.GetBytes    ("0123456789");
byte[] utf16Bytes = System.Text.Encoding.Unicode.GetBytes ("0123456789");
byte[] utf32Bytes = System.Text.Encoding.UTF32.GetBytes   ("0123456789");

Console.WriteLine (utf8Bytes.Length);    // 10
Console.WriteLine (utf16Bytes.Length);   // 20
Console.WriteLine (utf32Bytes.Length);   // 40

string original1 = System.Text.Encoding.UTF8.GetString    (utf8Bytes);
string original2 = System.Text.Encoding.Unicode.GetString (utf16Bytes);
string original3 = System.Text.Encoding.UTF32.GetString   (utf32Bytes);

Console.WriteLine (original1);          // 0123456789
Console.WriteLine (original2);          // 0123456789
Console.WriteLine (original3);          // 0123456789

UTF-16 and surrogate pairs

Recall that .NET stores characters and strings in UTF-16. Because UTF-16 requires one or two 16-bit words per character, and a char is only 16 bits in length, some Unicode characters require two chars to represent. This has a couple of consequences:

• A string’s Length property may be greater than its real character count.

• A single char is not always enough to fully represent a Unicode character.

Most applications ignore this, because nearly all commonly used characters fit into a section of Unicode called the Basic Multilingual Plane (BMP) which requires only one 16-bit word in UTF-16. The BMP covers several dozen world languages and includes more than 30,000 Chinese characters. Excluded are characters of some ancient languages, symbols for musical notation, and some less common Chinese characters.

If you need to support two-word characters, the following static methods in char convert a 32-bit code point to a string of two chars, and back again:

string ConvertFromUtf32 (int utf32)
int    ConvertToUtf32   (char highSurrogate, char lowSurrogate)

Two-word characters are called surrogates. They are easy to spot because each word is in the range 0xD800 to 0xDFFF. You can use the following static methods in char to assist:

bool IsSurrogate     (char c)
bool IsHighSurrogate (char c)
bool IsLowSurrogate  (char c)
bool IsSurrogatePair (char highSurrogate, char lowSurrogate)

The StringInfo class in the System.Globalization namespace also provides a range of methods and properties for working with two-word characters.

Characters outside the BMP typically require special fonts and have limited operating system support.

Choosing between DateTime and DateTimeOffset

DateTime and DateTimeOffset differ in how they handle time zones. A DateTime incorporates a three-state flag indicating whether the DateTime is relative to:

• The local time on the current computer

• UTC (the modern equivalent of Greenwich Mean Time)

• Unspecified

A DateTimeOffset is more specific—it stores the offset from UTC as a TimeSpan:

July 01 2007 03:00:00 -06:00

This influences equality comparisons, which is the main factor in choosing between DateTime and DateTimeOffset. Specifically:

• DateTime ignores the three-state flag in comparisons and considers two values equal if they have the same year, month, day, hour, minute, and so on.

• DateTimeOffset considers two values equal if they refer to the same point in time.

So, DateTime considers the following two values different, whereas DateTimeOffset considers them equal:

July 01 2007 09:00:00 +00:00 (GMT)
July 01 2007 03:00:00 -06:00 (local time, Central America)

In most cases, DateTimeOffset’s equality logic is preferable. For example, in calculating which of two international events is more recent, a DateTimeOffset implicitly gives the right answer. Similarly, a hacker plotting a distributed denial of service attack would reach for a DateTimeOffset! To do the same with DateTime requires standardizing on a single time zone (typically UTC) throughout your application. This is problematic for two reasons:

• To be friendly to the end user, UTC DateTimes require explicit conversion to local time prior to formatting.

• It’s easy to forget and incorporate a local DateTime.

DateTime is better, though, at specifying a value relative to the local computer at runtime—for example, if you want to schedule an archive at each of your international offices for next Sunday, at 3 A.M. local time (when there’s least activity). Here, DateTime would be more suitable because it would respect each site’s local time.

We revisit time zones and equality comparison in more depth in “Dates and Time Zones”.

Constructing a DateTime

DateTime defines constructors that accept integers for the year, month, and day—and optionally, the hour, minute, second, and millisecond:

public DateTime (int year, int month, int day);

public DateTime (int year, int month, int day,
                 int hour, int minute, int second, int millisecond);

If you specify only a date, the time is implicitly set to midnight (0:00).

The DateTime constructors also allow you to specify a DateTimeKind—an enum with the following values:

Unspecified, Local, Utc

This corresponds to the three-state flag described in the preceding section. Unspecified is the default, and it means that the DateTime is time-zone-agnostic. Local means relative to the local time zone on the current computer. A local DateTime does not include information about which particular time zone it refers to, nor, unlike DateTimeOffset, the numeric offset from UTC.

A DateTime’s Kind property returns its DateTimeKind.

DateTime’s constructors are also overloaded to accept a Calendar object as well—this allows you to specify a date using any of the Calendar subclasses defined in System.Globalization. For example:

DateTime d = new DateTime (5767, 1, 1,
                          new System.Globalization.HebrewCalendar());

Console.WriteLine (d);    // 12/12/2006 12:00:00 AM

(The formatting of the date in this example depends on your computer’s control panel settings.) A DateTime always uses the default Gregorian calendar—this example, a one-time conversion, takes place during construction. To perform computations using another calendar, you must use the methods on the Calendar subclass itself.

You can also construct a DateTime with a single ticks value of type long, where ticks is the number of 100 ns intervals from midnight 01/01/0001.

For interoperability, DateTime provides the static FromFileTime and FromFileTimeUtc methods for converting from a Windows file time (specified as a long) and FromOADate for converting from an OLE automation date/time (specified as a double).

To construct a DateTime from a string, call the static Parse or ParseExact method. Both methods accept optional flags and format providers; ParseExact also accepts a format string. We discuss parsing in greater detail in “Formatting and parsing”.

Constructing a DateTimeOffset

DateTimeOffset has a similar set of constructors. The difference is that you also specify a UTC offset as a TimeSpan:

public DateTimeOffset (int year, int month, int day,
                       int hour, int minute, int second,
                       TimeSpan offset);

public DateTimeOffset (int year, int month, int day,
                       int hour, int minute, int second, int millisecond,
                       TimeSpan offset);

The TimeSpan must amount to a whole number of minutes, or an exception is thrown.

DateTimeOffset also has constructors that accept a Calendar object, a long ticks value, and static Parse and ParseExact methods that accept a string.

You can construct a DateTimeOffset from an existing DateTime either by using these constructors:

public DateTimeOffset (DateTime dateTime);
public DateTimeOffset (DateTime dateTime, TimeSpan offset);

or with an implicit cast:

DateTimeOffset dt = new DateTime (2000, 2, 3);

If you don’t specify an offset, it’s inferred from the DateTime value using these rules:

• If the DateTime has a DateTimeKind of Utc, the offset is zero.

• If the DateTime has a DateTimeKind of Local or Unspecified (the default), the offset is taken from the current local time zone.

To convert in the other direction, DateTimeOffset provides three properties that return values of type DateTime:

• The UtcDateTime property returns a DateTime in UTC time.

• The LocalDateTime property returns a DateTime in the current local time zone (converting it if necessary).

• The DateTime property returns a DateTime in whatever zone it was specified, with a Kind of Unspecified (i.e., it returns the UTC time plus the offset).

The current DateTime/DateTimeOffset

Both DateTime and DateTimeOffset have a static Now property that returns the current date and time:

Console.WriteLine (DateTime.Now);         // 11/11/2015 1:23:45 PM
Console.WriteLine (DateTimeOffset.Now);   // 11/11/2015 1:23:45 PM -06:00

DateTime also provides a Today property that returns just the date portion:

Console.WriteLine (DateTime.Today);       // 11/11/2015 12:00:00 AM

The static UtcNow property returns the current date and time in UTC:

Console.WriteLine (DateTime.UtcNow);        // 11/11/2015 7:23:45 AM
Console.WriteLine (DateTimeOffset.UtcNow);  // 11/11/2015 7:23:45 AM +00:00

The precision of all these methods depends on the operating system and is typically in the 10–20 ms region.

Working with dates and times

DateTime and DateTimeOffset provide a similar set of instance properties that return various date/time elements:

DateTime dt = new DateTime (2000, 2, 3,
                            10, 20, 30);

Console.WriteLine (dt.Year);         // 2000
Console.WriteLine (dt.Month);        // 2
Console.WriteLine (dt.Day);          // 3
Console.WriteLine (dt.DayOfWeek);    // Thursday
Console.WriteLine (dt.DayOfYear);    // 34

Console.WriteLine (dt.Hour);         // 10
Console.WriteLine (dt.Minute);       // 20
Console.WriteLine (dt.Second);       // 30
Console.WriteLine (dt.Millisecond);  // 0
Console.WriteLine (dt.Ticks);        // 630851700300000000
Console.WriteLine (dt.TimeOfDay);    // 10:20:30  (returns a TimeSpan)

DateTimeOffset also has an Offset property of type TimeSpan.

Both types provide the following instance methods to perform computations (most accept an argument of type double or int):

AddYears  AddMonths   AddDays
AddHours  AddMinutes  AddSeconds  AddMilliseconds  AddTicks

These all return a new DateTime or DateTimeOffset, and they take into account such things as leap years. You can pass in a negative value to subtract.

The Add method adds a TimeSpan to a DateTime or DateTimeOffset. The + operator is overloaded to do the same job:

TimeSpan ts = TimeSpan.FromMinutes (90);
Console.WriteLine (dt.Add (ts));
Console.WriteLine (dt + ts);             // same as above

You can also subtract a TimeSpan from a DateTime/DateTimeOffset and subtract one DateTime/DateTimeOffset from another. The latter gives you a TimeSpan:

DateTime thisYear = new DateTime (2015, 1, 1);
DateTime nextYear = thisYear.AddYears (1);
TimeSpan oneYear = nextYear - thisYear;

Formatting and parsing

Calling ToString on a DateTime formats the result as a short date (all numbers) followed by a long time (including seconds). For example:

11/11/2015 11:50:30 AM

The operating system’s control panel, by default, determines such things as whether the day, month, or year comes first, the use of leading zeros, and whether 12- or 24-hour time is used.

Calling ToString on a DateTimeOffset is the same, except that the offset is returned also:

11/11/2015 11:50:30 AM -06:00

The ToShortDateString and ToLongDateString methods return just the date portion. The long date format is also determined by the control panel; an example is “Wednesday, 11 November 2015”. ToShortTimeString and ToLongTimeString return just the time portion, such as 17:10:10 (the former excludes seconds).

These four methods just described are actually shortcuts to four different format strings. ToString is overloaded to accept a format string and provider, allowing you to specify a wide range of options and control how regional settings are applied. We describe this in “Formatting and Parsing”.

DateTime dt1 = DateTime.Now;
string cannotBeMisparsed = dt1.ToString ("o");
DateTime dt2 = DateTime.Parse (cannotBeMisparsed);

The static Parse/TryParse and ParseExact/TryParseExact methods do the reverse of ToString, converting a string to a DateTime or DateTimeOffset. These methods are also overloaded to accept a format provider. The Try* methods return false instead of throwing a FormatException.

Null DateTime and DateTimeOffset values

Because DateTime and DateTimeOffset are structs, they are not intrinsically nullable. When you need nullability, there are two ways around this:

• Use a Nullable type (i.e., DateTime? or DateTimeOffset?).

• Use the static field DateTime.MinValue or DateTimeOffset.MinValue (the default values for these types).

A nullable type is usually the best approach because the compiler helps to prevent mistakes. DateTime.MinValue is useful for backward compatibility with code written prior to C# 2.0 (when nullable types were introduced).

TimeZone

The static TimeZone.CurrentTimeZone method returns a TimeZone object based on the current local settings. The following demonstrates the result if run in California:

TimeZone zone = TimeZone.CurrentTimeZone;
Console.WriteLine (zone.StandardName);      // Pacific Standard Time
Console.WriteLine (zone.DaylightName);      // Pacific Daylight Time

The IsDaylightSavingTime and GetUtcOffset methods work as follows:

DateTime dt1 = new DateTime (2015, 1, 1);
DateTime dt2 = new DateTime (2015, 6, 1);
Console.WriteLine (zone.IsDaylightSavingTime (dt1));     // True
Console.WriteLine (zone.IsDaylightSavingTime (dt2));     // False
Console.WriteLine (zone.GetUtcOffset (dt1));             // 08:00:00
Console.WriteLine (zone.GetUtcOffset (dt2));             // 09:00:00

The GetDaylightChanges method returns specific daylight saving time information for a given year:

DaylightTime day = zone.GetDaylightChanges (2015);
Console.WriteLine (day.Start.ToString ("M"));       // 08 March
Console.WriteLine (day.End.ToString ("M"));         // 01 November
Console.WriteLine (day.Delta);                      // 01:00:00

TimeZoneInfo

The TimeZoneInfo class works in a similar manner. TimeZoneInfo.Local returns the current local time zone:

TimeZoneInfo zone = TimeZoneInfo.Local;
Console.WriteLine (zone.StandardName);      // Pacific Standard Time
Console.WriteLine (zone.DaylightName);      // Pacific Daylight Time

TimeZoneInfo also provides IsDaylightSavingTime and GetUtcOffset methods—the difference is that they accept either a DateTime or a DateTimeOffset.

You can obtain a TimeZoneInfo for any of the world’s time zones by calling FindSystemTimeZoneById with the zone ID. This feature is unique to TimeZoneInfo, as is everything else that we demonstrate from this point on. We’ll switch to Western Australia for reasons that will soon become clear:

TimeZoneInfo wa = TimeZoneInfo.FindSystemTimeZoneById
                  ("W. Australia Standard Time");

Console.WriteLine (wa.Id);                   // W. Australia Standard Time
Console.WriteLine (wa.DisplayName);          // (GMT+08:00) Perth
Console.WriteLine (wa.BaseUtcOffset);        // 08:00:00
Console.WriteLine (wa.SupportsDaylightSavingTime);     // True

The Id property corresponds to the value passed to FindSystemTimeZoneById. The static GetSystemTimeZones method returns all world time zones; hence, you can list all valid zone ID strings as follows:

foreach (TimeZoneInfo z in TimeZoneInfo.GetSystemTimeZones())
  Console.WriteLine (z.Id);

The static ConvertTime method converts a DateTime or DateTimeOffset from one time zone to another. You can include either just a destination TimeZoneInfo, or both source and destination TimeZoneInfo objects. You can also convert directly from or to UTC with the methods ConvertTimeFromUtc and ConvertTimeToUtc.

For working with daylight saving time, TimeZoneInfo provides the following additional methods:

• IsInvalidTime returns true if a DateTime is within the hour (or delta) that’s skipped when the clocks move forward.

• IsAmbiguousTime returns true if a DateTime or DateTimeOffset is within the hour (or delta) that’s repeated when the clocks move back.

• GetAmbiguousTimeOffsets returns an array of TimeSpans representing the valid offset choices for an ambiguous DateTime or DateTimeOffset.

Unlike with TimeZone, you can’t obtain simple dates from a TimeZoneInfo indicating the start and end of daylight saving time. Instead, you must call GetAdjustmentRules, which returns a declarative summary of all daylight saving rules that apply to all years. Each rule has a DateStart and DateEnd indicating the date range within which the rule is valid:

foreach (TimeZoneInfo.AdjustmentRule rule in wa.GetAdjustmentRules())
  Console.WriteLine ("Rule: applies from " + rule.DateStart +
                                    " to " + rule.DateEnd);

Western Australia first introduced daylight saving time in 2006, midseason (and then rescinded it in 2009). This required a special rule for the first year; hence, there are two rules:

Rule: applies from 1/01/2006 12:00:00 AM to 31/12/2006 12:00:00 AM
Rule: applies from 1/01/2007 12:00:00 AM to 31/12/2009 12:00:00 AM

Each AdjustmentRule has a DaylightDelta property of type TimeSpan (this is one hour in almost every case) and properties called DaylightTransitionStart and DaylightTransitionEnd. The latter two are of type TimeZoneInfo.TransitionTime, which has the following properties:

public bool IsFixedDateRule { get; }
public DayOfWeek DayOfWeek { get; }
public int Week { get; }
public int Day { get; }
public int Month { get; }
public DateTime TimeOfDay { get; }

A transition time is somewhat complicated in that it needs to represent both fixed and floating dates. An example of a floating date is “the last Sunday in March.” Here are the rules for interpreting a transition time:

1. If, for an end transition, IsFixedDateRule is true, Day is 1, Month is 1, and TimeOfDay is DateTime.MinValue, there is no end to daylight saving time in that year (this can happen only in the southern hemisphere, upon the initial introduction of daylight saving time to a region).

2. Otherwise, if IsFixedDateRule is true, the Month, Day, and TimeOfDay properties determine the start or end of the adjustment rule.

3. Otherwise, if IsFixedDateRule is false, the Month, DayOfWeek, Week, and TimeOfDay properties determine the start or end of the adjustment rule.

In the last case, Week refers to the week of the month, with “5” meaning the last week. We can demonstrate this by enumerating the adjustment rules for our wa time zone:

foreach (TimeZoneInfo.AdjustmentRule rule in wa.GetAdjustmentRules())
{
  Console.WriteLine ("Rule: applies from " + rule.DateStart +
                                    " to " + rule.DateEnd);

  Console.WriteLine ("   Delta: " + rule.DaylightDelta);

  Console.WriteLine ("   Start: " + FormatTransitionTime
                                   (rule.DaylightTransitionStart, false));

  Console.WriteLine ("   End:   " + FormatTransitionTime
                                   (rule.DaylightTransitionEnd, true));
  Console.WriteLine();
}

In FormatTransitionTime, we honor the rules just described:

static string FormatTransitionTime (TimeZoneInfo.TransitionTime tt,
                                    bool endTime)
{
  if (endTime && tt.IsFixedDateRule
              && tt.Day == 1 && tt.Month == 1
              && tt.TimeOfDay == DateTime.MinValue)
    return "-";

  string s;
  if (tt.IsFixedDateRule)
    s = tt.Day.ToString();
  else
    s = "The " +
        "first second third fourth last".Split() [tt.Week - 1] +
        " " + tt.DayOfWeek + " in";

  return s + " " + DateTimeFormatInfo.CurrentInfo.MonthNames [tt.Month-1]
           + " at " + tt.TimeOfDay.TimeOfDay;
}

The result with Western Australia is interesting in that it demonstrates both fixed and floating date rules—as well as an absent end date:

Rule: applies from 1/01/2006 12:00:00 AM to 31/12/2006 12:00:00 AM
   Delta: 01:00:00
   Start: 3 December at 02:00:00
   End:   -

Rule: applies from 1/01/2007 12:00:00 AM to 31/12/2009 12:00:00 AM
   Delta: 01:00:00
   Start: The last Sunday in October at 02:00:00
   End:   The last Sunday in March at 03:00:00

from zone in TimeZoneInfo.GetSystemTimeZones()
let rules = zone.GetAdjustmentRules()
where
  rules.Any
   (r => r.DaylightTransitionEnd.IsFixedDateRule) &&
  rules.Any
   (r => !r.DaylightTransitionEnd.IsFixedDateRule)
select zone

Format providers and CultureInfo

Within the context of format providers, CultureInfo acts as an indirection mechanism for the other two format providers, returning a NumberFormatInfo or DateTimeFormatInfo object applicable to the culture’s regional settings.

In the following example, we request a specific culture (english language in Great Britain):

CultureInfo uk = CultureInfo.GetCultureInfo ("en-GB");
Console.WriteLine (3.ToString ("C", uk));      // £3.00

This executes using the default NumberFormatInfo object applicable to the en-GB culture.

The next example formats a DateTime with invariant culture. Invariant culture is always the same, regardless of the computer’s settings:

DateTime dt = new DateTime (2000, 1, 2);
CultureInfo iv = CultureInfo.InvariantCulture;
Console.WriteLine (dt.ToString (iv));            // 01/02/2000 00:00:00
Console.WriteLine (dt.ToString ("d", iv));       // 01/02/2000

Using NumberFormatInfo or DateTimeFormatInfo

In the next example, we instantiate a NumberFormatInfo and change the group separator from a comma to a space. We then use it to format a number to three decimal places:

NumberFormatInfo f = new NumberFormatInfo ();
f.NumberGroupSeparator = " ";
Console.WriteLine (12345.6789.ToString ("N3", f));   // 12 345.679

The initial settings for a NumberFormatInfo or DateTimeFormatInfo are based on the invariant culture. Sometimes, however, it’s more useful to choose a different starting point. To do this, you can Clone an existing format provider:

NumberFormatInfo f = (NumberFormatInfo)
                      CultureInfo.CurrentCulture.NumberFormat.Clone();

A cloned format provider is always writable—even if the original was read-only.

Composite formatting

Composite format strings allow you to combine variable substitution with format strings. The static string.Format method accepts a composite format string—we illustrated this in “String.Format and composite format strings”:

string composite = "Credit={0:C}";
Console.WriteLine (string.Format (composite, 500));   // Credit=$500.00

The Console class itself overloads its Write and WriteLine methods to accept composite format strings, allowing us to shorten this example slightly:

Console.WriteLine ("Credit={0:C}", 500);   // Credit=$500.00

You can also append a composite format string to a StringBuilder (via AppendFormat), and to a TextWriter for I/O (see Chapter 15).

string.Format accepts an optional format provider. A simple application for this is to call ToString on an arbitrary object while passing in a format provider. For example:

string s = string.Format (CultureInfo.InvariantCulture, "{0}", someObject);

This is equivalent to:

string s;
if (someObject is IFormattable)
  s = ((IFormattable)someObject).ToString (null,
                                           CultureInfo.InvariantCulture);
else if (someObject == null)
  s = "";
else
  s = someObject.ToString();

Parsing with format providers

There’s no standard interface for parsing through a format provider. Instead, each participating type overloads its static Parse (and TryParse) method to accept a format provider, and optionally, a NumberStyles or DateTimeStyles enum.

NumberStyles and DateTimeStyles control how parsing work: they let you specify such things as whether parentheses or a currency symbol can appear in the input string. (By default, the answer to both of these questions is no.) For example:

int error = int.Parse ("(2)");   // Exception thrown

int minusTwo = int.Parse ("(2)", NumberStyles.Integer |
                                 NumberStyles.AllowParentheses);   // OK

decimal fivePointTwo = decimal.Parse ("£5.20", NumberStyles.Currency,
                       CultureInfo.GetCultureInfo ("en-GB"));

The next section lists all NumberStyles and DateTimeStyles members—as well as the default parsing rules for each type.

IFormatProvider and ICustomFormatter

All format providers implement IFormatProvider:

public interface IFormatProvider { object GetFormat (Type formatType); }

The purpose of this method is to provide indirection—this is what allows CultureInfo to defer to an appropriate NumberFormatInfo or DateTimeInfo object to do the work.

By implementing IFormatProvider—along with ICustomFormatter—you can also write your own format provider that works in conjunction with existing types. ICustomFormatter defines a single method as follows:

string Format (string format, object arg, IFormatProvider formatProvider);

The following custom format provider writes numbers as words:

// Program can be downloaded from http://www.albahari.com/nutshell/

public class WordyFormatProvider : IFormatProvider, ICustomFormatter
{
  static readonly string[] _numberWords =
   "zero one two three four five six seven eight nine minus point".Split();

  IFormatProvider _parent;   // Allows consumers to chain format providers

  public WordyFormatProvider () : this (CultureInfo.CurrentCulture) { }
  public WordyFormatProvider (IFormatProvider parent)
  {
    _parent = parent;
  }

  public object GetFormat (Type formatType)
  {
    if (formatType == typeof (ICustomFormatter)) return this;
    return null;
  }

  public string Format (string format, object arg, IFormatProvider prov)
  {
    // If it's not our format string, defer to the parent provider:
    if (arg == null || format != "W")
      return string.Format (_parent, "{0:" + format + "}", arg);

    StringBuilder result = new StringBuilder();
    string digitList = string.Format (CultureInfo.InvariantCulture,
                                      "{0}", arg);
    foreach (char digit in digitList)
    {
      int i = "0123456789-.".IndexOf (digit);
      if (i == -1) continue;
      if (result.Length > 0) result.Append (' '),
      result.Append (_numberWords[i]);
    }
    return result.ToString();
  }
}

Notice that in the Format method, we used string.Format to convert the input number to a string—with InvariantCulture. It would have been much simpler just to call ToString() on arg, but then CurrentCulture would have been used instead. The reason for needing the invariant culture is evident a few lines later:

int i = "0123456789-.".IndexOf (digit);

It’s critical here that the number string comprises only the characters 0123456789-. and not any internationalized versions of these.

Here’s an example of using WordyFormatProvider:

double n = -123.45;
IFormatProvider fp = new WordyFormatProvider();
Console.WriteLine (string.Format (fp, "{0:C} in words is {0:W}", n));

// -$123.45 in words is minus one two three point four five

Custom format providers can be used only in composite format strings.

Parsing and misparsing DateTimes

Strings that put the month or day first are ambiguous and can easily be misparsed—particularly if you or any of your customers live outside the United States. This is not a problem in user-interface controls because the same settings are in force when parsing as when formatting. But when writing to a file, for instance, day/month misparsing can be a real problem. There are two solutions:

• Always state the same explicit culture when formatting and parsing (e.g., invariant culture).

• Format DateTime and DateTimeOffsets in a manner independent of culture.

The second approach is more robust—particularly if you choose a format that puts the four-digit year first: such strings are much harder to misparse by another party. Further, strings formatted with a standards-compliant year-first format (such as "o") can parse correctly alongside locally formatted strings—rather like a “universal donor.” (Dates formatted with "s" or "u" have the further benefit of being sortable.)

To illustrate, suppose we generate a culture-insensitive DateTime string s as follows:

string s = DateTime.Now.ToString ("o");

yyyy-MM-ddTHH:mm:ss K

We can reparse this in two ways. ParseExact demands strict compliance with the specified format string:

DateTime dt1 = DateTime.ParseExact (s, "o", null);

(You can achieve a similar result with XmlConvert’s ToString and ToDateTime methods.)

Parse, however, implicitly accepts both the "o" format and the CurrentCulture format:

DateTime dt2 = DateTime.Parse (s);

This works with both DateTime and DateTimeOffset.

Rounding real-to-integral conversions

In Chapter 2, we saw how implicit and explicit casts allow you to convert between numeric types. In summary:

• Implicit casts work for nonlossy conversions (e.g., int to double).

• Explicit casts are required for lossy conversions (e.g., double to int).

Casts are optimized for efficiency; hence, they truncate data that won’t fit. This can be a problem when converting from a real number to an integer, because often you want to round rather than truncate. Convert’s numerical conversion methods address just this issue; they always round:

double d = 3.9;
int i = Convert.ToInt32 (d);    // i == 4

Convert uses banker’s rounding, which snaps midpoint values to even integers (this avoids positive or negative bias). If banker’s rounding is a problem, first call Math.Round on the real number: this accepts an additional argument that allows you to control midpoint rounding.

Parsing numbers in base 2, 8, and 16

Hidden among the To(integral-type) methods are overloads that parse numbers in another base:

int thirty = Convert.ToInt32  ("1E", 16);    // Parse in hexadecimal
uint five  = Convert.ToUInt32 ("101", 2);    // Parse in binary

The second argument specifies the base. It can be any base you like—as long as it’s 2, 8, 10, or 16!

Dynamic conversions

Occasionally, you need to convert from one type to another—but you don’t know what the types are until runtime. For this, the Convert class provides a ChangeType method:

public static object ChangeType (object value, Type conversionType);

The source and target types must be one of the “base” types. ChangeType also accepts an optional IFormatProvider argument. Here’s an example:

Type targetType = typeof (int);
object source = "42";

object result = Convert.ChangeType (source, targetType);

Console.WriteLine (result);             // 42
Console.WriteLine (result.GetType());   // System.Int32

An example of when this might be useful is in writing a deserializer that can work with multiple types. It can also convert any enum to its integral type (see “Enums” in Chapter 3).

A limitation of ChangeType is that you cannot specify a format string or parsing flag.

Base 64 conversions

Sometimes you need to include binary data such as a bitmap within a text document such as an XML file or email message. Base 64 is a ubiquitous means of encoding binary data as readable characters, using 64 characters from the ASCII set.

Convert’s ToBase64String method converts from a byte array to base 64; FromBase64String does the reverse.

Enum to integral conversions

Recall that an explicit cast converts between an enum member and its integral value. An explicit cast is the correct approach if you know the enum type at compile time:

[Flags] public enum BorderSides { Left=1, Right=2, Top=4, Bottom=8 }
...
int i = (int) BorderSides.Top;            // i == 4
BorderSides side = (BorderSides) i;       // side == BorderSides.Top

You can cast a System.Enum instance to its integral type in the same way. The trick is to first cast to an object, and then the integral type:

static int GetIntegralValue (Enum anyEnum)
{
  return (int) (object) anyEnum;
}

This relies on you knowing the integral type: the method we just wrote would crash if passed an enum whose integral type was long. To write a method that works with an enum of any integral type, you can take one of three approaches. The first is to call Convert.ToDecimal:

static decimal GetAnyIntegralValue (Enum anyEnum)
{
  return Convert.ToDecimal (anyEnum);
}

This works because every integral type (including ulong) can be converted to decimal without loss of information. The second approach is to call Enum.GetUnderlyingType in order to obtain the enum’s integral type, and then call Convert.ChangeType:

static object GetBoxedIntegralValue (Enum anyEnum)
{
  Type integralType = Enum.GetUnderlyingType (anyEnum.GetType());
  return Convert.ChangeType (anyEnum, integralType);
}

This preserves the original integral type, as the following example shows:

object result = GetBoxedIntegralValue (BorderSides.Top);
Console.WriteLine (result);                               // 4
Console.WriteLine (result.GetType());                     // System.Int32

The third approach is to call Format or ToString specifying the "d" or "D" format string. This gives you the enum’s integral value as a string, and it is useful when writing custom serialization formatters:

static string GetIntegralValueAsString (Enum anyEnum)
{
  return anyEnum.ToString ("D");      // returns something like "4"
}

Integral-to-enum conversions

Enum.ToObject converts an integral value to an enum instance of the given type:

object bs = Enum.ToObject (typeof (BorderSides), 3);
Console.WriteLine (bs);                              // Left, Right

This is the dynamic equivalent of this:

BorderSides bs = (BorderSides) 3;

ToObject is overloaded to accept all integral types, as well as object. (The latter works with any boxed integral type.)

String conversions

To convert an enum to a string, you can either call the static Enum.Format method or call ToString on the instance. Each method accepts a format string, which can be "G" for default formatting behavior, "D" to emit the underlying integral value as a string, "X" for the same in hexadecimal, or "F" to format combined members of an enum without the Flags attribute. We listed examples of these in “Standard Format Strings and Parsing Flags”.

Enum.Parse converts a string to an enum. It accepts the enum type and a string that can include multiple members:

BorderSides leftRight = (BorderSides) Enum.Parse (typeof (BorderSides),
                                                  "Left, Right");

An optional third argument lets you perform case-insensitive parsing. An ArgumentException is thrown if the member is not found.

== and !=

We’ve already seen in many examples how the standard == and != operators perform equality/inequality comparisons. The subtleties with == and != arise because they are operators and so are statically resolved (in fact, they are implemented as static functions). So, when you use == or !=, C# makes a compile-time decision as to which type will perform the comparison, and no virtual behavior comes into play. This is normally desirable. In the following example, the compiler hard-wires == to the int type because x and y are both int:

int x = 5;
int y = 5;
Console.WriteLine (x == y);      // True

But in the next example, the compiler wires the == operator to the object type:

object x = 5;
object y = 5;
Console.WriteLine (x == y);      // False

Because object is a class (and so a reference type), object’s == operator uses referential equality to compare x and y. The result is false, because x and y each refer to different boxed objects on the heap.

The virtual Object.Equals method

To correctly equate x and y in the preceding example, we can use the virtual Equals method. Equals is defined in System.Object and so is available to all types:

object x = 5;
object y = 5;
Console.WriteLine (x.Equals (y));      // True

Equals is resolved at runtime—according to the object’s actual type. In this case, it calls Int32’s Equals method, which applies value equality to the operands, returning true. With reference types, Equals performs referential equality comparison by default; with structs, Equals performs structural comparison by calling Equals on each of its fields.

Hence, Equals is suitable for equating two objects in a type-agnostic fashion. The following method equates two objects of any type:

public static bool AreEqual (object obj1, object obj2)
  => obj1.Equals (obj2);

There is one case, however, in which this fails. If the first argument is null, you get a NullReferenceException. Here’s the fix:

public static bool AreEqual (object obj1, object obj2)
{
  if (obj1 == null) return obj2 == null;
  return obj1.Equals (obj2);
}

Or more succinctly:

public static bool AreEqual (object obj1, object obj2)
  => obj1 == null ? obj2 == null : obj1.Equals (obj2);

The static object.Equals method

The object class provides a static helper method that does the work of AreEqual in the preceding example. Its name is Equals—just like the virtual method—but there’s no conflict because it accepts two arguments:

public static bool Equals (object objA, object objB)

This provides a null-safe equality comparison algorithm for when the types are unknown at compile time. For example:

object x = 3, y = 3;
Console.WriteLine (object.Equals (x, y));   // True
x = null;
Console.WriteLine (object.Equals (x, y));   // False
y = null;
Console.WriteLine (object.Equals (x, y));   // True

A useful application is when writing generic types. The following code will not compile if object.Equals is replaced with the == or != operator:

class Test <T>
{
  T _value;
  public void SetValue (T newValue)
  {
    if (!object.Equals (newValue, _value))
    {
      _value = newValue;
      OnValueChanged();
    }
  }
  protected virtual void OnValueChanged() { ... }
}

Operators are prohibited here because the compiler cannot bind to the static method of an unknown type.

if (!EqualityComparer<T>.Default.Equals (newValue, _value))

The static object.ReferenceEquals method

Occasionally, you need to force referential equality comparison. The static object.ReferenceEquals method does just this:

class Widget { ... }

class Test
{
  static void Main()
  {
    Widget w1 = new Widget();
    Widget w2 = new Widget();
    Console.WriteLine (object.ReferenceEquals (w1, w2));     // False
  }
}

You might want to do this because it’s possible for Widget to override the virtual Equals method, such that w1.Equals(w2) would return true. Further, it’s possible for Widget to overload the == operator so that w1==w2 would also return true. In such cases, calling object.ReferenceEquals guarantees normal referential equality semantics.

The IEquatable<T> interface

A consequence of calling object.Equals is that it forces boxing on value types. This is undesirable in highly performance-sensitive scenarios because boxing is relatively expensive compared to the actual comparison. A solution was introduced in C# 2.0, with the IEquatable<T> interface:

public interface IEquatable<T>
{
  bool Equals (T other);
}

The idea is that IEquatable<T>, when implemented, gives the same result as calling object’s virtual Equals method—but more quickly. Most basic .NET types implement IEquatable<T>. You can use IEquatable<T> as a constraint in a generic type:

class Test<T> where T : IEquatable<T>
{
  public bool IsEqual (T a, T b)
  {
    return a.Equals (b);     // No boxing with generic T
  }
}

If we remove the generic constraint, the class would still compile, but a.Equals(b) would instead bind to the slower object.Equals (slower assuming T was a value type).

When Equals and == are not equal

We said earlier that it’s sometimes useful for == and Equals to apply different definitions of equality. For example:

double x = double.NaN;
Console.WriteLine (x == x);            // False
Console.WriteLine (x.Equals (x));      // True

The double type’s == operator enforces that one NaN can never equal anything else—even another NaN. This is most natural from a mathematical perspective, and it reflects the underlying CPU behavior. The Equals method, however, is obliged to apply reflexive equality; in other words:

x.Equals (x) must always return true.

Collections and dictionaries rely on Equals behaving this way; otherwise, they could not find an item they previously stored.

Having Equals and == apply different definitions of equality is actually quite rare with value types. A more common scenario is with reference types and happens when the author customizes Equals so that it performs value equality while leaving == to perform (default) referential equality. The StringBuilder class does exactly this:

var sb1 = new StringBuilder ("foo");
var sb2 = new StringBuilder ("foo");
Console.WriteLine (sb1 == sb2);          // False (referential equality)
Console.WriteLine (sb1.Equals (sb2));    // True  (value equality)

Let’s now look at how to customize equality.

Changing the meaning of equality

Changing the meaning of equality makes sense when the default behavior of == and Equals is unnatural for your type and is not what a consumer would expect. An example is DateTimeOffset, a struct with two private fields: a UTC DateTime and a numeric integer offset. If you were writing this type, you’d probably want to ensure that equality comparisons considered only the UTC DateTime field and not the offset field. Another example is numeric types that support NaN values such as float and double. If you were implementing such types yourself, you’d want to ensure that NaN-comparison logic was supported in equality comparisons.

With classes, it’s sometimes more natural to offer value equality as the default instead of referential equality. This is often the case with small classes that hold a simple piece of data—such as System.Uri (or System.String).

Speeding up equality comparisons with structs

The default structural equality comparison algorithm for structs is relatively slow. Taking over this process by overriding Equals can improve performance by a factor of five. Overloading the == operator and implementing IEquatable<T> allows unboxed equality comparisons, and this can speed things up by a factor of five again.

There’s actually another, rather peculiar case for customizing equality, and that’s to improve a struct’s hashing algorithm for better performance in a hashtable. This comes of the fact that equality comparison and hashing are joined at the hip. We’ll examine hashing in a moment.

How to override equality semantics

Here is a summary of the steps:

1. Override GetHashCode() and Equals().

2. (Optionally) overload != and ==.

3. (Optionally) implement IEquatable<T>.

Overriding GetHashCode

It might seem odd that System.Object—with its small footprint of members—defines a method with a specialized and narrow purpose. GetHashCode is a virtual method in Object that fits this description—it exists primarily for the benefit of just the following two types:

System.Collections.Hashtable
System.Collections.Generic.Dictionary<TKey,TValue>

These are hashtables—collections where each element has a key used for storage and retrieval. A hashtable applies a very specific strategy for efficiently allocating elements based on their key. This requires that each key have an Int32 number, or hash code. The hash code need not be unique for each key but should be as varied as possible for good hashtable performance. Hashtables are considered important enough that GetHashCode is defined in System.Object—so that every type can emit a hash code.

Both reference and value types have default implementations of GetHashCode, meaning you don’t need to override this method—unless you override Equals. (And if you override GetHashCode, you will almost certainly want to also override Equals.)

Here are the other rules for overriding object.GetHashCode:

• It must return the same value on two objects for which Equals returns true (hence, GetHashCode and Equals are overridden together).

• It must not throw exceptions.

• It must return the same value if called repeatedly on the same object (unless the object has changed).

For maximum performance in hashtables, GetHashCode should be written so as to minimize the likelihood of two different values returning the same hashcode. This gives rise to the third reason for overriding Equals and GetHashCode on structs, which is to provide a more efficient hashing algorithm than the default. The default implementation for structs is at the discretion of the runtime and may be based on every field in the struct.

In contrast, the default GetHashCode implementation for classes is based on an internal object token, which is unique for each instance in the CLR’s current implementation.

A complete example illustrating how to override GetHashCode is listed shortly.

Overriding Equals

The axioms for object.Equals are as follows:

• An object cannot equal null (unless it’s a nullable type).

• Equality is reflexive (an object equals itself).

• Equality is commutative (if a.Equals(b), then b.Equals(a)).

• Equality is transitive (if a.Equals(b) and b.Equals(c), then a.Equals(c)).

• Equality operations are repeatable and reliable (they don’t throw exceptions).

Overloading == and !=

In addition to overriding Equals, you can optionally overload the equality and inequality operators. This is nearly always done with structs, because the consequence of not doing so is that the == and != operators will simply not work on your type.

With classes, there are two ways to proceed:

• Leave == and != alone—so that they apply referential equality.

• Overload == and != in line with Equals.

The first approach is most common with custom types—especially mutable types. It ensures that your type follows the expectation that == and != should exhibit referential equality with reference types and this avoids confusing consumers. We saw an example earlier:

var sb1 = new StringBuilder ("foo");
var sb2 = new StringBuilder ("foo");
Console.WriteLine (sb1 == sb2);          // False (referential equality)
Console.WriteLine (sb1.Equals (sb2));    // True  (value equality)

The second approach makes sense with types for which a consumer would never want referential equality. These are typically immutable—such as the string and System.Uri classes—and are sometimes good candidates for structs.

Implementing IEquatable<T>

For completeness, it’s also good to implement IEquatable<T> when overriding Equals. Its results should always match those of the overridden object’s Equals method. Implementing IEquatable<T> comes at no programming cost if you structure your Equals method implementation, as in the following example.

An example: The Area struct

Imagine we need a struct to represent an area whose width and height are interchangeable. In other words, 5 × 10 is equal to 10 × 5. (Such a type would be suitable in an algorithm that arranges rectangular shapes.)

Here’s the complete code:

public struct Area : IEquatable <Area>
{
  public readonly int Measure1;
  public readonly int Measure2;

  public Area (int m1, int m2)
  {
    Measure1 = Math.Min (m1, m2);
    Measure2 = Math.Max (m1, m2);
  }

  public override bool Equals (object other)
  {
    if (!(other is Area)) return false;
    return Equals ((Area) other);        // Calls method below
  }

  public bool Equals (Area other)        // Implements IEquatable<Area>
    => Measure1 == other.Measure1 && Measure2 == other.Measure2;

  public override int GetHashCode()
    => Measure2 * 31 + Measure1;    // 31 = some prime number

  public static bool operator == (Area a1, Area a2) => a1.Equals (a2);

  public static bool operator != (Area a1, Area a2) => !a1.Equals (a2);
}

Area? otherArea = other as Area?;
return otherArea.HasValue && Equals (otherArea.Value);

In implementing GetHashCode, we’ve helped to improve the likelihood of uniqueness by multiplying the larger measure by some prime number (ignoring any overflow) before adding the two together. When there are more than two fields, the following pattern, suggested by Josh Bloch, gives good results while being performant:

int hash = 17;                             // 17 = some prime number
hash = hash * 31 + field1.GetHashCode();   // 31 = another prime number
hash = hash * 31 + field2.GetHashCode();
hash = hash * 31 + field3.GetHashCode();
...
return hash;

(See http://albahari.com/hashprimes for a link to a discussion on primes and hashcodes.)

Here’s a demo of the Area struct:

Area a1 = new Area (5, 10);
Area a2 = new Area (10, 5);
Console.WriteLine (a1.Equals (a2));    // True
Console.WriteLine (a1 == a2);          // True

Pluggable equality comparers

If you want a type to take on different equality semantics just for a particular scenario, you can use a pluggable IEqualityComparer. This is particularly useful in conjunction with the standard collection classes, and we describe it in the following chapter, in “Plugging in Equality and Order”.

IComparable versus Equals

Consider a type that both overrides Equals and implements the IComparable interfaces. You’d expect that when Equals returns true, CompareTo should return 0. And you’d be right. But here’s the catch:

• When Equals returns false, CompareTo can return what it likes (as long as it’s internally consistent)!

In other words, equality can be “fussier” than comparison, but not vice versa (violate this and sorting algorithms will break). So, CompareTo can say “All objects are equal” while Equals says “But some are more equal than others!”

A great example of this is System.String. String’s Equals method and == operator use ordinal comparison, which compares the Unicode point values of each character. Its CompareTo method, however, uses a less fussy culture-dependent comparison. On most computers, for instance, the strings “ṻ” and “ǖ” are different according to Equals, but the same according to CompareTo.

In Chapter 7, we discuss the pluggable ordering protocol, IComparer, which allows you to specify an alternative ordering algorithm when sorting or instantiating a sorted collection. A custom IComparer can further extend the gap between CompareTo and Equals—a case-insensitive string comparer, for instance, will return 0 when comparing "A" and "a". The reverse rule still applies, however: CompareTo can never be fussier than Equals.

if (Equals (other)) return 0;