SoftCircuits.Wordify 1.1.4

SoftCircuits.Wordify

Install-Package SoftCircuits.Wordify

Wordify is a static class that contains extension methods to create and modify text. It includes methods to convert numbers and dates to text, insert spaces into camel-case strings, pluralize strings, truncate strings, convert Roman numerals, create memory size strings and much more.

Note: Wordify methods that accept a string parameter always correctly handle when that parameter is null. And all methods that return a string ensure the return value is never null (unless otherwise documented).

Numbers

The library can be used to convert numbers to words.

The Wordify() method has many overloads. The one that accepts floating point values also accepts a FractionOption argument that specifies how to format the fractional part.

Note: Because most of these methods return strings, it's easy to chain extension method calls. For example: 123.67.Wordify(FractionOption.Decimal).Capitalize();.

Ordinals

The library also has support for converting numbers to ordinals using the MakeOrdinal() extention method.

The MakeOrdinalDigits() extension method works similarly but outputs digits instead of words.

Dates and TimeSpans

The library also provides support for describing the differences between two DateTime values. This version of Wordify() describes the relationship between the specified date and time with the current date and time. Or, you can supply your own date and time that the description should be relative to.

The following examples assume a DateTime variable with the name now. (Note that when using the version that automatically gets the current date and time, that it's possible to have a couple of milliseconds pass before it does.)

Here are examples using the version of Wordify() for TimeSpan values. This method also takes a precision argument. By default, the precision is 1, and only one part of the time span will be described. Pass a larger number to include additional parts.

Wordifying Strings

SoftCircuits.Wordify has several methods to help convert symbol names like TotalCount, total_count and total-count to text like total count. The examples below use the Wordify() extension method. If you know what method should be used for your string, you can achieve a small performance gain by passing the appropriate WordifyOption option. Otherwise, you can pass WordifyOption.AutoDetect and Wordify() will attempt to automatically detect the type of transformation needed.

If you know your string contains camel case, you can call the InsertCamelCaseSpaces() extension method directly.

Notice in the last example that there is no way to detect if IBM and XT should be separate words. That's just a limitation of word detection from camel case.

Wordifying Enums

Finally, there is a variation of the Wordify() method specifically for enums. This extension method takes an enum. If the enum value has a DescriptionAttribute attribute, the method returns the description from that attribute. Otherwise, the name of the enum is passed to the Wordify() extension method described above.

This Wordify() extension method takes an optional bool argument that, when set to true, will prevent this method from checking for the presence of a DescriptionAttribute.

The examples below assuming the following enum.

enum MyEnums
{
    [Description("First enum")]
    One,
    [Description("Second enum")]
    Two,
    [Description("Third enum")]
    Three,
    OnTheGo,
    ReadHTMLPage,
}

Pluralization

The library also provides support for making words plural and then back to singular again. Use the Pluralize() extension method to make a word plural.

And use the Singularize() extension method to make a plural word singular.

Another variation of the Pluralize() method accepts a numeric argument. This method pluralizes the string only when the numeric value is not equal to 1.

Note that the English language is complex. It is just not possible for the library to handle every word perfectly. You can use the Wordify.AddIrregularNoun() and Wordify.AddDefectiveNoun() methods to add additional words that require special handling by the pluralizer.

Converting Case

Wordify contains several extension methods for setting case of a string. You can use any of the individual methods SetUpperCase(), SetLowerCase(), Capitalize(), CapitalizeAll() or SetTitleCase(). Or you can pass a CaseOption parameter to SetCase().

Truncating Strings

The library has several methods that help in formatting strings that are too long. The Truncate() method wil shorten a string according to the options you specify.

Displaying Memory Size

The ToMemorySize() extension method is handy when displaying a number of bytes, such as the size of a file.

You can use the ParseMemorySize() extension method to convert a memory size string back to a ulong. This method does not throw any exceptions. It simply parses the string as best it can. If it is unable to parse anything meaningful, this method returns 0.

Roman Numerals

The ToRomanNumerals() extension method converts a number to Roman numerals.

Use the ParseRomanNumerals() extension method to convert a string of Roman numerals back to an integer. This method throws an exception if the string cannot be converted. You can also use the TryParseRomanNumerals() method to instead return false when a string cannot be converted.

Spreadsheet Column Names

Support is also provided for generating and parsing spreadsheet column names.

Use the ParseSpreadsheetColumn() extension method to convert a spreadsheet column name back to an integer. This method throws an exception if the string cannot be converted. You can also use the TryParseSpreadsheetColumn() method to instead return false when a string cannot be converted.

Formatting Collections

Use the Wordify() extension method to combine a collection of items into a string.

Formatting Data

The library includes several static methods that make it easy to format various types of data.

Quoting Strings

Use the WrapInQuotes() and WrapInSingleQuotes() methods to wrap a string or character in double or single quotes.

Miscellaneous

The library also includes a number of helper extension methods that don't really fall into any other category. The examples below assume a variable s of type string.