Proposal: Introducing User-Defined Literals (UDL) to C#

[shimodateakira]

Proposal: Introducing User-Defined Literals (UDL) to C#

TL;DR

Allow user-defined suffixes in the form of _<suffix> for numeric, string, interpolated string, and tuple literals.
This enables concise and type-safe representation of domain-specific values, with scope control via using static.

var d   = 1.5_km;                                // Numeric
var re  = @"^[a-z0-9_]+$"_regex;                 // String
var sql = $"select * from T where id={id}"_sql;  // FormattableString
var p   = (1920, 1080)_pt;                       // Tuple

---

1. What is UDL?

UDL (User-Defined Literal) is a mechanism that allows developers to attach custom meaning to literals, directly constructing instances of specific types.
In C++, for example, operator""_km can be defined so that a numeric literal is converted into a Distance type.

This proposal aims to bring a similar capability to C#, allowing domain-specific types to be constructed directly from literals.

---

2. Motivation

• Improved readability: 1.5_km is more intuitive than Distance.FromKilometers(1.5).
• Type safety: Units, formats, or constraints can be enforced by the type system, reducing errors such as unit conversion mistakes or SQL injection.
• Less verbosity: The syntax directly expresses intent in a compact form.
• Scoped usage: using static allows enabling UDLs only where needed.
• BCL and future feature compatibility: Works naturally with existing BCL types and future features such as extension operators.

---

3. Proposed Syntax

• Suffix format: _ + valid identifier
• Supported literal kinds: numeric, string, FormattableString, and tuples
• Definition uses the operator keyword
• Scope controlled by using static

Numeric literal

public static Distance operator _km(double v) => new(v * 1000);
var d = 1.5_km;

String literal

public static Regex operator _regex(string pattern) => new(pattern);
var re = @"^[a-z0-9_]+$"_regex;

Interpolated string (FormattableString)

public static SqlQuery operator _sql(FormattableString fs) => SqlQuery.From(fs);
var sql = $"select * from T where id={id}"_sql;

Tuple literal

public static Point operator _pt((int x, int y) coords) => new(coords.x, coords.y);
var p = (1920, 1080)_pt;

---

4. Example: Extending BCL Types (Compatibility with Future Extension Operators)

If extension operators are implemented in the future, UDLs would integrate seamlessly with existing BCL types.

For example, adding _ms, _s, _m, _h to TimeSpan would enable highly readable time specifications.
Moreover, the .NET BCL could define and ship these suffixes by default, allowing developers to use them out of the box.

// Hypothetical example if extension operators are implemented in C#
public static class TimeSpanExtensions
{
    extension(double v)
    {
        public static TimeSpan operator _ms(double v) => TimeSpan.FromMilliseconds(v);
        public static TimeSpan operator _s(double v)  => TimeSpan.FromSeconds(v);
        public static TimeSpan operator _m(double v)  => TimeSpan.FromMinutes(v);
        public static TimeSpan operator _h(double v)  => TimeSpan.FromHours(v);
    }
}

using static TimeSpanExtensions;

Thread.Sleep(500_ms);

---

5. Prior Art

• C++: Allows operator""_km for custom suffixes on numeric or string literals.
• Rust: Achieves literal-like syntax via macros and type system (no native UDL syntax with suffixes).
• Swift: Uses literal initialization protocols for types to be constructed from literals (type inference-based, no suffix syntax).

These examples show that UDLs are a proven method for improving readability and type safety.

---

6. Benefits

1. Conciseness - Domain-specific values in a single expression
2. Type safety - Units, formats, and constraints enforced at compile time
3. Scoped usage - Enabled only where necessary via using static
4. BCL-friendly - Works naturally with existing .NET types
5. Future-ready - Can integrate with extension operators and potential BCL-provided UDLs

---

7. Alternative syntax: suffix contextual keyword

As an alternative to extending operator to declare identifier-based UDLs, a contextual keyword suffix could be introduced specifically for declaring literal suffix handlers.
For example:

