Indexadores de extensão

Edição campeã: https://github.com/dotnet/csharplang/issues/9856

Declaração

Gramática

Os indexadores de extensão são adicionados ao conjunto de membros permitidos dentro de uma declaração de extensão estendendo a gramática da seguinte forma (relativamente a proposals/csharp-14.0/extensions.md):

extension_member_declaration
        : method_declaration
        | property_declaration
        | indexer_declaration // new
        | operator_declaration
        ;

Tal como os indexadores comuns, os indexadores de extensão não têm identificador e são identificados pela sua lista de parâmetros. Os indexadores de extensão podem usar o conjunto completo de funcionalidades que os indexadores comuns suportam atualmente (corpos de acessórios, membros com corpo de expressão, acessores que retornam ref, scoped parâmetros, atributos, etc.).

Como os indexadores são sempre membros de instância, um bloco de extensão que declara um indexador deve fornecer um parâmetro de recetor nomeado.

As restrições existentes sobre membros de extensão continuam a aplicar-se: os indexadores dentro de uma declaração de extensão não podem especificar abstract, virtual, override, newsealed, partial, , ( protected ou qualquer um dos modificadores de acessibilidade relacionados), nem init acessórios.

public static class BitExtensions
{
    extension(int i)
    {
        public bool this[int index]
        {
            get => ...;
        }
    }
}

Todas as regras do padrão C# que se aplicam aos indexadores comuns aplicam-se aos indexadores de extensão, mas os membros da extensão não têm um .this

A regra de inferibilidade existente dos membros da extensão ainda se aplica: Para cada membro de extensão que não seja o método, todos os parâmetros de tipo do seu bloco de extensão devem ser usados no conjunto combinado de parâmetros da extensão e do membro.

Atributo IndexerName

IndexerNameAttribute pode ser aplicado a um indexador de extensão. O atributo não é emitido nos metadados, mas o seu valor afeta conflitos entre membros, determina o nome da propriedade e dos acessórios nos metadados, e é usado na emissão [DefaultMemberAttribute] (ver Metadados).

Consumo

Acesso ao indexador

As regras no acesso ao indexador são atualizadas: se o processamento normal do acesso ao indexador não encontrar um indexador aplicável, faz-se uma tentativa de processar a construção como um acesso ao indexador de extensão.

1. Tente ligar usando os indexadores de instância declarados (ou herdados) no tipo de recetor. Se for encontrado um candidato aplicável, a resolução de sobrecarga seleciona entre esses membros da instância como hoje e para.
2. Tente ligar usando os indexadores implícitos de instâncias declarados (ou herdados) no tipo de recetor. Se for encontrado um candidato aplicável, a resolução de sobrecarga seleciona entre esses membros da instância como hoje e para.
3. Tente ligar como um acesso indexador de extensão. Se este processo encontrar um candidato aplicável, a resolução de sobrecarga seleciona entre esses membros de extensão conforme descrito abaixo e para.
4. Tente ligar como extensão o acesso implícito ao indexador. Se este processo encontrar um candidato aplicável, a resolução de sobrecarga seleciona entre esses membros de extensão conforme descrito abaixo e para.

Nota: a secção de acesso a elementos trata do caso em que um argumento tem tipo dynamic, pelo que nunca é processado como acesso indexador.

Acesso ao indexador de extensões

Membros de extensão, incluindo indexadores de extensão, nunca são considerados quando o recetor é uma expressão base_access .

Nota: só processamos um element_access como acesso ao indexador se o recetor for uma variável ou valor, pelo que os indexadores de extensão nunca são considerados quando o recetor é um tipo.

Dado um element_accessE[A], o objetivo é identificar um indexador de extensão.

Um indexador de extensão candidato é aplicável relativamente ao recetor E e à lista A de argumentos se uma assinatura expandida, composta pelos parâmetros de tipo do bloco de extensão e uma lista de parâmetros que combina o parâmetro de extensão com os parâmetros do indexador, for aplicável relativamente a uma lista de argumentos que combina o recetor E com a lista Ade argumentos .

Reutilizamos o método de extensão scope walk: percorremos os mesmos escopos consultados para invocação do método de extensão, incluindo os escopos lexicais atuais e anexos e using namespace ou using static importações.

Considerando cada oscilação por sua vez:

• Blocos de extensão em declarações de classe estática não genéricas no âmbito atual são considerados.
• Os indexadores nesses blocos de extensão constituem o conjunto de candidatos.
• Candidatos que não são acessíveis são removidos do conjunto.
• Os candidatos que não são aplicáveis (conforme definido acima) são removidos do conjunto.
• Se o conjunto resultante de indexadores candidatos estiver vazio, então avançamos para o próximo âmbito, ou falhamos em resolver um acesso ao indexador de extensão se chegámos ao último escopo (nesse caso, continuaremos a tentar resolver como um indexador implícito de extensão).
• Caso contrário, aplica-se resolução de sobrecarga ao conjunto candidato. Se não for possível identificar um único melhor indexador, o acesso ao indexador de extensão é ambíguo e ocorre um erro em tempo de compilação.

Usando este único melhor indexador identificado na etapa anterior, o acesso ao indexador é então processado como uma invocação estática de método.

Dependendo do contexto em que é utilizado, um acesso ao indexador provoca a invocação do get_accessor ou do set_accessor do indexador.
Se o acesso ao indexador for o alvo de uma atribuição, o método de implementação estática set_accessor é invocado para atribuir um novo valor.
Em todos os outros casos, o método de implementação estática get_accessor é invocado para obter o valor atual.
De qualquer forma, a invocação usará argumentos genéricos inferidos durante a verificação de aplicabilidade e o recetor como primeiro argumento.

Acesso implícito ao indexador de extensão

