11 Wzorce i dopasowywanie wzorców

11.1 Ogólne

Wzorzec jest formą składniową, która może być używana z is operatorem (§12.14.12), w switch_statement (§13.8.3) i w switch_expression (§12.11) w celu wyrażenia kształtu danych, względem których mają być porównywane dane przychodzące. Wzorce mogą być rekursywne, dzięki czemu części danych mogą być dopasowane do wzorców podrzędnych.

Wzorzec jest testowany względem wartości w wielu kontekstach:

W instrukcji switch wzorzec etykiety wielkości liter jest testowany względem wyrażenia instrukcji switch.
W operatorze is-pattern wzorzec po prawej stronie jest testowany względem wyrażenia po lewej stronie.
W wyrażeniu przełącznika wzorzecswitch_expression_arm jest testowany względem wyrażenia po lewej stronie wyrażenia przełącznika.
W kontekstach zagnieżdżonych wzorzec jest testowany względem wartości pobranych z właściwości, pól lub indeksowanych z innych wartości wejściowych, w zależności od formularza wzorca.

Wartość, względem której testowany jest wzorzec, jest nazywana wartością wejściową wzorca.

Formularze wzorca 11.2

11.2.1 Ogólne

Wzorzec może mieć jedną z następujących form:

pattern
    : declaration_pattern
    | constant_pattern
    | var_pattern
    | positional_pattern
    | property_pattern
    | discard_pattern
    ;

Niektóre wzorcemogą spowodować deklarację zmiennej lokalnej.

Każdy formularz wzorca definiuje zestaw typów dla wartości wejściowych, do których można zastosować wzorzec. Wzorzec P ma typów, których wartości mogą być zgodne ze wzorcem. Jest to błąd czasu kompilacji, jeśli wzorzec pojawia się w programie, aby dopasować wartość wejściową wzorca P (§11.1) typu T , jeśli P nie ma zastosowania do T.

Przykład: Poniższy przykład generuje błąd czasu kompilacji, ponieważ typ czasu kompilacji v to TextReader. Zmienna typu TextReader nigdy nie może mieć wartości zgodnej z elementem string:
TextReader v = Console.In; // compile-time type of 'v' is 'TextReader'
if (v is string) // compile-time error
{
    // code assuming v is a string
}
Jednak następujące polecenie nie generuje błędu czasu kompilacji, ponieważ typ v czasu kompilacji to object. Zmienna typu object może mieć wartość zgodną z odwołaniem:string
object v = Console.In;
if (v is string s)
{
    // code assuming v is a string
}
przykład końcowy

Każdy formularz wzorca definiuje zestaw wartości, dla których wzorzec pasuje do wartości w czasie wykonywania.

Kolejność oceny operacji i skutków ubocznych podczas dopasowywania wzorca (wywołania do , dostęp do Deconstructwłaściwości i wywołania metod w programie System.ITuple) nie jest określony.

Wzorzec deklaracji 11.2.2

Declaration_pattern służy do testowania, czy wartość ma dany typ i, jeśli test zakończy się pomyślnie, opcjonalnie podaj wartość w zmiennej tego typu.

declaration_pattern
    : type simple_designation
    ;
simple_designation
    : discard_designation
    | single_variable_designation
    ;
discard_designation
    : '_'
    ;
single_variable_designation
    : identifier
    ;

Simple_designation z tokenem _ uznaje się za discard_designation, a nie single_variable_designation.

Typ środowiska uruchomieniowego wartości jest testowany względem typu we wzorcu przy użyciu tych samych reguł określonych w operatorze is-type (§12.14.12.1). Jeśli test zakończy się pomyślnie, wzorzec pasuje do tej wartości. Jest to błąd czasu kompilacji, jeśli typ jest typem wartości dopuszczalnej wartości null (§8.3.12) lub typem odwołania dopuszczanym do wartości null (§8.9.3). Ten formularz wzorca nigdy nie pasuje do null wartości.

Uwaga: wyrażenie e is T typu is i wzorzec e is T _ deklaracji są równoważne, gdy T nie jest typem dopuszczalnym wartości null. notatka końcowa

Biorąc pod uwagę wartość wejściową wzorca (§11.1) e, jeśli simple_designation jest discard_designation, oznacza odrzucenie (§9.2.9.2), a wartość e nie jest powiązana z niczym. (Chociaż zadeklarowana zmienna o nazwie _ może być w tym momencie w zakresie, ta nazwana zmienna nie jest widoczna w tym kontekście). W przeciwnym razie, jeśli simple_designation jest single_variable_designation, wprowadzana jest zmienna lokalna (§9.2.9) danego typu o nazwie podanego identyfikatora. Ta zmienna lokalna ma przypisaną wartość wartości wejściowej wzorca, gdy wzorzec jest zgodny z wartością.

