SoftCircuits.Wordify 1.2.0

Prefix Reserved
dotnet add package SoftCircuits.Wordify --version 1.2.0                
NuGet\Install-Package SoftCircuits.Wordify -Version 1.2.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SoftCircuits.Wordify" Version="1.2.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SoftCircuits.Wordify --version 1.2.0                
#r "nuget: SoftCircuits.Wordify, 1.2.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install SoftCircuits.Wordify as a Cake Addin
#addin nuget:?package=SoftCircuits.Wordify&version=1.2.0

// Install SoftCircuits.Wordify as a Cake Tool
#tool nuget:?package=SoftCircuits.Wordify&version=1.2.0                

SoftCircuits.Wordify

NuGet version (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.

Numbers

The library can be used to convert numbers to words.

Code Output
1.Wordify(); one
123.Wordify(); one hundred twenty-three
12345.Wordify(); twelve thousand three hundred forty-five

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.

Code Output
345.7.Wordify(); three hundred forty-five and 7/10
345.7.Wordify(FractionOption.Fraction); three hundred forty-five and 7/10
345.7.Wordify(FractionOption.Check); three hundred forty-five and 70/100
345.7.Wordify(FractionOption.Words); three hundred forty-five and seven tenths
345.7.Wordify(FractionOption.UsCurrency); three hundred forty-five dollars and seventy cents
345.7.Wordify(FractionOption.Decimal); three hundred forty-five and .7
345.7.Wordify(FractionOption.Round); three hundred forty-six
345.7.Wordify(FractionOption.Truncate); three hundred forty-five

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

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 indicated).

Ordinals

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

Code Output
1.MakeOrdinal(); first
123.MakeOrdinal(); one hundred twenty-third

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

Code Output
1.MakeOrdinalDigits(); 1st
123.MakeOrdinalDigits(); 123rd

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.)

Code Output
now.Wordify(); now
now.Wordify(now); now
now.AddDays(0).Wordify(now); now
now.AddHours(2).AddMinutes(24).Wordify(); 2 hours from now
now.AddDays(4).Wordify(now); 4 days from now
now.AddHours(-2).AddMinutes(-24).Wordify(); 2 hours ago
now.AddHours(-2).AddMinutes(-24).Wordify(DateTimeOption.UseWords); two hours ago

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.

Code Output
TimeSpan.Zero.Wordify(); 0 milliseconds
new TimeSpan(4, 7, 44).Wordify(); 4 hours
new TimeSpan(4, 7, 44).Wordify(1); 4 hours
new TimeSpan(4, 7, 44).Wordify(2); 4 hours and 7 minutes
new TimeSpan(4, 7, 44).Wordify(3); 4 hours, 7 minutes and 44 seconds
new TimeSpan(4, 7, 44).Wordify(3, DateTimeOption.UseWords); four hours, seven minutes and forty-four seconds

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.

Code Output
"abcDef".Wordify(); abc Def
"abc_def".Wordify(WordifyOption.AutoDetect); abc def
"abc-def".Wordify(WordifyOption.AutoDetect); abc def
"abc-def".Wordify(WordifyOption.ReplaceHypens); abc def

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

Code Output
"ThisIsATest".InsertCamelCaseSpaces(); This Is A Test
"TheHTTPProtocol".InsertCamelCaseSpaces(); The HTTP Protocol
"IBoughtAnOldIBMXT".InsertCamelCaseSpaces(); I Bought An Old IBMXT

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,
}
Code Output
MyEnums.One.Wordify(); First enum
MyEnums.Two.Wordify(); Second enum
MyEnums.Two.Wordify(true); Two
MyEnums.Three.Wordify(false); Third enum
MyEnums.OnTheGo.Wordify(); On The Go
MyEnums.ReadHTMLPage.Wordify(); Read HTML Page

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.

Code Output
"cat".Pluralize(); cats
"boy".Pluralize(); boys
"cross".Pluralize(); crosses
"party".Pluralize(); parties
"goose".Pluralize(); geese
"sheep".Pluralize(); sheep
" dog! ".Pluralize(); dogs!

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

Code Output
"cats".Singularize(); cat
"boys".Singularize(); boy
"crosses".Singularize(); cross
"parties".Singularize(); party
"geese".Singularize(); goose
"sheep".Singularize(); sheep
" dogs! ".Singularize(); dog!

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().

Code Output
"this is a test".SetUpperCase(); THIS IS A TEST
"THIS IS A TEST".SetLowerCase(); this is a test
"this is a test".Capitalize(); This is a test
"this is a test".CapitalizeAll(); This Is A Test
"this is a test".SetTitleCase(); This is a Test
"this is a test".SetCase(CaseOption.Capitalize); This is a test

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.

Code Output
"Another test string".Truncate(16); Another test str
"Another test string".Truncate(16, TruncateOption.None); Another test str
"Another test string".Truncate(16, TruncateOption.AppendEllipsis); Another test ...
"Another test string".Truncate(16, TruncateOption.TrimPartialWords); Another test
"Another test string".Truncate(16, TruncateOption.TrimPartialWords \| TruncateOption.AppendEllipsis); Another test...

Displaying Memory Size

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

Code Output
0.ToMemorySize(); 0 B
1.ToMemorySize(); 1 B
1000UL.ToMemorySize(MemorySizeOption.Decimal); 1 KB
1024UL.ToMemorySize(MemorySizeOption.Binary); 1 KiB
1124UL.ToMemorySize(MemorySizeOption.Binary); 1.1 KiB

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.