public static TimeSpan suffix _ms(double v) => TimeSpan.FromMilliseconds(v);

This is arguably more readable and keeps the grammar change isolated, but it adds a new declaration form (and a new keyword) and would need to be considered in the design of extension operators as “extension suffixes.”
For v1, we propose to keep operator to minimize impact, but if the Language Design Meeting (LDM) dislikes extending operator, suffix remains a viable syntactic sugar.

[CyrusNajmabadi]

Why not just do something like 1.km using extension properties?

Wrt to your motivation:

Improved readability: 1.5_km is more intuitive than Distance.FromKilometers(1.5).

I find that debatable. But even if so, 1.5.km seems totally fine.

Type safety: Units, formats, or constraints can be enforced by the type system, reducing errors such as unit conversion mistakes or SQL injection.

I don't understand this. How is that any different from calling apis? Regardless, of this is true for _ it would be true for .

Less verbosity: The syntax directly expresses intent in a compact form.

Same with dot

Scoped usage: using static allows enabling UDLs only where needed.

Same with .. It is only available if you import the extension.

BCL and future feature compatibility: Works naturally with existing BCL types and future features such as extension operators.

I don't know that this means. But it seems the same with ..

[shimodateakira]

Thank you for your comment.
I understand the approach you suggested.
However, in this proposal, I place emphasis on the conciseness and readability of literal expressions with the _ suffix, which has a slightly different focus from extension properties.
I will keep your feedback in mind and would like to wait for further input from others as well.

[HaloFour]

What makes _ more concise than .? With extension properties, you will already be able to write code like TimeSpan ts = 1.minutes;, so additional language features become unnecessary.

[CyrusNajmabadi]

However, in this proposal, I place emphasis on the conciseness and readability of literal expressions with the _ suffix,

What makes _ more concise than .? They are both one character long.

What makes it more readable?

which has a slightly different focus from extension properties.

I'm not sure what this means.

My point is this: you're suggesting a very narrow language feature. That narrow feature seems to already have been subsumed entirely with a new language feature coming in c#14.

[pedoc]

What makes _ more concise than .? With extension properties, you will already be able to write code like TimeSpan ts = 1.minutes;, so additional language features become unnecessary.

Hi, could you provide some sample code for this?

[ufcpp]

Console.WriteLine(1.minutes);

public static class TimeSpanExtensions
{
    extension(int x)
    {
        public TimeSpan minutes => TimeSpan.FromMinutes(x);
    }
}

[CyrusNajmabadi]

For example, adding _ms, _s, _m, _h to TimeSpan would enable highly readable time specifications.

I don't know if I agree. You already mentioned adding _km as an extension on numbers to give you distance. So I would expect _m to be the same ("meters"). But here it also means "minutes".

Using actual types with actual well named methods to create and consume them avoids this sort of inherent ambiguity entirely.

[shimodateakira]

You’re right that scope control alone doesn’t eliminate ambiguity.
In this proposal, if the same suffix is provided by multiple sources in the same scope, it’s a compile-time error by design. Library authors are expected to pick distinct names per domain, and consumers can opt for longer suffixes when mixing domains (e.g., _meter vs _minute).
The feature targets domain-focused code where a given suffix is conventional, rather than scenarios that intentionally mix conflicting meanings. Thanks for the feedback.

[CyrusNajmabadi]

consumers can opt for longer suffixes when mixing domains (e.g., _meter vs _minute).

I don't see anything in your proposal that allows for this. How do consumers control the suffix? It seems entirely determined by the lib author.

[shimodateakira]

The idea for this proposal started from a simple thought:
"Wouldn’t it be useful if user-defined types could have literal representations, just like built-in types?"
For example, in C#, 1L or 1l represents a long value of 1. I thought it would be great if we could do the same for user-defined types.
At first, I wasn’t aware of the concept of User-Defined Literals in C++, but when I later learned about it, I thought: "This is exactly what I had in mind!"
That’s what led me to explore how this idea could be adapted to C#.