Niektóre kombinacje statycznego typu wartości wejściowej wzorca i danego typu są uznawane za niezgodne i powodują błąd czasu kompilacji. Wartość typu E statycznego jest zgodna ze wzorcem zgodnym z typemT, jeśli istnieje konwersja tożsamości, niejawna lub jawna konwersja odwołań, konwersja boksu lub konwersja E rozpaku z na T, lub jeśli E albo T jest typem otwartym (§8.4.3). Wzorzec deklaracji nazewnictwa typu T ma zastosowanie do.

Uwaga: Obsługa typów otwierania może być najbardziej przydatna podczas sprawdzania typów, które mogą być typami struktur lub klas, i należy unikać tworzenia pól. notatka końcowa

Przykład: Wzorzec deklaracji jest przydatny do wykonywania testów typu czasu wykonywania typów odwołań i zastępuje idiom
var v = expr as Type;
if (v != null) { /* code using v */ }
z nieco bardziej zwięzłym
if (expr is Type v) { /* code using v */ }
przykład końcowy

Przykład: Wzorzec deklaracji może służyć do testowania wartości typów dopuszczanych do wartości null: wartość typu Nullable<T> (lub pole) Tpasuje do wzorca T2 id typu, jeśli wartość jest inna niż null i T2 ma Twartość , lub jakiś podstawowy typ lub interfejs T. Na przykład w fragmentie kodu
int? x = 3;
if (x is int v) { /* code using v */ }
Warunek instrukcji if jest true w czasie wykonywania, a zmienna v przechowuje wartość 3 typu int wewnątrz bloku. Po zablokowaniu zmienna v znajduje się w zakresie, ale na pewno nie jest przypisana. przykład końcowy

Wzorzec stałej 11.2.3

Constant_pattern służy do testowania wartości wartości wejściowej wzorca (§11.1) względem danej wartości stałej.

constant_pattern
    : constant_expression
    ;

Wzorzec stałej ma P typu, jeśli istnieje niejawna konwersja z wyrażenia stałego T na typ P.T

W przypadku wzorca Pstałego jego przekonwertowana wartość to

jeśli typ wartości wejściowej wzorca jest typem całkowitym lub typem wyliczeniowym, stała wartość wzorca przekonwertowana na ten typ; inaczej
jeśli typ wartości wejściowej wzorca jest wersją typu całkowitego dopuszczaną do wartości null lub typem wyliczenia, stała wartość wzorca przekonwertowana na jego typ bazowy; inaczej
wartość stałej wartości wzorca.

Biorąc pod uwagę wartość wejściową wzorca e i stały wzorzec P z przekonwertowaną wartością v,

jeśli e ma typ całkowity lub typ wyliczeniowy, albo możliwą do wartości null formę jednego z nich, a v ma typ całkowity, wzorzec P pasuje do wartości e, jeśli wynik wyrażenia e == v to true; w przeciwnym razie
wzorzec Ppasuje do wartości e , jeśli object.Equals(e, v) zwraca wartość true.

Przykład: instrukcja switch w poniższej metodzie używa pięciu wzorców stałych w etykietach przypadków.

static decimal GetGroupTicketPrice(int visitorCount)
{
    switch (visitorCount) 
    {
        case 1: return 12.0m;
        case 2: return 20.0m;
        case 3: return 27.0m;
        case 4: return 32.0m;
        case 0: return 0.0m;
        default: throw new ArgumentException(...);
    }
}

przykład końcowy

Wzorzec wariancja 11.2.4

Var_pattern pasuje do każdej wartości. Oznacza to, że operacja dopasowywania wzorca z var_pattern zawsze kończy się powodzeniem.

Var_pattern ma zastosowanie do każdego typu.

var_pattern
    : 'var' designation
    ;
designation
    : simple_designation
    | tuple_designation
    ;
tuple_designation
    : '(' designations? ')'
    ;
designations
    : designation (',' designation)*
    ;

Biorąc pod uwagę wartość wejściową wzorca (§11.1) e, jeśli oznaczenie jest discard_designation, oznacza odrzucenie (§9.2.9.2), a wartość e nie jest powiązana z niczym. (Mimo że zadeklarowana zmienna o tej nazwie może znajdować się w zakresie w tym momencie, ta nazwana zmienna nie jest widoczna w tym kontekście). W przeciwnym razie, jeśli oznaczenie jest single_variable_designation, w czasie wykonywania wartość e jest powiązana z nowo wprowadzoną zmienną lokalną (§9.2.9) tej nazwy, której typem jest typ statyczny e, a wartość wejściowa wzorca jest przypisana do tej zmiennej lokalnej.

