This useful little class can be used to parse structured text files – either delimited or fixed length. You can iterate over the lines in the file and extract the data through the ReadFields method.

Since it is provided by Microsoft, you can use it in environments that do not allow “third-party” libraries and as it is a .NET libarary you can use it in any .NET language (yes, C# and F# included) – just import the library.

The examples on MSDN are all in VB.NET, but are easily translated to other .NET dialects.

- How to: Read From Comma-Delimited Text Files
- How to: Read From Fixed-width Text Files
- How to: Read From Text Files with Multiple Formats

If one takes the time to think about it, class libraries only ever execute in the context of an application – a web application, a console application, a unit test runner or some other executable.

A class library gets loaded into the memory space of the application and gets called and executed there.

It makes sense then that the executing application should be the one deciding on how to configure a class library it is using, rather than the other way around.

The .NET framework configuration subsystem subscribes to this idea – when using the System.Configuration namespace, the application configuration file will be the one queried, even if there is a configuration file matching the dll name.

I would add that configuration should be treated as a dependency – the values should be injected into any class or method that required them – read the excellent blog by Paul Hiles – Configuration Settings Are A Dependency That Should Be Injected.

Whenever these are used, the CultureInfo that is used with them comes into play. If an IFormatProvider is not specified, the CultureInfo assigned to the current thread is used.

Standard format strings

These are all single character format specifiers – they each can be thought of as representing longer, culture sensitive custom format strings.

Any format string that contains more than one character (including white space) is considered to be a custom format specifier.

A FormatException will be thrown if the format specifier is not one of the known ones (listed in the table below):

Take a look at the documentation for more detail.

Standard format strings are simple to use – when formatting a DateTime as a string or parsing a string into a DateTime (using ParseExact or TryParseExact).

Formatting examples:

DateTime.Now.ToString("f");
// 13 December 2011 19:35

DateTime.Now.ToString("f", CultureInfo.GetCultureInfo("he-IL"));
// יום שלישי 13 דצמבר 2011 19:35

DateTime.Now.ToString("D");
// 13 December 2011

DateTime.Now.ToString("D", CultureInfo.GetCultureInfo("ru-RU"));
// 13 декабря 2011 г.

Parsing examples (really just the opposite of the above):

DateTime.ParseExact("13 December 2011 19:35", "f", 
                    CultureInfo.GetCultureInfo("en-GB"))

DateTime.ParseExact("יום שלישי 13 דצמבר 2011 19:35", "f", 
                    CultureInfo.GetCultureInfo("he-IL"))

DateTime.ParseExact("13 December 2011", "D", 
                    CultureInfo.GetCultureInfo("en-GB"))

DateTime.ParseExact("13 декабря 2011 г.", "D", 
                    CultureInfo.GetCultureInfo("ru-RU"));

Custom format strings

Any string that contains more than one character will be considered to be a custom format string.

Custom format strings allow you to exactly match and parse any string representing a date and to convert a DateTime to any custom date string for display. They provide the most flexibility in parsing and outputting but are more complex to understand, construct and use than standard format strings.

All characters are allowed in the format string and each would be interpreted unchanged, unless it is one of the following format specifiers:

Several of these merit special discussion:

“:” – the time separator

When “:” appears in a custom format string, is gets replaced with the time separator defined in the CultureInfo being used. For example, in the “it-IT” culture, the time separator is a “.”.

“/” – the date separator

When “/” appears in a custom format string, is gets replaced with the date separator defined in the CultureInfo being used. For example, in the “ar-DZ” culture, the date separator is a “-”.

“string”, ‘string’ – the literal string delimiter

You can use single and double quotes as literal string delimiters within a format string – any such delimited string within a format string would appear verbatim in the string being parsed or output.

“\” – the escape character

When “\” appears in a custom format string, it simply escapes the next character so it does not get interpreted as a format specifier. For example, if the letter s appears in the string to be parsed, “\s” would represent it for parsing to ensure it does not get interpreted as the single character seconds custom format specifier.

“%” – precedes a single character custom format specifier

If you wish to use a single character custom format specifier you have several choices – prepend or append a space to it to ensure that it is not interpreted as a standard format string (otherwise it will be and if it is not a valid one a FormatException will be thrown). A downside to using a space in this manner is that one will be expected in the string to parse or will be output when converting to a string.

The alternative is to prepend “%” – this avoids the issue with spaces and serves as a special escape to allow for single character custom format specifiers.

Take a look at the documentation for more detail.

I will not give examples for these, as the documentation contains plenty.

If you have specific questions about the contents of this post, please post them in the comments and I will answer to the best of my ability.

InvariantCulture represents no culture at all – it is associated with the English language, though no specific country/region.

See Using the InvariantCulture Property on MSDN.

Here is an example of its use:

DateTime dt = new DateTime(2011, 11, 21, 12, 34, 56);
Console.WriteLine(dt.ToString(CultureInfo.InvariantCulture));

Overloads that do not specify IFormatProvider

So, what happens when overloads of ToString and the different Parse methods (Parse, TryParse, ParseExact and TryParseExact) that don’t take an IFormatProvider instance are used?

To answer this, I will ask this question: what would the console output of the following lines of code?

DateTime dt = new DateTime(2011, 11, 21, 12, 34, 56);
Console.WriteLine(dt);

The answer is – it depends. It depends on the configured locale of the account that the application is executing under (see the Regional Settings and what the different Date and Time formats are configured as). The locale will determine what culture is used in.

So, if the user is in England, the result could be:

21/11/2011 12:34:56

If, however, the user is in the United States, the result could be:

11/21/2011 12:34:56 PM

As I have demonstrated, the CultureInfo instance associated with the current thread is the one used. Depending on the application context, either the Thread.CurrentCulture or Thread.CurrentUICulture culture would be used.

For this reason, both Thread.CurrentCulture and Thread.CurrentUICulture should usually be changed at the same time to the same CultureInfo.

Specifying an IFormatProvider

By specifying an IFormatProvider you can be explicit about over how DateTime instances get formatted and how strings get parsed into DateTime instances.

For example, here is how you would explicitly format a DateTime with a US culture:

DateTime dt = new DateTime(2011, 11, 21, 12, 34, 56);
Console.WriteLine(dt.ToString(CultureInfo.GetCultureInfo("en-US")));

And for the British version:

DateTime dt = new DateTime(2011, 11, 21, 12, 34, 56);
Console.WriteLine(dt.ToString(CultureInfo.GetCultureInfo("en-GB")));

The most amount of control would come with format strings, these do however interact with the culture – this will be covered in a future post.

Some asides

You can create your own cultures using … See How to: Create Custom Cultures on MSDN and the CultureAndRegionInfoBuilder class.

Some locale settings can be changed – I will discuss some of that in a future post.

Here is good Microsoft FAQ about locales and languages – http://msdn.microsoft.com/en-us/goglobal/bb688174.

This interface defines a single method – GetFormat which takes a type and returns an object that provides formatting services for the specified type. When DateTime in concerned this object would be an instance of the DateTimeFormatInfo class.

The CultureInfo class also implements the IFormatProvider interface and will also return a DateTimeFormatInfo instance when called in the context of DateTime formatting. This is important, as CultureInfo is the most common implementer of IFormatProvider that is used for formatting DateTime instances for display.

It is unlikely that you will ever need to implement IFormatProvider yourself, at least when DateTime formatting is concerned.

The most common usages of IFormatProvider with DateTime are to provide a culture sensitive display of the DateTime instance and to parse a string representing a DateTime into a DateTime instance. This will be the subject of the next post.

A DateTime instance (say one representing midnight of March 26th 2011) has an internal representation that has no specific formatting – it is not something that will make sense to any human being in that form (this post is not about what exactly that representation is).

What this means is that every time you see a value for a DateTime instance, you are seeing this internal value after it has been formatted for human eyes.

How this formatted value comes to be is the subject of this blog series, starting with this introduction.

In future posts I will discuss the roles of IFormatProvider and format strings, Cultures and the Regional settings.

Good stuff, most of which is generally applicable to any question/answer site and day to day questions and answer, a small portion is only relevant to StackOverflow.com.

when describing your problem, make sure to include details of what you already tried. This will help ensure that you do not get answers that go into more depth and that will suggest things you have not tried.

Tip #1 – Ask a question

Tip #2 – Be polite

Tip #3 – Ask one question

Tip #4 – Descriptive title

Tip #5 – Write in English

Tip #6 – Pertinent code samples

Tip #7 – Stay on topic

Tip #8 – Do some research

Tip #9 – Stay engaged

Tip #10 – What, not how

Tip #11 – Accept rate

Tip #12 – Code that shows the problem

When posting a code sample, make sure that it is representative of the problem you are having. This means that it needs to be syntacticly correct (otherwise, people will point out the syntax errors and not the problem you are trying to solve), if possible it should compile and it must clearly show the problem.

This will ensure that people will be able to easily reproduce the issue and answers will be relevant to the problem.

Tip #1 – Ask a question

Tip #2 – Be polite

Tip #3 – Ask one question

Tip #4 – Descriptive title

Tip #5 – Write in English

Tip #6 – Pertinent code samples

Tip #7 – Stay on topic

Tip #8 – Do some research

Tip #9 – Stay engaged

Tip #10 – What, not how

Tip #11 – Accept rate