[CyrusNajmabadi]

I thought it would be great if we could do the same for user-defined types.

I understand. What I'm saying is: we have a feature that seems to meet you do this. It's virtually identical to your suggestion, except that it uses . for the literal, not _. I'm asking: why so o we need ANOTHER feature, just to support that single character difference?

[GabeSchaffer]

The big difference with the C++ feature is that it allows you to define a function that is passed in numeric literals as a string, allowing you to have bignum or extended precision floats literals.

The C# counterpart requires anything that isn't representable as a C# numeric literal be entered as a string. For example, 1.3_X could be equivalent to X("1.3"), while 1.3.X is equivalent to X(1.2999999523162841796875).

[ufcpp]

You can use Source Generator (Interceptor) for that purpose.

[GabeSchaffer]

You can use Source Generator (Interceptor) for that purpose.

Interesting idea. I think I understand what you're saying, but my belief is that an expression like 1.3.X lowers to a property accessor on an extension to double, and I thought only methods (not property accessors) could be intercepted. Would your idea really work?

[TahirAhmadov]

There are 2 reasons why _ is better than just using extension properties:

1. With extension properties on basic types, like int, etc., the list of possible identifiers to follow an int becomes very long; it's already a problem in my code, because of the extension methods on object to do things which C# doesn't have constructs for. Basically, you type 123. and you get a long list of stuff, a lot of which you don't care about.
2. They will light up on all expressions of type int, etc., not just literals; this is probably undesirable, because the intention is to have a physical (like distance) literal, and something like (a + b).km is definitely not a literal.
3. PS. I thought about one more reason - with extensions, you need to define them on each numerical type, int, double, etc.; whereas with a "literal feature", I can imagine it being designed in a way that a double is specified, and then it lights up for all numerical literals which can be converted to double.

The above defense of _ shouldn't be misconstrued as my support for this proposal, in fact, I don't support it. That's because I don't see the value in specifying these physical values as literals in the first place. Yes C# is a great language to do complex calculations (one of my projects does some of that stuff and it works great), however values are supposed to be inputs to a program; to me, if code has 1.5_km hard coded, it's a huge code smell. And the language shouldn't make it easier to write bad code.
The only literal type I can get behind is TimeSpan because of the multitude of waiting scenarios where it does make sense to hard code timeouts (again, not always, but definitely more justifiable than distance/weight/etc.). There was a discussion about that; extension properties make sense for such a small quality of life improvement. Ideally, if the m, s and ms extension properties have [EditorVisible(Never)] (or whatever) attribute on them which is respected, then the intellisense is not polluted. You can do 500.ms and it's obviously easier to write and probably easier to read than TimeSpan.FromMilliseconds(500) etc.

[full-ing-arr]

var d   = 1.5_km;                                // Numeric
var re  = @"^[a-z0-9_]+$"_regex;                 // String
var sql = $"select * from T where id={id}"_sql;  // FormattableString
var p   = (1920, 1080)_pt;                       // Tuple

what a reason when we can use

Km d   = 1.5;
Regex re  = @"^[a-z0-9_]+$";
Sql sql = $"select * from T where id={id}";
Pt p  = (1920, 1080);

or

var d   = new Km(1.5);
var re  = new Regex (@"^[a-z0-9_]+$");
var sql = new Sql ($"select * from T where id={id}");
var p   = new Pt(1920, 1080);

or

var d _km  = 1.5;
var re_regex  = @"^[a-z0-9_]+$";
var sql_sql = $"select * from T where id={id}";
var p_pt   = (1920, 1080);

or better use extensions (https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/extension-methods)

var d   = 1.5.km;
var re  = @"^[a-z0-9_]+$".regex;
var sql = $"select * from T where id={id}".sql;
var p  = (1920, 1080).pt;

[full-ing-arr]

may be at one case, where it has sense, it's static-check and no effect to runtime, instead ext properties, if lasts not can argessive inline and we lost perfomance
what i lost at here?