Decode byte-bounded text

Intermediate · C#. A buffer count measures encoded bytes. UTF-8 and UTF-16 characters can use several bytes, while CP437 and Latin-1 map single bytes differently.

Run this example

Prerequisites: the repository's .NET 10 SDK and a checkout of this source. Run from the repository root:

dotnet run --project docs/examples/CStructSharp.Docs.Examples.csproj -c Release -- bounded-encodings

The runner checks Euro, accented and supplementary characters with exact byte counts and endian order. Success includes PASS bounded-encodings.

Try the related browser lesson.

Complete program

The layout, options, input bytes, helper methods, and required types are all included. To adapt it outside the repository, create a .NET 10 console project, add CStructSharp, and replace Program.cs with this complete file. These examples follow the source version; use a matching package when testing a release.

Download the complete C# source.

// Generated from executable documentation examples. Edit the source region, then regenerate.
using System;
using System.IO;
using System.IO.Pipelines;
using System.Linq;
using System.Buffers;
using System.Collections.Generic;
using System.Dynamic;
using System.Globalization;
using System.Numerics;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Threading.Tasks;
using CStructSharp;
using CStructSharp.Codecs;
using CStructSharp.Diagnostics;
using CStructSharp.Introspection;
using CStructSharp.Values;

internal static partial class Program
{
    public static void Main()
    {
        BoundedEncodings();
        Console.WriteLine("PASS bounded-encodings");
    }

    private static void BoundedEncodings()
    {
        const string definition = "struct root { utf8 currency[3]; latin1 western[1]; cp437 dos[1]; utf16le little[4]; utf16be big[4]; uint8 tail; };";
        var layout = new CStruct(definition, aligned: false);
        var value = new Dictionary<string, object?> { ["currency"] = "€", ["western"] = "é", ["dos"] = "é", ["little"] = "😀", ["big"] = "😀", ["tail"] = 99 };
        byte[] bytes = layout.Serialize("root", value);
        SequenceEqual(Convert.FromHexString("E282ACE9823DD800DED83DDE0063"), bytes);
        StructValue parsed = layout.Parse(bytes, "root");
        Equal("€", parsed.Get<string>("currency"));
        Equal("é", parsed.Get<string>("dos"));
        Equal("😀", parsed.Get<string>("little"));
        Equal("😀", parsed.Get<string>("big"));
        Equal((byte)99, parsed.Get<byte>("tail"));
        SequenceEqual(bytes, layout.Serialize("root", parsed));
        Throws<CStructWriteException>(() => layout.Serialize("root.currency", "€!"));
    }

    private static void Equal<T>(T expected, T actual)
    {
        if (!EqualityComparer<T>.Default.Equals(expected, actual))
        {
            throw new InvalidOperationException($"Expected '{expected}', received '{actual}'.");
        }
    }

    private static void SequenceEqual(byte[] expected, byte[] actual)
    {
        if (!expected.AsSpan().SequenceEqual(actual))
        {
            throw new InvalidOperationException(
                $"Expected {Convert.ToHexString(expected)}, received {Convert.ToHexString(actual)}.");
        }
    }

    private static void Throws<TException>(Action action)
        where TException : Exception
    {
        try
        {
            action();
        }
        catch (TException)
        {
            return;
        }

        throw new InvalidOperationException($"Expected {typeof(TException).Name}.");
    }
}

Try it and diagnose mistakes

Change the UTF-8 capacity from 3 to 2.

Answer: The Euro sign requires three bytes. Serialization rejects it instead of truncating a character. The program contains assertions for its original inputs. When changing an input intentionally, update the expected assertion too; an unchanged assertion is not evidence that the new value is wrong.

Continue with the related guide or choose another recipe.