naxp 0.13.0

naxp

A naxp ('encoded ASCII expression') uses a regex-like syntax to define how ASCII strings should be mapped to a numerical index.

With one simple expression you can standardise conversion of alphanumeric codes to integer indexes unambiguously and consistently across multiple coding languages and hardware platforms.

dotnet add package naxp

The naxp package includes a source generator that compiles a naxp into your own type at build time, as C# does for regexes, and a library for a naxp not known until the program runs. It targets .NET 8 and .NET Standard 2.0, so it runs on .NET Framework too.

Why use a naxp rather than roll your own encoding?

1. A naxp is simpler and safer than writing your own custom encoding.

2. The mapping is language and platform independent.

3. All naxps covering the same set of ASCII strings result in the same encoding, which means that the mapping is robust.

Example

UK postcodes are sufficiently non-trivial that writing your own encoding risks creating bugs. A UK postcode comprises one or two letters, a number, an optional additional letter or number, a space separator (that may be omitted in practice), and then a number and two letters. Examples are EC4M 8AD and M1 1AA.

This is the standard naxp for a UK postcode:

\A\A?\9\X? \s!! \9\A\A | GIR \s!! 0AA

Some points to note:

• We've used the shortcuts \A for any uppercase letter, \9 for any digit and \X for any uppercase letter or digit. We could have written [A-Z], [0-9] and [A-Z0-9] instead.
• ?, | and [...] mean the same as in regexes, i.e. one or none, a or b, and character range respectively.
• naxps ignore whitespace – use \s to mean an actual space.
• !! after the space makes it optional without changing the encoding, which ensures that EC4M8AD and EC4M 8AD are mapped to the same encoded value. (Using ?, which might be your first instinct if you are used to regexes, would instead map each of these to different encoded values.) A naxp written with a ! operator maps multiple texts to a single encoded value, but defines one of those texts as canonical.
• GIR 0AA is a single anomalous but real postcode, so the naxp specifies it explicitly.

The naxp source generator

If a naxp is known at compile time then use the source generator.

Add the [Naxp] attribute to a partial class and the source generator will add the naxp functionality with no need to reference the naxp package at run time.

using LogMu;

[Naxp(@"\A\A?\9\X? \s!! \9\A\A | GIR \s!! 0AA", typeof(int))]
static partial class Postcode
{
}

Postcode.MaxEncodedValue;               // 1755842401
Postcode.MaxLength;                     // 8
Postcode.Encode("EC4M 8AD");            // 278794572
Postcode.Encode("EC4M8AD");             // 278794572 (same as above)
Postcode.Decode(278794572);             // "EC4M 8AD" (canonical form)
Postcode.GetCanonicalForm("EC4M 8AD");  // "EC4M 8AD" (canonical form)
Postcode.GetCanonicalForm("EC4M8AD");   // "EC4M 8AD" (canonical form)
Postcode.Accepts("invalid");            // false
Postcode.Encode("invalid");             // 0

// Performant Try... and span-writing overloads are also generated -- see the API below.

Each naxp generates static versions of the members of the library's Naxp object listed below, other than Emit and ToString, with Pattern, MaxEncodedValue and MaxLength as constants.

If you want to use the same class for more than one naxp then use [Naxp] multiple times but with different Prefix arguments to distinguish the systems.

The generated code needs C# 7.3 or later, and carries nullable annotations where the target framework supports them. The source generator needs the .NET 8 SDK or Visual Studio 2022 17.8 or later.

Error codes begin with 'NAXP' and are documented at naxp.org/error-codes/.

Using a naxp at run time

If a naxp is not known until run time (e.g. because it's read from configuration or chosen by a user) then use the library, which provides the same functionality but dynamically.

using LogMu;

var postcode = Naxp.Parse(@"\A\A?\9\X? \s!! \9\A\A | GIR \s!! 0AA");

postcode.MaxEncodedValue;               // 1755842401
postcode.MaxLength;                     // 8
postcode.Encode("EC4M 8AD");            // 278794572
postcode.Encode("EC4M8AD");             // 278794572 (same as above)
postcode.Decode(278794572);             // "EC4M 8AD" (canonical form)
postcode.GetCanonicalForm("EC4M 8AD");  // "EC4M 8AD" (canonical form)
postcode.GetCanonicalForm("EC4M8AD");   // "EC4M 8AD" (canonical form)
postcode.Accepts("invalid");            // false
postcode.Encode("invalid");             // 0

The API

This section sets out the library API.

The source-generated members are the same, as static members of your class, except that the encoded value type will be the integer type requested as opposed to the ulong type used by the library. See the example above under naxp source generator.

Factory methods

The pattern argument of Naxp.Parse and Naxp.TryParse is a string or a ReadOnlySpan<char>.

A longer overload of TryParse provides additional diagnostics if required:

bool succeeded = Naxp.TryParse(
    "A{2-5}", out Naxp? naxp,
    out string? errorMessage,
    out int errorOffset, out int errorLength, out string? errorCode);

succeeded;      // false
naxp;           // null
errorMessage;   // "The counts of an interval are separated by ',', not '-'. Write 'A{2,5}'."
errorOffset;    // 3 (zero-based offset)
errorLength;    // 1
errorCode;      // "NAXP1002" (always text)

Use errorOffset and errorLength to locate the issue:

A{2-5}
   ^  The counts of an interval are separated by ',', not '-'. Write 'A{2,5}'.

If the error relates to the whole naxp then the whole text range is specified.

Naxp object members

Encode always returns a ulong in order to avoid overflow (given that a naxp can hold up to 2^64 - 1 encoded values).

The text argument is a string, a ReadOnlySpan<char> or a ReadOnlySpan<byte> of ASCII.

The destination argument of TryDecode and TryGetCanonicalForm is a text buffer of Span<char> or Span<byte>, with written being set to the number of characters written.

Comparing two naxps

Note

This functionality is provided primarily to enable the website naxp migration functionality. It is included here for completeness – it is unlikely that you will require it in normal use.

Use these to determine whether replacing one naxp with another retains the meaning of stored encoded values. See migrating.

Compare addresses text inputs and FirstDivergentValue addresses text outputs. Both are required in the case where two naxps encode alike but print differently. For example, (A|B)!A and (A|B)!B accept the same two strings (A and B) and map each to the same encoded value (1). But they print differently (as A or B respectively), which is why FirstDivergentValue returns 1.

Determining the relationship between two naxps can be combinatorially expensive (especially for unrelated naxps) and so budget caps the number of states the comparison may build, defaulting to 200 000. Compare throws InvalidOperationException when that is not enough. FirstDivergentValue needs no budget, since it never builds more states than the two naxps themselves hold.

Status

Alpha. This package implements naxp 0.10, the first published specification. The package version and the specification version each follow semantic versioning, and move independently of one another. The public surface above is stable enough to build on, but the language is still on 0.x and nothing is promised until version 1.

This package is validated against conformance/naxp-v0.10.json, the test data generated from that specification.

Licence

Apache-2.0.