Code Output
"0 B".ParseMemorySize(); 0UL
"1b".ParseMemorySize(); 1UL
"1 kb".ParseMemorySize(); 1000UL
"1.1 KIB".ParseMemorySize(); 1124UL

Roman Numerals

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

Code Output
0.ToRomanNumerals(); N
1.ToRomanNumerals(); I
2.ToRomanNumerals(); II
3.ToRomanNumerals(); III
4.ToRomanNumerals(); IV
1900.ToRomanNumerals(); MCM
1912.ToRomanNumerals(); MCMXII
2000.ToRomanNumerals(); MM
2022.ToRomanNumerals(); MMXXII

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.

Code Output
"N".ParseRomanNumerals(); 0
"I".ParseRomanNumerals(); 1
"II".ParseRomanNumerals(); 2
"III".ParseRomanNumerals(); 3
"IV".ParseRomanNumerals(); 4
"MCM".ParseRomanNumerals(); 1900
"MCMXII".ParseRomanNumerals(); 1912
"MM".ParseRomanNumerals(); 2000
"MMXXII".ParseRomanNumerals(); 2022
" V ".ParseRomanNumerals(); 5

Spreadsheet Column Names

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

Code Output
1.ToSpreadsheetColumn(); A
2.ToSpreadsheetColumn(); B
3.ToSpreadsheetColumn(); C
26.ToSpreadsheetColumn(); Z
27.ToSpreadsheetColumn(); AA
28.ToSpreadsheetColumn(); AB

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.

Code Output
"A".ParseSpreadsheetColumn(); 1
"B".ParseSpreadsheetColumn(); 2
" C ".ParseSpreadsheetColumn(); 3
" z ".ParseSpreadsheetColumn(); 26
" aa ".ParseSpreadsheetColumn(); 27
"ab".ParseSpreadsheetColumn(); 28

Formatting Collections

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

Code Output
(new[] { 1, 2, 3 }).Wordify(); 1, 2 and 3
(new[] { 1, 2, 3 }).Wordify(CollectionOption.AndConjunction); 1, 2 and 3
(new[] { 1, 2, 3 }).Wordify(CollectionOption.OrConjunction); 1, 2 or 3
(new[] { 1, 2, 3 }).Wordify(CollectionOption.OxfordComma); 1, 2, and 3
(new[] { 1, 2, 3 }).Wordify(CollectionOption.OrConjunction \| CollectionOption.OxfordComma); 1, 2, or 3

Formatting Data

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

Code Output
Wordify.FormatPhoneNumber("1234567"); 123-4567
Wordify.FormatPhoneNumber("1234567890"); 123-456-7890
Wordify.FormatPhoneNumber("1234567890", PhoneOption.AreaCodeParentheses); (123) 456-7890
Wordify.FormatPhoneNumber("12345678901"); 1-234-567-8901
Wordify.FormatPhoneNumber("12345678901", PhoneOption.InternationalPlusSign); +1-234-567-8901
Wordify.FormatPhoneNumber(" 1 2 3 4 5 6 7 "); 123-4567
Code Output
Wordify.FormatName("John"); John
Wordify.FormatName("John", "Van Dyk"); John Van Dyk
Wordify.FormatName("John", "Van Dyk", "W.", "Dr.", "III"); Dr. John W. Van Dyk III
Code Output
Wordify.FormatAddress("123 Elm"); 123 Elm
Wordify.FormatAddress("123 Elm", "Apt 3", delimiter: "-"); 123 Elm-Apt 3
Wordify.FormatAddress("123 Elm", "Apt 3", "Small Town", "UT", "84084", "United States", delimiter: "-"); 123 Elm-Apt 3-Small Town, UT 84084-United States
Code Output
Wordify.FormatCityStateZip("Small Town"); Small Town
Wordify.FormatCityStateZip("Small Town", "UT"); Small Town, UT
Wordify.FormatCityStateZip("Small Town", "UT", "84084"); Small Town, UT 84084

Quoting Strings

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

Code Output
"abc".WrapInQuotes(); "abc"
'a'.WrapInQuotes(); "a"
"abc".WrapInSingleQuotes(); 'abc'
'a'.WrapInSingleQuotes(); 'a'

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.

Extension Method Description
s.CountWords(); Counts the number of words in this string. Words are separated by one or more whitespace character.
s.NormalizeWhiteSpace(); Returns a copy of s with all whitespace sequences replaced with a single space character and all leading and trailing whitespace removed.
s.EmptyIfNull(); If s is null, then an empty string is returned. Otherwise, s is returned.
s.NullIfEmpty(); If s is an empty string, then null is returned. Otherwise, s is returned.
s.EmptyIfNullOrWhiteSpace(); If s is null, an empty string or only contains whitespace, then an empty string is returned. Otherwise, s is returned.
s.NullIfEmptyOrWhiteSpace(); If s is null, an empty string or only contains whitespace, then null is returned. Otherwise, s is returned.
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.2.0 145 3/17/2024
1.1.5 223 7/16/2023
1.1.4 230 4/5/2023
1.1.3 314 1/15/2023
1.1.2 302 1/15/2023
1.1.1 280 12/28/2022
1.1.0 314 11/25/2022
1.0.9 662 10/27/2022
1.0.8 421 9/4/2022
1.0.7 403 8/6/2022
1.0.6 389 8/5/2022
1.0.5 431 7/16/2022
1.0.4 426 6/26/2022
1.0.3 422 6/18/2022
1.0.2 425 6/11/2022
1.0.1 409 6/11/2022
1.0.0 392 6/11/2022

Added direct support for .NET 8; Removed direct support for deprecated .NET 5; Added XML documentation file; Minor tweaks and fixes.