Yerel boyutlu tamsayılarNative-sized integers

ÖzetSummary

Yerel boyutlu imzalı ve işaretsiz tamsayı türleri için dil desteği.Language support for a native-sized signed and unsigned integer types.

Mosyon, birlikte çalışma senaryolarına ve alt düzey kitaplıklara yöneliktir.The motivation is for interop scenarios and for low-level libraries.

TasarımDesign

Tanımlayıcılar nint ve nuint Yerel imzalı ve işaretsiz tamsayı türlerini temsil eden yeni bağlamsal anahtar sözcüklerdir.The identifiers nint and nuint are new contextual keywords that represent native signed and unsigned integer types. Tanımlayıcılar yalnızca ad arama, bu program konumunda önemli bir sonuç bulamadığında anahtar sözcük olarak değerlendirilir.The identifiers are only treated as keywords when name lookup does not find a viable result at that program location.

nint x = 3;
string y = nameof(nuint);
_ = nint.Equals(x, 3);

Türler nint ve nuint temel alınan türler tarafından temsil edilir System.IntPtr ve derleyici, System.UIntPtr Bu türler için yerel olarak ek dönüştürmeler ve işlemler elde eder.The types nint and nuint are represented by the underlying types System.IntPtr and System.UIntPtr with compiler surfacing additional conversions and operations for those types as native ints.

SabitlerConstants

Sabit ifadeler veya türünde olabilir nint nuint .Constant expressions may be of type nint or nuint. Yerel int değişmez değerleri için doğrudan bir sözdizimi yoktur.There is no direct syntax for native int literals. Bunun yerine, diğer integral sabit değerlerinin örtük veya açık yayınları kullanılabilir: const nint i = (nint)42; .Implicit or explicit casts of other integral constant values can be used instead: const nint i = (nint)42;.

nint sabitler [ int.MinValue , int.MaxValue ] aralığındadır.nint constants are in the range [ int.MinValue, int.MaxValue ].

nuint sabitler [ uint.MinValue , uint.MaxValue ] aralığındadır.nuint constants are in the range [ uint.MinValue, uint.MaxValue ].

Veya üzerinde hiçbir alan yok, diğeri dışında, MinValue MaxValue nint nuint nuint.MinValue Bu değerler sabitler olarak yayınlanamaz.There are no MinValue or MaxValue fields on nint or nuint because, other than nuint.MinValue, those values cannot be emitted as constants.

Sabit katlama, {,, + - ~ } ve ikili işleçler {,,,,,,, + - * / % == != < , <= , > , >= , & , | , ^ , << , >> } için desteklenir.Constant folding is supported for all unary operators { +, -, ~ } and binary operators { +, -, *, /, %, ==, !=, <, <=, >, >=, &, |, ^, <<, >> }. Sabit katlama işlemleri, Int32 UInt32 derleyici platformundan bağımsız olarak tutarlı davranış için yerel olarak değil, ve işlenenleri ile değerlendirilir.Constant folding operations are evaluated with Int32 and UInt32 operands rather than native ints for consistent behavior regardless of compiler platform. İşlem, 32 bitlik bir sabit değer ile sonuçlanırsa, derleme zamanında sabit katlama yapılır.If the operation results in a constant value in 32-bits, constant folding is performed at compile-time. Aksi takdirde, işlem çalışma zamanında yürütülür ve sabit kabul edilmez.Otherwise the operation is executed at runtime and not considered a constant.

DönüşümlerConversions

Ve arasında ve arasında bir kimlik dönüştürmesi vardır nint IntPtr nuint UIntPtr .There is an identity conversion between nint and IntPtr, and between nuint and UIntPtr. Yerel ve temel türler tarafından farklı bileşik türler arasında bir kimlik dönüştürmesi vardır: diziler, Nullable<> , oluşturulmuş türler ve tanımlama grupları.There is an identity conversion between compound types that differ by native ints and underlying types only: arrays, Nullable<>, constructed types, and tuples.

Aşağıdaki tablolar özel türler arasındaki dönüşümleri kapsar.The tables below cover the conversions between special types. (Her dönüştürme için Il, unchecked farklıysa ve bağlamların çeşitlemelerini içerir checked .)(The IL for each conversion includes the variants for unchecked and checked contexts if different.)

Öğesinden A öğesine dönüştürme Nullable<B> :Conversion from A to Nullable<B> is:

