diff --git a/readme.md b/readme.md index 5c35b11dd..2efef9428 100644 --- a/readme.md +++ b/readme.md @@ -5,9 +5,12 @@ Humanizer meets all your .NET needs for manipulating and displaying strings, enu - [Features](#features) - [Humanize String](#humanize-string) - [Dehumanize String](#dehumanize-string) - - [Transform](#transform) + - [Transform String](#transform-string) + - [Truncate String](#truncate-string) + - [Format String](#format-string) - [Humanize Enums](#humanize-enums) - [Dehumanize Enums](#dehumanize-enums) + - [Humanize DateTime](#humanize-datetime) - [Humanize TimeSpan](#humanize-timespan) - [Inflector methods](#inflector-methods) - [Pluralize](#pluralize) @@ -21,8 +24,6 @@ Humanizer meets all your .NET needs for manipulating and displaying strings, enu - [Number to ordinal words](#number-to-ordinal-words) - [Roman numerals](#roman-numerals) - [ByteSize](#bytesize) - - [Truncate String](#truncate) - - [Format String](#format) - [Mix this into your framework to simplify your life](#mix-this-into-your-framework-to-simplify-your-life) - [How to contribute?](#how-to-contribute) - [Contribution guideline](#contribution-guideline) @@ -74,7 +75,7 @@ Much like you can humanize a computer friendly into human friendly string you ca "Pascal case input string is turned into sentence".Dehumanize() => "PascalCaseInputStringIsTurnedIntoSentence" ``` -###Transform +###Transform String There is a `Transform` method that supercedes `LetterCasing`, `ApplyCase` and `Humanize` overloads that accept `LetterCasing`. Transform method signatue is as follows: @@ -96,6 +97,45 @@ And there are some out of the box implemenations of `IStringTransformer` for let 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. +###Truncate String +You can truncate a `string` using the `Truncate` method: + +```c# +"Long text to truncate".Truncate(10) => "Long text…" +``` + +By default the `'…'` character is used to truncate strings. The advantage of using the `'…'` character instead of `"..."` is that the former only takes a single character and thus allows more text to be shown before truncation. If you want, you can also provide your own truncation string: + +```c# +"Long text to truncate".Truncate(10, "---") => "Long te---" +``` + +The default truncation strategy, `Truncator.FixedLength`, is to truncate the input string to a specific length, including the truncation string length. There are two more truncator strategies available: one for a fixed number of (alpha-numerical) characters and one for a fixed number of words. To use a specific truncator when truncating, the two `Truncate` methods shown in the previous examples both have an overload that allow you to specify the `ITruncator` instance to use for the truncation. Here are examples on how to use the three provided truncators: + +```c# +"Long text to truncate".Truncate(10, Truncator.FixedLength) => "Long text…" +"Long text to truncate".Truncate(10, "---", Truncator.FixedLength) => "Long te---" + +"Long text to truncate".Truncate(6, Truncator.FixedNumberOfCharacters) => "Long t…" +"Long text to truncate".Truncate(6, "---", Truncator.FixedNumberOfCharacters) => "Lon---" + +"Long text to truncate".Truncate(2, Truncator.FixedNumberOfWords) => "Long text…" +"Long text to truncate".Truncate(2, "---", Truncator.FixedNumberOfWords) => "Long text---" +``` + +Note that you can also use create your own truncator by having a class implement the `ITruncator` interface. + +###Format String +You can format a `string` using the `FormatWith()` method: + +```c# +"To be formatted -> {0}/{1}.".FormatWith(1, "A") => "To be formated -> 1/A." +``` + +This is an extension method based on `String.Format`, so exact rules applies to it. +If `format` is null, it'll throw `ArgumentNullException`. +If passed a fewer number for arguments, it'll throw `String.FormatException` exception. + ###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: @@ -520,45 +560,6 @@ ByteSize.Parse("1.55 tB"); ByteSize.Parse("1.55 tb"); ``` -###Truncate -You can truncate a `string` using the `Truncate` method: - -```c# -"Long text to truncate".Truncate(10) => "Long text…" -``` - -By default the `'…'` character is used to truncate strings. The advantage of using the `'…'` character instead of `"..."` is that the former only takes a single character and thus allows more text to be shown before truncation. If you want, you can also provide your own truncation string: - -```c# -"Long text to truncate".Truncate(10, "---") => "Long te---" -``` - -The default truncation strategy, `Truncator.FixedLength`, is to truncate the input string to a specific length, including the truncation string length. There are two more truncator strategies available: one for a fixed number of (alpha-numerical) characters and one for a fixed number of words. To use a specific truncator when truncating, the two `Truncate` methods shown in the previous examples both have an overload that allow you to specify the `ITruncator` instance to use for the truncation. Here are examples on how to use the three provided truncators: - -```c# -"Long text to truncate".Truncate(10, Truncator.FixedLength) => "Long text…" -"Long text to truncate".Truncate(10, "---", Truncator.FixedLength) => "Long te---" - -"Long text to truncate".Truncate(6, Truncator.FixedNumberOfCharacters) => "Long t…" -"Long text to truncate".Truncate(6, "---", Truncator.FixedNumberOfCharacters) => "Lon---" - -"Long text to truncate".Truncate(2, Truncator.FixedNumberOfWords) => "Long text…" -"Long text to truncate".Truncate(2, "---", Truncator.FixedNumberOfWords) => "Long text---" -``` - -Note that you can also use create your own truncator by having a class implement the `ITruncator` interface. - -###Format String -You can format a `string` using the `FormatWith()` method: - -```c# -"To be formatted -> {0}/{1}.".FormatWith(1, "A") => "To be formated -> 1/A." -``` - -This is an extension method based on `String.Format`, so exact rules applies to it. -If `format` is null, it'll throw `ArgumentNullException`. -If passed a fewer number for arguments, it'll throw `String.FormatException` exception. - ##Mix this into your framework to simplify your life 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".Humanize` for that?!