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:

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

using suffix TimeSpanExtensions;

Thread.Sleep(500_ms);

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?

[MrUnbelievable92]

People seem to misunderstand what kind of problem this would actually solve.
It is not there to denote a unit - a unit is better expressed as a type. Structs are zero cost abstractions that solve this issue.

I, on the other hand, have encountered problems which cannot be solved without user defined literals or rather in a very ugly way.
Consider a custom UInt128 data type. Yes - some of us are forced to use old C# language versions. Currently assigning it a value in a remotely clean way is impossible.
UInt128 d = 13297135693178561563518 does not compile. You have two possibilites:

• Use a literal (hmmmmm) d, denoting it as a double. Now you either have to both have and use a double-to-UInt128 type conversion and either perform it explicitly or have horrible code where that cast is implicit. Note that double cannot store this value exactly, so this makes the use of extension properties useless here. What you guys gave as examples are not problems user defined literals solve.
• Have your own string to UInt128 type conversion operator and make it implicit, where you have additional " symbols clearly denoting it as a string and making this a code smell. And this method is probably the preferred one, which is functionally similar/identical to user defined literals just in an ugly way. What if my type required a different string-to-type conversion as well? Use Parse()? Pff
  Additionally, if the conversion is implemented as a loop, the compiler potentially cannot reason as to whether or not the conversion code ever finishes executing, so these literals are clogging up my applications' memory. But this may be more of a problem with C# itself, not having a way to force compile time evaluation of specifically marked methods like with consteval in C++. These user defined literals would have to be compile time evaluated, a problem C# suffered from for a long time, which was the reason why you weren't able to define default constructors for structs or declare custom types as const. Has that changed?

Either way, this exact same problem comes up with software implemented quadruple precision floating point types and literals. For both these cases I simply end up logging the result of the string conversion to the console in hex in some dev environment and use constructors that take in 64bit halves instead of simply writing "1E+4000q". Really annoying, unreadable and tedious.

I was able to live with that, until I encountered another issue with not having this feature in a SIMD math library I maintain. There I have half precision SIMD vectors and in order to not have to write bool16 b = myHalf16 != (half)0f; everywhere, I would have to make floats implicitly convertible to half and half16 instead of being able to write bool16 b = myHalf16 != 0h;", which would kind of break the expectation that narrower types will be upcast to match the other type to which to perform an arithmetic operation with, which would come at a "hefty" performance cost in SIMD code especially. This is also the reason i cannot simply define operator overloads with a float as an operand here, while i would be able to, safely, if I had access to user defined literals.

The point is, every type that could reasonably be expressed as a literal should have a user defined literal, especially - and this is the big one guys - if other literal types like long or double cannot represent it. That's not Kilometers myDistance = 1000; (see what I did there? thats called a "type" ;) YOU CAN EVEN ADD METERS TO IT :O ), it's the cases i demonstrated earlier.
You can misuse and abuse any feature, but that does not make the feature itself bad or unnecessary.

[full-ing-arr]

some points more
myT 4byte
in a memory layout 8 bytes
struct myT //a memory layout
...

in a single operation on register 6 bytes
struct myT //a processing layout
..
in a custom simd packed 5 bytes
struct myT //a layout of the simd packs
..
var vec = new 512

so we have more than these three
how to unifie this
var data = 1248f_myT-literal// witch one?
looks like unsafe a structure cast issue too

[full-ing-arr]

mb point in smth:
int160 d = (0xaaaa, 0xbbbb, 0xcccc, 0xdddd, 0xeeee).int128
instead binary literal _b
int160 d = aaaabbbbccccddddeeee_b5;
but diff between different memory layouts

aaaabbbbccccddddeeee
eeeeddddccccbbbbaaaa
0000eeeeccccddddaaaabbbb
000000000000eeeeaaaabbbbccccdddd

???