Jest to błąd, jeśli nazwa var będzie wiązać się z typem , w którym jest używana var_pattern .

Jeśli oznaczenie jest tuple_designation, wzorzec jest odpowiednikiem positional_pattern (§11.2.5) oznaczenia formularza(var, ... ) gdzie oznaczenias znajdują się w tuple_designation. Na przykład wzorzec jest odpowiednikiem (var x, (var y, var z)).var (x, (y, z))

11.2.5 Wzorzec pozycyjny

Positional_pattern sprawdza, czy wartość wejściowa nie nulljest , wywołuje odpowiednią Deconstruct metodę (§12.7) i wykonuje dalsze dopasowywanie wzorca dla wartości wynikowych. Obsługuje również składnię wzorca przypominającą krotkę (bez podanego typu), gdy typ wartości wejściowej jest taki sam jak typ zawierający Deconstruct, lub jeśli typ wartości wejściowej jest typem krotki, lub jeśli typ wartości wejściowej to object lub System.ITuple typ środowiska uruchomieniowego wyrażenia implementuje System.ITuplewartość .

positional_pattern
    : type? '(' subpatterns? ')' property_subpattern? simple_designation?
    ;
subpatterns
    : subpattern (',' subpattern)*
    ;
subpattern
    : pattern
    | identifier ':' pattern
    ;

