Zadávání poznámek ke strukturám a třídám

  • Článek
  • 2 min ke čtení

Členy struktury a třídy můžete anotovat pomocí poznámek, které fungují jako invarianty – předpokládá se, že jsou pravdivé při jakémkoli volání funkce nebo vstupu/výstupu funkce, které zahrnují ohraničující strukturu jako parametr nebo výslednou hodnotu.

Poznámky ke strukturám a třídám

  • _Field_range_(low, high)

    Pole je v rozsahu (včetně) od low do high . Ekvivalent k _Satisfies_(_Curr_ >= low && _Curr_ <= high) použití na objekt s poznámkami pomocí příslušných podmínek před nebo po.

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

    Pole, které má zapisovatelné velikosti v prvcích (nebo bajtech), jak je určeno parametrem 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)

    Pole, které má zapisovatelné velikosti v prvcích (nebo bajtech), jak je určeno parametrem , a elementů sizecount (bajtů), které jsou čitelné.

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

    Pole, které má čitelná i zapisovatelná velikost v prvcích (nebo bajtech), jak je určeno parametrem size .

  • _Field_z_

    Pole, které má řetězec zakončený hodnotou null.

  • _Struct_size_bytes_(size)

    Platí pro deklaraci struktury nebo třídy. Označuje, že platný objekt tohoto typu může být větší než deklarovaný typ s počtem bajtů určeným parametrem size . Například:

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

    Velikost vyrovnávací paměti v bajtech parametru typu se pak pMMyStruct * určuje jako:

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

Příklad

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

Poznámky pro tento příklad:

  • _Field_z_ je ekvivalentem k _Null_terminated_. _Field_z_ pro pole názvu určuje, že pole názvu je řetězec ukončený hodnotou null.
  • _Field_range_ parametr bufferSize určuje, že hodnota by měla být v rámci hodnoty 1 a bufferSizeMaxBufferSize (včetně).
  • Koncové výsledky poznámek a _Struct_size_bytes__Field_size_ jsou ekvivalentní. Pro struktury nebo třídy s podobným rozložením je snadnější čtení a údržba, protože má méně odkazů a výpočtů než ekvivalentní _Field_size__Struct_size_bytes_ anotace. _Field_size_ nevyžaduje převod na velikost byte. Je-li velikost byte jedinou možností, například pro pole ukazatele typu void, _Field_size_bytes_ lze použít. Pokud existuje _Struct_size_bytes_ i , budou pro nástroje k dispozici obě _Field_size_ možnosti. Je na nástroji, co dělat, pokud tyto dvě poznámky nesouhlasí.

Viz také