Partilhar via

Anotando Estruturas e Classes

Você pode anotar membros de estrutura e classe usando anotações que agem como invariantes — presume-se que sejam verdadeiras em qualquer chamada de função ou entrada/saída de função que inclua a estrutura que as encerra como um parâmetro ou resultado.

As Anotações de Estruturas (Struct) e Classes (Class)

  • _Field_range_(low, high)

    O campo está no intervalo (inclusive) de low até high. Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= high) aplicado ao objeto anotado usando as condições pré ou pós apropriadas.

  • _Field_size_(size), _Field_size_opt_(size), _Field_size_bytes_(size), _Field_size_bytes_opt_(size)

    Um campo que tem um tamanho gravável em elementos (ou bytes), conforme especificado por size.

  • _Field_size_part_(size, count), _Field_size_part_opt_(size, count), _Field_size_bytes_part_(size, count), _Field_size_bytes_part_opt_(size, count)

    Um campo com um tamanho em elementos (ou bytes) que pode ser gravado conforme especificado por size, e aqueles elementos (bytes) cujo tamanho está legível por count.

  • _Field_size_full_(size), _Field_size_full_opt_(size), _Field_size_bytes_full_(size), _Field_size_bytes_full_opt_(size)

    Um campo que tem tamanho legível e gravável em elementos (ou bytes), conforme especificado por size.

  • _Field_z_

    Um campo que tem uma cadeia de caracteres terminada em nulo.

  • _Struct_size_bytes_(size)

    Aplica-se à declaração de struct ou class. Indica que um objeto válido desse tipo pode ser maior do que o tipo declarado, com o número de bytes sendo especificado por size. Por exemplo:

    typedef _Struct_size_bytes_(nSize)
struct MyStruct {
    size_t nSize;
    ...
};

    O tamanho do buffer em bytes de um parâmetro pM do tipo MyStruct * é então considerado como:

    min(pM->nSize, sizeof(MyStruct))

Exemplo

#include <sal.h>

// This _Struct_size_bytes_ is equivalent to what below _Field_size_ means.
_Struct_size_bytes_(__builtin_offsetof(MyBuffer, buffer) + bufferSize * sizeof(int))
struct MyBuffer
{
    static int MaxBufferSize;

    _Field_z_
    const char* name;

    int firstField;

    // ... other fields

    _Field_range_(1, MaxBufferSize)
    int bufferSize;

    _Field_size_(bufferSize)        // Preferred way - easier to read and maintain.
    int buffer[]; // Using C99 Flexible array member
};

Notas para este exemplo:

  • _Field_z_ é equivalente a _Null_terminated_. _Field_z_ para o campo name especifica que o campo name é uma cadeia de caracteres terminada em nulo.
  • _Field_range_ para bufferSize especifica que o valor de bufferSize deve estar entre 1 e MaxBufferSize, incluindo ambos.
  • Os resultados finais das _Struct_size_bytes_ anotações e _Field_size_ são equivalentes. Para estruturas ou classes que têm um layout semelhante, _Field_size_ é mais fácil de ler e manter, porque tem menos referências e cálculos do que a anotação equivalente _Struct_size_bytes_ . _Field_size_ não requer conversão para o tamanho em bytes. Se o tamanho do byte for a única opção, por exemplo, para um campo de ponteiro vazio, _Field_size_bytes_ pode ser usado. Se existirem _Struct_size_bytes_ e _Field_size_, ambos estarão disponíveis para ferramentas. Cabe à ferramenta o que fazer se as duas anotações discordarem.

Ver também

  • Last updated on