Biorąc pod uwagę dopasowanie wartości wejściowej dopodwzorców)typu( wzorca, metoda jest wybierana przez wyszukiwanie w typie dostępnych deklaracji Deconstruct i wybranie jednej z nich przy użyciu tych samych reguł co dla deklaracji dekonstrukcji. Jest to błąd, jeśli positional_pattern pomija typ, ma jeden podwzorca bez identyfikatora, nie ma property_subpattern i nie ma simple_designation. To rozbicie między constant_pattern , który jest nawiasem i positional_pattern. Aby wyodrębnić wartości, które mają być zgodne z wzorcami na liście,

Jeśli typ zostanie pominięty, a typ wyrażenia wejściowego jest typem krotki, liczba podwzorców musi być taka sama jak kardynalność krotki. Każdy element krotki jest zgodny z odpowiednim podwzorcą, a dopasowanie powiedzie się, jeśli wszystkie te elementy powiedzą się. Jeśli jakikolwiek podwzorca ma identyfikator, nazwa to element krotki w odpowiedniej pozycji w typie krotki.
W przeciwnym razie, jeśli odpowiedni Deconstruct element istnieje jako element członkowski typu, jest to błąd czasu kompilacji, jeśli typ wartości wejściowej nie jest zgodny ze wzorcem z typem. W czasie wykonywania wartość wejściowa jest testowana względem typu. Jeśli to się nie powiedzie, dopasowanie wzorca pozycyjnego zakończy się niepowodzeniem. Jeśli to się powiedzie, wartość wejściowa jest konwertowana na ten typ i Deconstruct jest wywoływana ze świeżymi zmiennymi wygenerowanymi przez kompilator w celu odbierania parametrów wyjściowych. Każda odebrana wartość jest zgodna z odpowiednim podwzorcą, a dopasowanie powiedzie się, jeśli wszystkie te elementy powiedzą się. Jeśli jakikolwiek podwzorca ma identyfikator, nazwa parametru Deconstructw odpowiedniej pozycji .
W przeciwnym razie, jeśli typ zostanie pominięty, a wartość wejściowa jest typu object lub jakiś typ, który można przekonwertować na System.ITuple przez niejawną konwersję odwołania, a żaden identyfikator nie pojawia się wśród podwzorców, dopasowanie używa System.ITuplemetody .
W przeciwnym razie wzorzec jest błędem czasu kompilacji.

Kolejność dopasowania podwzorców w czasie wykonywania jest nieokreślona, a dopasowanie nie powiodło się, może nie być zgodne ze wszystkimi podwzorcami.

Przykład: w tym miejscu dekonstrukujemy wynik wyrażenia i dopasujemy wartości wynikowe do odpowiednich zagnieżdżonych wzorców:

static string Classify(Point point) => point switch
{
    (0, 0) => "Origin",
    (1, 0) => "positive X basis end",
    (0, 1) => "positive Y basis end",
    _ => "Just a point",
};

public readonly struct Point
{
    public int X { get; }
    public int Y { get; }
    public Point(int x, int y) => (X, Y) = (x, y);
    public void Deconstruct(out int x, out int y) => (x, y) = (X, Y);
}

przykład końcowy

Przykład: Nazwy elementów krotki i parametrów Deconstruct mogą być używane w wzorcu pozycyjnym w następujący sposób:
var numbers = new List<int> { 10, 20, 30 };
if (SumAndCount(numbers) is (Sum: var sum, Count: var count))
{
    Console.WriteLine($"Sum of [{string.Join(" ", numbers)}] is {sum}");
}

static (double Sum, int Count) SumAndCount(IEnumerable<int> numbers)
{
    int sum = 0;
    int count = 0;
    foreach (int number in numbers)
    {
        sum += number;
        count++;
    }
    return (sum, count);
}
Generowane dane wyjściowe są następujące:
Sum of [10 20 30] is 60
przykład końcowy

Wzorzec właściwości 11.2.6

Property_pattern sprawdza, czy wartość wejściowa nie nulljest wartością , a rekursywnie pasuje do wartości wyodrębnionych przez użycie dostępnych właściwości lub pól.

property_pattern
    : type? property_subpattern simple_designation?
    ;
property_subpattern
    : '{' '}'
    | '{' subpatterns ','? '}'
    ;

Jest to błąd, jeśli jakikolwiek podwzorcaproperty_pattern nie zawiera identyfikatora.

Jest to błąd czasu kompilacji, jeśli typ jest typem wartości dopuszczalnej wartości null (§8.3.12) lub typem odwołania dopuszczanym do wartości null (§8.9.3).

Uwaga: Wzorzec sprawdzania wartości null wypada ze wzorca właściwości trywialnych. Aby sprawdzić, czy ciąg s jest inny niż null, można napisać dowolny z następujących formularzy:
#nullable enable
string s = "abc";
if (s is object o) ...  // o is of type object
if (s is string x1) ... // x1 is of type string
if (s is {} x2) ...     // x2 is of type string
if (s is {}) ...
notatka końcowa Biorąc pod uwagę dopasowanie wyrażenia e do typu{ wzorcaproperty_pattern_list}, jest to błąd czasu kompilacji, jeśli wyrażenie e nie jest zgodne ze wzorcem z typemT wyznaczonym przez typ. Jeśli typ jest nieobecny, przyjmuje się, że typ jest statycznym typem e. Każdy z identyfikatorów wyświetlanych po lewej stronie jego property_pattern_list wyznacza dostępną czytelną właściwość lub pole T. Jeśli simple_designationproperty_pattern jest obecny, deklaruje zmienną wzorca typu T.

W czasie wykonywania wyrażenie jest testowane względem języka T. Jeśli to się nie powiedzie, dopasowanie wzorca właściwości zakończy się niepowodzeniem, a wynikiem jest false. Jeśli to się powiedzie, każde pole lub właściwość property_subpattern jest odczytywane, a jego wartość jest dopasowywana do odpowiadającego mu wzorca. Wynik całego dopasowania jest false tylko wtedy, gdy wynik któregokolwiek z nich to false. Kolejność dopasowania podwzorców nie jest określona, a dopasowanie nie powiodło się, może nie przetestować wszystkich podwzorców w czasie wykonywania. Jeśli dopasowanie powiedzie się, a simple_designationproperty_pattern jest single_variable_designation, zadeklarowana zmienna zostanie przypisana do dopasowanej wartości.

Property_pattern może służyć do dopasowywania wzorca do typów anonimowych.

Przykład:

var o = ...;
if (o is string { Length: 5 } s) ...

przykład końcowy

Przykład: Sprawdzanie typu czasu wykonywania i deklaracja zmiennej można dodać do wzorca właściwości w następujący sposób:

Console.WriteLine(TakeFive("Hello, world!"));  // output: Hello
Console.WriteLine(TakeFive("Hi!"));            // output: Hi!
Console.WriteLine(TakeFive(new[] { '1', '2', '3', '4', '5', '6', '7' }));  // output: 12345
Console.WriteLine(TakeFive(new[] { 'a', 'b', 'c' }));  // output: abc

static string TakeFive(object input) => input switch
{
    string { Length: >= 5 } s => s.Substring(0, 5),
    string s => s,
    ICollection<char> { Count: >= 5 } symbols => new string(symbols.Take(5).ToArray()),
    ICollection<char> symbols => new string(symbols.ToArray()),
    null => throw new ArgumentNullException(nameof(input)),
    _ => throw new ArgumentException("Not supported input type."),
};

Generowane dane wyjściowe są następujące:

Hello
Hi!
12345
abc

przykład końcowy

11.2.7 Odrzuć wzorzec

Każde wyrażenie jest zgodne ze wzorcem odrzucenia, co powoduje odrzucenie wartości wyrażenia.

discard_pattern
    : '_'
    ;

Jest to błąd czasu kompilacji, aby użyć wzorca odrzucenia w relational_expression wzorca formularza relational_expressionis lub jakowzorzecswitch_label.

Uwaga: W takich przypadkach, aby dopasować dowolne wyrażenie, użyj var_pattern z odrzuceniem var _. notatka końcowa

Przykład:
Console.WriteLine(GetDiscountInPercent(DayOfWeek.Friday));
Console.WriteLine(GetDiscountInPercent(null));
Console.WriteLine(GetDiscountInPercent((DayOfWeek)10));

static decimal GetDiscountInPercent(DayOfWeek? dayOfWeek) => dayOfWeek switch
{
    DayOfWeek.Monday => 0.5m,
    DayOfWeek.Tuesday => 12.5m,
    DayOfWeek.Wednesday => 7.5m,
    DayOfWeek.Thursday => 12.5m,
    DayOfWeek.Friday => 5.0m,
    DayOfWeek.Saturday => 2.5m,
    DayOfWeek.Sunday => 2.0m,
    _ => 0.0m,
};
Generowane dane wyjściowe są następujące:
5.0
0.0
0.0
W tym miejscu wzorzec odrzucenia jest używany do obsługi null wszystkich wartości całkowitych, które nie mają odpowiedniego DayOfWeek elementu członkowskiego wyliczenia. Gwarantuje to, że switch wyrażenie obsługuje wszystkie możliwe wartości wejściowe. przykład końcowy

11.3 Podsumpcja wzorca

W instrukcji switch jest to błąd, jeśli wzorzec sprawy jest podsumowywany przez poprzedni zestaw niestrzeżonych przypadków (§13.8.3). Nieformalnie oznacza to, że każda wartość wejściowa byłaby zgodna z jedną z poprzednich przypadków. Następujące reguły definiują, kiedy zestaw wzorców subsumuje określony wzorzec:

Wzorzec Ppasuje do stałej K , jeśli specyfikacja zachowania środowiska uruchomieniowego tego wzorca jest P zgodna z Kparametrem .

Zestaw wzorców Qsubsumuje wzorzec P , jeśli którykolwiek z następujących warunków jest wstrzymany:

Pjest stałym wzorcem, a każdy z wzorców w zestawie Q będzie zgodny z Pprzekonwertowaną wartością
P jest wzorcem var, a zestaw wzorców Q jest wyczerpujący (§11.4) dla typu wartości wejściowej wzorca (§11.1), a wartość wejściowa wzorca nie jest typu dopuszczalnego wartości null lub jakiś wzorzec w Q elemecie jest zgodny nullz .
P jest wzorcem deklaracji z typem T , a zestaw wzorców Q jest wyczerpujący dla typu T (§11.4).

11.4 Wyczerpującość wzorca

Nieformalnie zestaw wzorców jest wyczerpujący dla typu, jeśli dla każdej możliwej wartości tego typu innej niż null, jakiś wzorzec w zestawie ma zastosowanie. Następujące reguły określają, kiedy zestaw wzorców jest wyczerpujący dla typu:

Zestaw wzorców Q jest wyczerpujący dla typu T , jeśli którykolwiek z następujących warunków jest wstrzymany:

T jest typem całkowitym lub wyliczeniowym albo wersją dopuszczającą wartość null jednej z tych wartości i dla każdej możliwej wartości typu bazowego Tbez wartości null, jakiś wzorzec w Q elemecie pasuje do tej wartości; lub
Wzorzec w pliku Q jest wzorcem var; lub
Wzorzec w pliku Q to wzorzec deklaracji typu D, a istnieje konwersja tożsamości, niejawna konwersja odwołania lub konwersja boksu z T na D.

Przykład:

static void M(byte b)
{
    switch (b) {
        case 0: case 1: case 2: ... // handle every specific value of byte
            break;
        // error: the pattern 'byte other' is subsumed by the (exhaustive)
        // previous cases
        case byte other: 
            break;
    }
}

przykład końcowy

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-31

Udostępnij za pomocą

11 Wzorce i dopasowywanie wzorców

11.1 Ogólne

Formularze wzorca 11.2

11.2.1 Ogólne

Wzorzec deklaracji 11.2.2

Wzorzec stałej 11.2.3

Wzorzec wariancja 11.2.4

11.2.5 Wzorzec pozycyjny

Wzorzec właściwości 11.2.6

11.2.7 Odrzuć wzorzec

11.3 Podsumpcja wzorca

11.4 Wyczerpującość wzorca

Sprzężenie zwrotne

Dodatkowe zasoby