Cuemon.Extensions.Text

Overview

Cuemon.Extensions.Text extends Cuemon.Text with four convenience methods that hang directly off string and IEncodingOptions. The package is small by design: StringExtensions exposes the decorator-based encoding pipeline as ordinary string extensions, while EncodingOptionsExtensions adds BOM-aware encoding detection that falls back to the caller's configured default.

The package does not introduce a separate text abstraction layer. Its methods are thin, fail-fast wrappers over lower-level Cuemon APIs such as Decorator.Enclose(...).ToEncodedString(...) and ByteOrderMark.DetectEncodingOrDefault(...), which makes it useful when you want the Cuemon text primitives without carrying decorator calls through consumer code.

Key APIs

StringExtensions.ToEncodedString encodes a string through a FallbackEncodingOptions setup delegate, then returns the converted text as a new string. It is the general-purpose entry point when you need a target encoding and explicit fallback behavior but want to stay on the string surface.

StringExtensions.ToAsciiEncodedString specializes the conversion pipeline for ASCII output. Internally it routes through ToEncodedString, pins TargetEncoding to Encoding.ASCII, and uses an empty EncoderReplacementFallback, so unsupported characters are removed instead of replaced with visible placeholder characters.

EncodingOptionsExtensions.DetectUnicodeEncoding(Stream) inspects a stream for a byte order mark and returns the detected Encoding when one is present. When detection fails, it returns options.Encoding, so callers can keep a deterministic fallback instead of branching around missing BOM metadata.

EncodingOptionsExtensions.DetectUnicodeEncoding(byte[]) provides the same fallback-aware BOM detection for in-memory payloads. It is the matching overload when the caller already has raw bytes and does not need to materialize a Stream first.

Basic usage

using Codebelt.Extensions.Xunit;
using Cuemon.Extensions.Text;
using Xunit;

namespace MyProject.Tests;

public class LegacyExportNameTest : Test
{
    public LegacyExportNameTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ToAsciiEncodedString_ShouldRemoveCharactersUnsupportedByAscii()
    {
        var exportName = "release-café-v1".ToAsciiEncodedString();

        TestOutput.WriteLine($"ASCII export name: {exportName}");

        Assert.Equal("release-caf-v1", exportName);
    }
}

Use this pattern when text must cross an ASCII-only boundary such as a legacy export name, identifier, or integration field. It matters because the package exposes Cuemon's encoding conversion pipeline as a single string extension instead of forcing callers to compose decorator and fallback plumbing by hand.

Installation

dotnet add package Cuemon.Extensions.Text

Usage guidance

Adopt Cuemon.Extensions.Text when you already rely on Cuemon text primitives and want the common conversion and Unicode-detection workflows to read as direct extensions on string and IEncodingOptions. If you need lower-level control over decorators or byte processing, use the underlying Cuemon.Core and Cuemon.Text APIs directly; if the built-in System.Text.Encoding methods already cover your case, you can skip this package.