Indexadores de extensão

Problema do especialista: 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 maneira (em relação a propostas/csharp-14.0/extensions.md):

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

Assim como os indexadores comuns, os indexadores de extensão não têm identificador e são identificados pela lista de parâmetros. Os indexadores de extensão podem usar o conjunto completo de recursos que os indexadores comuns dão suporte hoje (corpos do acessador, membros aptos à expressão, acessadores de retorno de ref, scoped parâmetros, atributos etc.).

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

As restrições existentes aos membros da extensão continuam a ser aplicadas: indexadores dentro de uma declaração de extensão não podem especificarabstract, virtual, override, new, sealed, partialprotected (ou qualquer um dos modificadores de acessibilidade relacionados) ou init acessadores.

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

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

A regra de inferência de membro de extensão existente ainda se aplica: para cada membro de extensão não método, todos os parâmetros de tipo de 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 em metadados, mas seu valor afeta conflitos entre membros, determina o nome da propriedade e acessadores nos metadados e é usado ao emitir [DefaultMemberAttribute] (consulte Metadados).

Consumo

Acesso de indexador

As regras no acesso ao Indexador são atualizadas: se o processamento normal do acesso do indexador não encontrar nenhum indexador aplicável, será feita uma tentativa de processar o constructo como um acesso do indexador de extensão.

1. Tente associar usando os indexadores de instância declarados (ou herdados) no tipo receptor. Se um candidato aplicável for encontrado, a resolução de sobrecarga selecionará entre esses membros da instância como hoje e será interrompida.
2. Tente associar usando os indexadores de instância implícita declarados (ou herdados) no tipo receptor. Se um candidato aplicável for encontrado, a resolução de sobrecarga selecionará entre esses membros da instância como hoje e será interrompida.
3. Tente associar como um acesso de indexador de extensão. Se esse processo encontrar um candidato aplicável, a resolução de sobrecarga selecionará entre esses membros de extensão, conforme descrito abaixo e será interrompido.
4. Tente associar como um acesso de indexador implícito de extensão. Se esse processo encontrar um candidato aplicável, a resolução de sobrecarga selecionará entre esses membros de extensão, conforme descrito abaixo e será interrompido.

Observação: a seção de acesso ao elemento manipula o caso em que um argumento tem tipo dynamic, portanto, ele nunca é processado como um acesso de indexador.

Acesso ao indexador de extensão

Os membros da extensão, incluindo indexadores de extensão, nunca são considerados quando o receptor é uma expressão base_access .

Observação: processaremos apenas um element_access como um acesso de indexador se o receptor for uma variável ou valor, portanto, os indexadores de extensão nunca serão considerados quando o receptor for um tipo.

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

Um indexador de extensão candidato é aplicável em relação ao receptor 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 em relação a uma lista de argumentos que combina o receptor E com a lista Ade argumentos.

Reutilizamos a caminhada de escopo do método de extensão: percorremos os mesmos escopos consultados para invocação do método de extensão, incluindo os escopos léxicos atuais e delimitados e using o namespace ou using static as importações.

Considerando cada escopo, por sua vez:

• Blocos de extensão em declarações de classe estática não genéricas no escopo atual são considerados.
• Os indexadores nesses blocos de extensão compõem o conjunto de candidatos.
• Os candidatos que não estã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, prosseguiremos para o próximo escopo ou não resolveremos um acesso de indexador de extensão se atingirmos o último escopo (continuaremos tentando resolver como um indexador implícito de extensão nesse caso).
• Caso contrário, a resolução de sobrecarga será aplicada ao conjunto de candidatos. Se um único melhor indexador não puder ser identificado, o acesso ao indexador de extensão será ambíguo e ocorrerá um erro de tempo de compilação.

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

Dependendo do contexto no qual ele é usado, um acesso de indexador causa invocação do get_accessor ou do set_accessor do indexador.
Se o acesso do indexador for o destino de uma atribuição, o método de implementação estático set_accessor será invocado para atribuir um novo valor.
Em todos os outros casos, o método de implementação estático 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 receptor como o primeiro argumento.

Acesso ao indexador implícito de extensão

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

1. o 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) é encontrada no tipo de receptor e
3. um indexador aplicável this[int] (ou Slice(int, int)) (instância ou extensão) é encontrado no tipo de receptor.

Outros formulários de acesso a elementos

Qualquer construção que adie a associação de acesso a elementos (acesso ou atribuições de elemento condicional nulo, atribuições de índice em inicializadores de objeto ou padrões de lista e distribuição) participa automaticamente da resolução do indexador de extensão descrita acima.

Árvores de expressão

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

Documentos XML

A sintaxe CREF permite fazer referência a um indexador de extensão e seus acessadores, bem como seus métodos de implementação.

Exemplo:

/// <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 de nível CLR que contém pelo menos um indexador, o compilador emite:

• Uma propriedade de extensão chamada Item (ou o valor fornecido por IndexerNameAttribute) com corpos acessadores que e um [ExtensionMarkerName] atributo referenciando throw NotImplementedException() o tipo de marcador de extensão apropriado.
• Métodos de implementação nomeados get_Item/set_Item na classe estática delimitada. Esses métodos anexam o parâmetro receptor à lista de parâmetros e contêm os corpos definidos pelo usuário. Eles são static e participam da 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 [DefaultMemberAttribute] , o compilador também emite qualquer tipo de agrupamento de extensão que contenha um ou mais indexadores de extensão. O atributo é MemberName igual ao nome de metadados do indexador (Item por padrão, 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 do tipo 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) => ...;
}

Problemas 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;
    }
}