Dela via

Annotera strukturer och klasser

Du kan kommentera struct- och klassmedlemmar med hjälp av anteckningar som fungerar som invarianter – de antas vara sanna vid valfritt funktionsanrop eller funktionsinmatning/-utgång som omfattar den omslutande strukturen som en parameter eller ett resultatvärde.

Struct- och klassannoteringar

  • _Field_range_(low, high)

    Fältet finns i intervallet (inklusive) från low till high. Motsvarar _Satisfies_(_Curr_ >= low && _Curr_ <= high) applicerat på det annoterade objektet genom att använda lämpliga villkor före eller efter.

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

    Ett fält som har en skrivbar storlek i element (eller byte) som anges av 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)

    Ett fält som har en skrivbar storlek i element (eller byte) enligt vad som anges av size, och de count av de elementen (byte) som är läsbara.

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

    Ett fält som har både läsbar och skrivbar storlek i element (eller byte) enligt size.

  • _Field_z_

    Ett fält som har en null-avslutad sträng.

  • _Struct_size_bytes_(size)

    Gäller för struktur- eller klassdeklaration. Anger att ett giltigt objekt av den typen kan vara större än den deklarerade typen, med antalet byte som anges av size. Till exempel:

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

    Buffertstorleken i byte av en parameter pM av typen MyStruct * anses sedan vara:

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

Exempel

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

Anmärkningar för det här exemplet:

  • _Field_z_ motsvarar _Null_terminated_. _Field_z_ för namnfältet anger att namnfältet är en null-avslutad sträng.
  • _Field_range_ för bufferSize anger att värdet bufferSize för ska vara inom 1 och MaxBufferSize (båda inkluderande).
  • Slutresultatet av anteckningarna _Struct_size_bytes_ och _Field_size_ är likvärdiga. För strukturer eller klasser som har en liknande layout _Field_size_ är det lättare att läsa och underhålla eftersom det har färre referenser och beräkningar än motsvarande _Struct_size_bytes_ anteckning. _Field_size_ kräver inte konvertering till bytestorleken. Om bytestorlek är det enda alternativet kan du till exempel använda ett tomrumspekarfält _Field_size_bytes_ . Om både _Struct_size_bytes_ och _Field_size_ finns kommer båda att vara tillgängliga för verktyg. Det är upp till verktyget vad det ska göra om de två anteckningarna inte överensstämmer.

Se även

  • Last updated on