RepletoryLib.Utilities.Formatting 1.0.0

RepletoryLib.Utilities.Formatting

Currency, phone, date, number, name, ID, and string formatting utilities with South African focus.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Utilities.Formatting provides a collection of static extension methods for formatting common data types into human-readable strings. The formatters are tailored for South African conventions (ZAR currency, SA phone numbers, SA ID numbers) while also supporting international formats.

All formatters are static extension methods -- no DI registration required. Simply add the package and start using the extensions.

Key Features

• Currency -- ZAR, USD, and generic currency formatting
• Phone -- E.164, local SA, and display formats
• Date -- SA date format, ISO 8601, relative time, and friendly dates
• Number -- Ordinals, file sizes, and percentages
• Name -- Title case, initials, and formal name formatting
• ID number -- SA ID masking and formatting
• String -- Slugs, sentence case, word wrap, and pluralization

Installation

dotnet add package RepletoryLib.Utilities.Formatting

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Utilities.Formatting" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Usage Examples

Currency Formatting

using RepletoryLib.Utilities.Formatting;

decimal price = 1_250_000.50m;

price.ToZar();                // "R 1,250,000.50"
price.ToUsd();                // "$1,250,000.50"
price.ToCurrency("EUR");      // "€1,250,000.50"

decimal small = 49.90m;
small.ToZar();                // "R 49.90"

Phone Formatting

using RepletoryLib.Utilities.Formatting;

string phone = "0831234567";

phone.ToE164();       // "+27831234567"
phone.ToLocalSa();    // "0831234567"
phone.ToDisplay();    // "+27 83 123 4567"

// International number
"+27831234567".ToLocalSa();  // "0831234567"
"+27831234567".ToDisplay();  // "+27 83 123 4567"

Date Formatting

using RepletoryLib.Utilities.Formatting;

var date = new DateTime(2025, 3, 15, 14, 30, 0);

date.ToSaDateString();   // "15/03/2025"
date.ToIso8601();        // "2025-03-15T14:30:00Z"
date.ToFriendlyDate();   // "15 March 2025"
date.ToRelativeTime();   // "2 hours ago" (depends on current time)

Number Formatting

using RepletoryLib.Utilities.Formatting;

1.ToOrdinal();     // "1st"
2.ToOrdinal();     // "2nd"
3.ToOrdinal();     // "3rd"
11.ToOrdinal();    // "11th"
23.ToOrdinal();    // "23rd"

1024L.ToFileSize();        // "1 KB"
1_048_576L.ToFileSize();   // "1 MB"
2_500_000L.ToFileSize();   // "2.38 MB"

0.75m.ToPercentage();  // "75%"
0.333m.ToPercentage(); // "33.3%"

Name Formatting

using RepletoryLib.Utilities.Formatting;

"john doe".ToTitleCase();     // "John Doe"
"John William Doe".ToInitials(); // "JWD"

NameFormatter.ToFormalName("Mr", "John", "Doe"); // "Mr John Doe"

ID Number Formatting

using RepletoryLib.Utilities.Formatting;

"9501015800087".MaskSaId();    // "**********087"
"9501015800087".FormatSaId();  // "950101 5800 08 7"

String Formatting

using RepletoryLib.Utilities.Formatting;

"Hello World! C# is Great".ToSlug();     // "hello-world-c-is-great"
"hello world".ToSentenceCase();          // "Hello world"

"A long paragraph text".WrapAt(10);
// "A long\nparagraph\ntext"

1.Pluralize("item", "items");   // "1 item"
5.Pluralize("item", "items");   // "5 items"
0.Pluralize("item", "items");   // "0 items"

API Reference

CurrencyFormatter

PhoneFormatter

DateFormatter

NumberFormatter

NameFormatter

IdNumberFormatter

StringFormatter

Integration with Other RepletoryLib Packages

Testing

All formatters are static extension methods with no external dependencies, making them trivial to test:

[Theory]
[InlineData(1, "1st")]
[InlineData(2, "2nd")]
[InlineData(3, "3rd")]
[InlineData(11, "11th")]
[InlineData(21, "21st")]
public void ToOrdinal_formats_correctly(int input, string expected)
{
    input.ToOrdinal().Should().Be(expected);
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.