Humanizer is a nice library to get human readable representations for strings, numbers and dates in .Net. Cutting strings down to a certain size or turning a TimeSpan into “an hour” isn’t magic. Nevertheless, trying to do all that work on your own will take time that Humanizer has already spent. Let’s look on a few use cases where this library has proven to be a great help.
Installation
Open your project in the Solution Explorer in Visual Studio, right-click on References and select “Manage NuGet Packages…” to open the NuGet packages dialog. Search for Humanizer and install this package:
A few minutes ago from a DateTime
Many sites offer you that nice feature where they show you how long ago a comment was written. Depending on the duration, you get an understandable unit (“a few minutes ago” or “5 years ago”) so that you don’t need to calculate that in your brain. You can write code to solve this problem on your own, but Humanizer has it already put into a simple extension method Humanize() on the DateTime class:
|
1 2 3 4 5 6 7 |
var now = DateTime.UtcNow; Assert.Equal("2 minutes ago", now.AddMinutes(-2).Humanize()); Assert.Equal("2 minutes from now", now.AddMinutes(2).Humanize()); Assert.Equal("11 months ago", now.AddMonths(-11).Humanize()); Assert.Equal("one year ago", now.AddMonths(-13).Humanize()); Assert.Equal("10 years ago", now.AddYears(-10).Humanize()); |
A week from a TimeSpan
The same magic works with TimeSpan objects, where Humanizer will show a unit of time that fits best:
|
1 2 3 4 5 |
Assert.Equal("2 minutes", TimeSpan.FromMinutes(2).Humanize()); Assert.Equal("2 minutes", TimeSpan.FromMinutes(-2).Humanize()); Assert.Equal("4 weeks", TimeSpan.FromDays(28).Humanize()); Assert.Equal("208 weeks", TimeSpan.FromDays(365 * 4).Humanize()); |
10.5 MB for files
It can be helpful to know how big a file is before you try to download it on a mobile connection. However, just showing the size in bytes may not help your users. Humanizer offers its own class to represent file sizes that can be converted as you need it or shown again in a human readable form:
|
1 2 3 4 5 6 7 8 |
var filesize = (10).Megabytes(); Assert.Equal(10240, filesize.Kilobytes); Assert.Equal(0.009765625, filesize.Gigabytes); Assert.Equal("10 MB", (10).Megabytes().Humanize()); Assert.Equal("1 GB", (1024).Megabytes().Humanize()); Assert.Equal("500 GB", (1024*1024*500).Kilobytes().Humanize()); |
Truncate Strings
You can truncate Strings with just a method call. Than can work, but often you need to indicate that this string was shortened and that requires some sort of logic. Humanizer can help you with this problem as well:
|
1 2 3 4 5 |
Assert.Equal("abc", "abc".Truncate(4)); Assert.Equal("abcd", "abcd".Truncate(4)); Assert.Equal("abc…", "abcdef".Truncate(4)); Assert.Equal("abc*", "abcdef".Truncate(4, "*")); |
Roman Numerals
Should you deal with roman numerals you can use Humanizer to convert Arabic numerals to Roman and back:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
Assert.Equal("I", 1.ToRoman()); Assert.Equal("II", 2.ToRoman()); Assert.Equal("III", 3.ToRoman()); Assert.Equal("IV", 4.ToRoman()); Assert.Equal("V", 5.ToRoman()); Assert.Equal("VI", 6.ToRoman()); Assert.Equal("VII", 7.ToRoman()); Assert.Equal("VIII", 8.ToRoman()); Assert.Equal("IX", 9.ToRoman()); Assert.Equal("X", 10.ToRoman()); Assert.Equal("L", 50.ToRoman()); Assert.Equal("C", 100.ToRoman()); Assert.Equal("D", 500.ToRoman()); Assert.Equal("CMXCIX", 999.ToRoman()); Assert.Equal("M", 1000.ToRoman()); Assert.Equal(1, "I".FromRoman()); Assert.Equal(2, "II".FromRoman()); Assert.Equal(3, "III".FromRoman()); Assert.Equal(4, "IV".FromRoman()); Assert.Equal(5, "V".FromRoman()); Assert.Equal(6, "VI".FromRoman()); Assert.Equal(7, "VII".FromRoman()); Assert.Equal(8, "VIII".FromRoman()); Assert.Equal(9, "IX".FromRoman()); Assert.Equal(10, "X".FromRoman()); Assert.Equal(3999, "MMMCMXCIX".FromRoman()); |
Internationalisation
The best part about Humanizer is the support for multiple languages. It uses the environment settings and each call to Humanize() can be overwritten with a specific CultureInfo:
|
1 2 3 4 5 6 7 8 |
var duration = DateTime.UtcNow.AddMonths(-5); var english = new CultureInfo("en-GB"); var german = new CultureInfo("de-CH"); var french = new CultureInfo("fr-FR"); Assert.Equal("5 months ago", duration.Humanize(culture: english)); Assert.Equal("vor 5 Monaten", duration.Humanize(culture: german)); Assert.Equal("il y a 5 mois", duration.Humanize(culture: french)); |
Great, but I need different units
The Humanize() method offers various options to change the units it displays. The precision is a good starting point to get more details from Humanizer:
|
1 2 3 4 5 6 |
var duration = TimeSpan.FromMilliseconds(1299690020); Assert.Equal("2 weeks", duration.Humanize()); Assert.Equal("2 weeks, 1 day", duration.Humanize(precision:2)); Assert.Equal("2 weeks, 1 day", duration.Humanize(2)); Assert.Equal("2 weeks, 1 day, 1 hour", duration.Humanize(3)); |
The parameter maxUnit can help you to get smaller units back from a call to Humanize():
|
1 2 3 4 |
var duration = TimeSpan.FromDays(367); Assert.Equal("52 weeks", duration.Humanize()); Assert.Equal("1 year", duration.Humanize(maxUnit: TimeUnit.Year)); Assert.Equal("12 months", duration.Humanize(maxUnit: TimeUnit.Month)); |
You find in the Readme.md of Humanizer many more examples on how you can influence the output for various data types. If you search for precision, maxUnit or minUnit you should find them without much effort.
Conclusion
Humanizer is a great help when you need to format output in a human readable form. It doesn’t look like much, but you safe a lot of time when you use this library instead of writing the code on your own.