Humanize Strings

String extensions are at the heart of this micro-framework. The foundation of this was set in the BDDfy framework where class names, method names and properties are turned into human readable sentences.

LowerCase is a public static property on To class that returns an instance of private ToLowerCase class that implements IStringTransformer and knows how to turn a string into lower case.

The benefit of using Transform and IStringTransformer over ApplyCase and LetterCasing is that LetterCasing is an enum and you’re limited to use what’s in the framework
while IStringTransformer is an interface you can implement in your codebase once and use it with Transform method allowing for easy extension.

Humanize Enums

Calling ToString directly on enum members usually results in less than ideal output for users. The solution to this is usually to use DescriptionAttribute data annotation and then read that at runtime to get a more friendly output. That is a great solution; but more often than not we only need to put some space between words of an enum member - which is what String.Humanize() does well. For an enum like:

And just like the Humanize API it honors the Description attribute. You don’t have to provide the casing you provided during humanization: it figures it out.

Humanize Dates

This is borrowed from StackOverFlow algorithm - although I had to apply some minor fixes on top of it. I am not going to bore you with all the examples as I am sure you know what this does: you basically give it an instance of DateTime and get back a string telling how far back in time that is:

DateTime.UtcNow.AddHours(-30).Humanize() => "yesterday"

Humanizer supports local as well as UTC dates. You could also provide the date you want the input date to be compared against. If null, it will use the current date as comparison base. Here is the API signature:

There are no fluent APIs for month or year as a month could have between 28 to 31 days and a year could be 365 or 366 days.

You could use these methods to, for example, replace

DateTime.Now.AddDays(2).AddHours(3).AddMinutes(-5)

with

DateTime.Now + 2.Days() + 3.Hours() - 5.Minutes()

DateTime methods

In.TheYear(2010) // Returns the first of January of 2010
In.January // Returns 1st of January of the current year
In.FebruaryOf(2009) // Returns 1st of February of 2009
In.One.Second // DateTime.UtcNow.AddSeconds(1);
In.Two.SecondsFrom(DateTime dateTime)
In.Three.Minutes // With corresponding From method
In.Three.Hours // With corresponding From method
In.Three.Days // With corresponding From method
In.Three.Weeks // With corresponding From method
In.Three.Months // With corresponding From method
In.Three.Years // With corresponding From method
On.January.The4th // Returns 4th of January of the current year
On.February.The(12) // Returns 12th of Feb of the current year

Integrate Humanizer with ASP.Net MVC

This is just a baseline and you can use this to simplify your day to day job. For example, in Asp.Net MVC we keep chucking Display attribute on ViewModel properties so HtmlHelper can generate correct labels for us; but, just like enums, in vast majority of cases we just need a space between the words in property name - so why not use string.Humanizer for that?!

You may find an Asp.Net MVC sample [in the code][5] that does that (although the project is excluded from the solution file to make the nuget package available for .Net 3.5 too).

This is achieved using a custom DataAnnotationsModelMetadataProvider I called HumanizerMetadataProvider. It is small enough to repeat here; so here we go:

This class calls the base class to extract the metadata and then, if required, humanizes the property name. It is checking if the property already has a DisplayName or Display attribute on it in which case the metadata provider will just honor the attribute and leave the property alone. For other properties it will Humanize the property name. That is all.

How to contribute?

Your contribution to Humanizer would be very welcome. Just check out the list of issues. They should be relatively straightforward.
We us GitHub flow for pull requests.
So if you want to contribute, fork the repo, fix an issue and send a PR.

One area Humanizer could definitely use your help is localisation.
Currently Humanizer supports French, Belgium, Spanish, Greek, German, Arabic, Russian and Romanian languages for Date.Humanize method.
Humanizer could definitely do with more translations. We also need localization for TimeSpan.Humanize.

To add a translation, fork the repository if you haven’t done yet, duplicate the resources.resx file, add your target locale code to the end (e.g. resources.ru.resx for Russian), translate the values to your language, commit, and send a pull request for it. Thanks.

Some languages have complex rules when it comes to dealing with numbers; for example, in Romanian “5 days” is “5 zile”, while “24 days” is “24 de zile” and in Arabic “2 days” is “يومين” not “2 يوم”.
Obviously a normal resource file doesn’t cut it in these cases as a more complex mapping is required.
In cases like this in addition to creating a resource file you should also subclass DefaultFormatter in a class that represents your language;
e.g. RomanianFormatter and then override the methods that need involve the complex rules. We think overriding the GetResourceKey method should be enough. To see how to do that check out RomanianFormatter and RussianFormatter to see an example.
Then you return an instance of your class in the Configurator class in the FormatterFactories based on the current culture.