• ' den ' a bir kimlik dönüştürmesi veya örtülü dönüşüm varsa örtük olarak null yapılabilir dönüştürme A B .an implicit nullable conversion if there is an identity conversion or implicit conversion from A to B;
• öğesinden açık bir dönüştürme varsa, açık bir null yapılabilir dönüştürme A B .an explicit nullable conversion if there is an explicit conversion from A to B;
• Aksi takdirde geçersiz.otherwise invalid.

Öğesinden Nullable<A> öğesine dönüştürme B :Conversion from Nullable<A> to B is:

• ' den ' a bir kimlik dönüştürmesi veya örtük ya da açık sayısal dönüştürme varsa, açık bir null yapılabilir dönüştürme A B .an explicit nullable conversion if there is an identity conversion or implicit or explicit numeric conversion from A to B;
• Aksi takdirde geçersiz.otherwise invalid.

Öğesinden Nullable<A> öğesine dönüştürme Nullable<B> :Conversion from Nullable<A> to Nullable<B> is:

• ' den ' a bir kimlik dönüştürmesi varsa, bir kimlik dönüştürme işlemi A B .an identity conversion if there is an identity conversion from A to B;
• öğesinden örtük veya açık sayısal dönüştürme varsa, açık bir null yapılabilir dönüştürme A B .an explicit nullable conversion if there is an implicit or explicit numeric conversion from A to B;
• Aksi takdirde geçersiz.otherwise invalid.

İşleçlerOperators

Önceden tanımlanmış işleçler aşağıda verilmiştir.The predefined operators are as follows. Bu işleçler , en az bir işlenenin türü nint veya nuint türünde olması halinde örtük dönüştürmeler için normal kurallara göre aşırı yükleme çözümlemesi sırasında değerlendirilir.These operators are considered during overload resolution based on normal rules for implicit conversions if at least one of the operands is of type nint or nuint.

(Her bir operatör için Il, unchecked farklı durumlarda için sapmaları ve checked bağlamlarını içerir.)(The IL for each operator includes the variants for unchecked and checked contexts if different.)

Bazı ikili işleçler için, Il işleçleri ek işlenen türlerini destekler (bkz. ECMA-335 III. 1,5 işlenen türü tablosu).For some binary operators, the IL operators support additional operand types (see ECMA-335 III.1.5 Operand type table). Ancak C# tarafından desteklenen işlenen türleri kümesi, basitlik ve dil içindeki var olan işleçlerle tutarlılık için sınırlıdır.But the set of operand types supported by C# is limited for simplicity and for consistency with existing operators in the language.

Bağımsız değişkenlerin ve dönüş türlerinin desteklendiği, yükseltilmemiş sürümleri nint? nuint? .Lifted versions of the operators, where the arguments and return types are nint? and nuint?, are supported.

Ya da yerel noktaları olan bileşik atama işlemleri x op= y x y , önceden tanımlanmış işleçlere sahip diğer ilkel türlerle aynı kuralları izler.Compound assignment operations x op= y where x or y are native ints follow the same rules as with other primitive types with pre-defined operators. Özellikle ifadesi, x = (T)(x op y) T türü olduğu x ve nerede x yalnızca bir kez değerlendirilen olarak bağlanır.Specifically the expression is bound as x = (T)(x op y) where T is the type of x and where x is only evaluated once.