Um acesso implícito System.Index (ou System.Range) ao indexador de extensão é aplicável se:

1. A element_access tem um único argumento que é do tipo System.Index (ou System.Range), e
2. uma propriedade aplicável Length ou Count (instância ou extensão) encontra-se no tipo de recetor, e
3. Um indexador aplicável this[int] (ou Slice(int, int)) (instância ou extensão) é encontrado no tipo de recetor.

Outras formas de acesso a elementos

Qualquer construto que defere para a ligação de acesso a elementos (acesso ou atribuições de elementos nulos, atribuições de índice em inicializadores de objetos, ou padrões de lista e dispersão) participa automaticamente na resolução do indexador de extensão descrita acima.

Árvores de expressão

Indexadores de extensão não podem ser capturados em árvores de expressão.

Documentos XML

A sintaxe CREF permite referir-se a um indexador de extensão e aos seus acessores, bem como aos seus métodos de implementação.

Example:

/// <see cref="E.extension(int).this[string]"/>
/// <see cref="E.extension(int).get_Item(string)"/>
/// <see cref="E.extension(int).get_Item"/>
/// <see cref="E.extension(int).set_Item(string, int)"/>
/// <see cref="E.extension(int).set_Item"/>
/// <see cref="E.get_Item(int, string)"/>
/// <see cref="E.get_Item"/>
/// <see cref="E.set_Item(int, string, int)"/>
/// <see cref="E.set_Item"/>
public static class E
{
    extension(int i)
    {
        /// <summary></summary>
        public int this[string s]
        {
            get => throw null;
            set => throw null;
        }
    }
}

Metadata

Os indexadores de extensão seguem o mesmo modelo de redução que as propriedades de extensão. Para cada tipo de agrupamento de extensão ao nível de CLR que contenha pelo menos um indexador, o compilador emite:

• Uma propriedade de extensão nomeada Item (ou o valor fornecido por IndexerNameAttribute) com corpos de acesso que throw NotImplementedException() e um [ExtensionMarkerName] atributo que referencia o tipo de marcador de extensão apropriado.
• Métodos de implementação nomeados get_Item/set_Item na classe estática que o envolve. Estes métodos antepõem o parâmetro receptor à lista de parâmetros e contêm os corpos definidos pelo utilizador. São static e participam na resolução de sobrecarga da mesma forma que os métodos de implementação para propriedades de extensão.

Para espelhar o comportamento dos indexadores comuns, o compilador também emite [DefaultMemberAttribute] em qualquer tipo de agrupamento de extensão que contenha um ou mais indexadores de extensão. O atributo MemberName é igual ao nome dos metadados do indexador (Item por defeito, ou o valor de IndexerNameAttribute).

Example

Código-fonte:

static class BitExtensions
{
    extension<T>(T t)
    {
        public bool this[int index]
        {
            get => ...;
            set => ...;
        }
    }
}

Metadados emitidos (simplificados para sintaxe semelhante à de C#):

[Extension]
static class BitExtensions
{
    [Extension, SpecialName, DefaultMember("Item")]
    public sealed class <G>$T0 // grouping type
    {
        [SpecialName]
        public static class <M>$T_t // marker type
        {
            [SpecialName]
            public static void <Extension>$(T t) { } // marker method
        }

        [ExtensionMarkerName("<M>$T_t")]
        public bool this[int index] // extension indexer
        {
            get => throw new NotImplementedException();
            set => throw new NotImplementedException();
        }
    }

    // accessor implementation methods
    public static bool get_Item<T>(T t, int index) => ...;
    public static void set_Item<T>(T t, int index, bool value) => ...;
}

Questões em aberto

int i = 0;
i[42, null] = new object(); // fails inference
E.set_Item(i, 42, null, new object()); // infer `E.set_Item<object>`

public static class E
{
    extension<T>(int i)
    {
        public T this[int j, T t] { set { } }
    }
}

#nullable enable

int i = 0;
i[new object()] = null; // infer `E.extension<object!>` and warn on conversion of null literal to `object!`
E.set_Item(i, new object(), null); // infer `E.set_Item<object?>`

public static class E
{
    extension<T>(int i)
    {
        public T this[T t] { set { } }
    }
}

C c = new C();
_ = c[..]; // Cannot apply indexing with [] to an expression of type 'C'

class C
{
    public int Length => 0;
}

static class E
{
    public static C Slice(this C c, int i, int j) => null!;
}

C c = new C();
var x1 = c[^1];
var x2 = c[1..];

if (c is [.., var y1]) { }
if (c is [_, .. var y2]) { }

class C { }

static class E
{
  extension(C c)
  {
    object this[System.Index] => ...;
    C this[System.Range] => ...;
    int Length => ...;
  }
}

C c = new C();
if (c is [var y1, .. var y2]) { }

class C
{
  C Slice(int i, int j) => ...;
}

static class E
{
  extension(C c)
  {
    object this[System.Index] => ...;
    int Length => ...;
  }
}

C c = new C();
_ = c[^1];

class C
{
  public int Length => ...;
  public int this[int i] => ...;
}

static class E
{
  extension(C c)
  {
    public int this[System.Index i] => ...;
  }
}

_ = c[1..^1];

static class E
{
  extension(C c)
  {
    public int Length => 3;
  }
  public static C Slice(this C c, int i, int j) => ...;
}

C c = new C();
int[] i = [0, .. c]; // Uses Length, if available, to allocate the right size

int[] i = ...;
_ = i[new C()];

public static class E
{
    extension(int[] i)
    {
        public int this[C c] => throw null;
    }
}

string s = "...;
_ = s[new C()];

public static class E
{
    extension(int[] i)
    {
        public int this[C c] => throw null;
    }
}