SHIFT işleçleri, sizeof(nint) 4 ise ve 8 bit ise, 5 bite kaydırma için bit sayısını maskelemelidir sizeof(nint) .The shift operators should mask the number of bits to shift - to 5 bits if sizeof(nint) is 4, and to 6 bits if sizeof(nint) is 8. (bkz. C# belirtiminde Shift işleçleri ).(see shift operators in C# spec).

C# 9 derleyicisi, önceki bir dil sürümü ile derlerken, önceden tanımlanmış yerel tamsayı işleçlerine hata bağlamayı bildirir, ancak yerel tamsayılarla ve yerel tamsayılara önceden tanımlanmış dönüşümler kullanılmasına izin verir.The C#9 compiler will report errors binding to predefined native integer operators when compiling with an earlier language version, but will allow use of predefined conversions to and from native integers.

csc -langversion:9 -t:library A.cs

public class A
{
    public static nint F;
}

csc -langversion:8 -r:A.dll B.cs

class B : A
{
    static void Main()
    {
        F = F + 1; // error: nint operator+ not available with -langversion:8
        F = (System.IntPtr)F + 1; // ok
    }
}

DinamikDynamic

Dönüştürmeler ve işleçler derleyici tarafından birleştirilmiştir ve temeldeki ve türlerin bir parçası değildir IntPtr UIntPtr .The conversions and operators are synthesized by the compiler and are not part of the underlying IntPtr and UIntPtr types. Sonuç olarak, bu dönüşümler ve işleçler için çalışma zamanı Ciltçi 'de kullanılamaz dynamic .As a result those conversions and operators are not available from the runtime binder for dynamic.

nint x = 2;
nint y = x + x; // ok
dynamic d = x;
nint z = d + x; // RuntimeBinderException: '+' cannot be applied 'System.IntPtr' and 'System.IntPtr'

Tür üyeleriType members

Ya da için yalnızca nint nuint parametre-Less Oluşturucu.The only constructor for nint or nuint is the parameter-less constructor.

Ve ' nin aşağıdaki üyeleri, System.IntPtr System.UIntPtr veya ' den açıkça dışarıda bırakılır nint nuint :The following members of System.IntPtr and System.UIntPtr are explicitly excluded from nint or nuint:

// constructors
// arithmetic operators
// implicit and explicit conversions
public static readonly IntPtr Zero; // use 0 instead
public static int Size { get; }     // use sizeof() instead
public static IntPtr Add(IntPtr pointer, int offset);
public static IntPtr Subtract(IntPtr pointer, int offset);
public int ToInt32();
public long ToInt64();
public void* ToPointer();

Ve ' nin kalan üyeleri, System.IntPtr System.UIntPtr ve ' de örtülü olarak dahil edilmiştir nint nuint .The remaining members of System.IntPtr and System.UIntPtr are implicitly included in nint and nuint. .NET Framework 4.7.2 için:For .NET Framework 4.7.2:

public override bool Equals(object obj);
public override int GetHashCode();
public override string ToString();
public string ToString(string format);

Ve tarafından uygulanan System.IntPtr arabirimler System.UIntPtr nint nuint , ilgili yerel tamsayı türleri tarafından değiştirildikleri temeldeki türlerin oluşumlarıyla örtülü olarak ve içine dahil edilmiştir.Interfaces implemented by System.IntPtr and System.UIntPtr are implicitly included in nint and nuint, with occurrences of the underlying types replaced by the corresponding native integer types. Öğesini IntPtr uyguluyorsa ISerializable, IEquatable<IntPtr>, IComparable<IntPtr> , örnek için nint uygular ISerializable, IEquatable<nint>, IComparable<nint> .For instance if IntPtr implements ISerializable, IEquatable<IntPtr>, IComparable<IntPtr>, then nint implements ISerializable, IEquatable<nint>, IComparable<nint>.

Geçersiz kılma, gizleme ve uygulamaOverriding, hiding, and implementing

nint ve ve System.IntPtr nuint ve System.UIntPtr , geçersiz kılma, gizleme ve uygulama için eşdeğer olarak kabul edilir.nint and System.IntPtr, and nuint and System.UIntPtr, are considered equivalent for overriding, hiding, and implementing.

Aşırı Yüklemeler, ve nint ve System.IntPtr nuint ve System.UIntPtr tek başına farklı olamaz.Overloads cannot differ by nint and System.IntPtr, and nuint and System.UIntPtr, alone. Geçersiz kılmalar ve uygulamalar, nint System.IntPtr tek başına ve, veya ile farklı olabilir nuint System.UIntPtr .Overrides and implementations may differ by nint and System.IntPtr, or nuint and System.UIntPtr, alone. Yöntemler, ve ile farklı diğer yöntemleri nint ve System.IntPtr nuint System.UIntPtr tek başına öğesini gizler.Methods hide other methods that differ by nint and System.IntPtr, or nuint and System.UIntPtr, alone.

ÇeşitliMiscellaneous

nint ve nuint dizi dizinleri olarak kullanılan ifadeler dönüştürme olmadan yayılır.nint and nuint expressions used as array indices are emitted without conversion.

static object GetItem(object[] array, nint index)
{
    return array[index]; // ok
}

nint ve nuint , temel tür olarak kullanılabilir enum .nint and nuint can be used as an enum base type.

enum E : nint // ok
{
}

Okuma ve yazma işlemleri nint , nuint ,, ve temel türü için atomik bir enum tür nint nuint .Reads and writes are atomic for types nint, nuint, and enum with base type nint or nuint.

Alanlar volatile , ve türleri için işaretlenebilir nint nuint .Fields may be marked volatile for types nint and nuint. ECMA-334 15.5.4, enum temel tür ile birlikte dahil System.IntPtr değildir System.UIntPtr .ECMA-334 15.5.4 does not include enum with base type System.IntPtr or System.UIntPtr however.

default(nint) ve ile new nint() eşdeğerdir (nint)0 .default(nint) and new nint() are equivalent to (nint)0.

typeof(nint), typeof(IntPtr) değeridir.typeof(nint) is typeof(IntPtr).

sizeof(nint) desteklenir, ancak güvenli olmayan bir bağlamda derleme gerektirir (olduğu gibi sizeof(IntPtr) ).sizeof(nint) is supported but requires compiling in an unsafe context (as does sizeof(IntPtr)). Değer, bir derleme zamanı sabiti değil.The value is not a compile-time constant. sizeof(nint) yerine uygulandı sizeof(IntPtr) IntPtr.Size .sizeof(nint) is implemented as sizeof(IntPtr) rather than IntPtr.Size.

Veya içeren tür başvuruları için derleyici tanılaması veya nint nuint nint nuint IntPtr UIntPtr .Compiler diagnostics for type references involving nint or nuint report nint or nuint rather than IntPtr or UIntPtr.

Meta veriMetadata

nint ve nuint meta verilerde ve olarak temsil System.IntPtr edilir System.UIntPtr .nint and nuint are represented in metadata as System.IntPtr and System.UIntPtr.

nint nuint System.Runtime.CompilerServices.NativeIntegerAttribute Tür başvurusunun hangi bölümlerinin yerel olarak olduğunu belirtmek için, içeren veya ile birlikte bulunan tür başvuruları.Type references that include nint or nuint are emitted with a System.Runtime.CompilerServices.NativeIntegerAttribute to indicate which parts of the type reference are native ints.

namespace System.Runtime.CompilerServices
{
    [AttributeUsage(
        AttributeTargets.Class |
        AttributeTargets.Event |
        AttributeTargets.Field |
        AttributeTargets.GenericParameter |
        AttributeTargets.Parameter |
        AttributeTargets.Property |
        AttributeTargets.ReturnValue,
        AllowMultiple = false,
        Inherited = false)]
    public sealed class NativeIntegerAttribute : Attribute
    {
        public NativeIntegerAttribute()
        {
            TransformFlags = new[] { true };
        }
        public NativeIntegerAttribute(bool[] flags)
        {
            TransformFlags = flags;
        }
        public readonly bool[] TransformFlags;
    }
}

İle tür başvurularının kodlaması NativeIntegerAttribute NativeIntegerAttribute.MDiçinde ele alınmıştır.The encoding of type references with NativeIntegerAttribute is covered in NativeIntegerAttribute.md.

AlternatiflerAlternatives

Yukarıdaki "tür ERASURE" yaklaşımına bir alternatif olarak yeni türler tanıtılmalıdır: System.NativeInt ve System.NativeUInt .An alternative to the "type erasure" approach above is to introduce new types: System.NativeInt and System.NativeUInt.

public readonly struct NativeInt
{
    public IntPtr Value;
}

Ayrı türler öğesinden farklı aşırı yükleme ve IntPtr farklı ayrıştırmaya izin verir ToString() .Distinct types would allow overloading distinct from IntPtr and would allow distinct parsing and ToString(). Ancak, CLR 'nin bu türleri verimli bir şekilde işlemesi için daha fazla iş vardır.But there would be more work for the CLR to handle these types efficiently which defeats the primary purpose of the feature - efficiency. Ve kullanan var olan yerel tamsayı kodu ile birlikte çalışma IntPtr daha zor olacaktır.And interop with existing native int code that uses IntPtr would be more difficult.

Diğer bir seçenek de çerçevede daha fazla yerel int desteği eklemektir, IntPtr ancak belirli bir derleyici desteği yoktur.Another alternative is to add more native int support for IntPtr in the framework but without any specific compiler support. Tüm yeni dönüştürmeler ve aritmetik işlemler derleyici tarafından otomatik olarak desteklenir.Any new conversions and arithmetic operations would be supported by the compiler automatically. Ancak dil anahtar sözcükler, sabitler veya checked işlemler sağlamaz.But the language would not provide keywords, constants, or checked operations.

Tasarım toplantılarıDesign meetings

• https://github.com/dotnet/csharplang/blob/master/meetings/2017/LDM-2017-05-26.md
• https://github.com/dotnet/csharplang/blob/master/meetings/2017/LDM-2017-06-13.md
• https://github.com/dotnet/csharplang/blob/master/meetings/2017/LDM-2017-07-05.md#native-int-and-intptr-operators
• https://github.com/dotnet/csharplang/blob/master/meetings/2019/LDM-2019-10-23.md
• https://github.com/dotnet/csharplang/blob/master/meetings/2020/LDM-2020-03-25.md