Hinzufügen einer Anmerkung zu Strukturen und Klassen

  • Artikel

Sie können Struktur- und Klassenmember kommentieren, indem Sie Anmerkungen verwenden, die wie Invarianten fungieren– sie werden angenommen, dass sie bei jedem Funktionsaufruf oder Funktionseintrag/-exit wahr sind, der die eingeschlossene Struktur als Parameter oder ergebniswert umfasst.

Struktur- und Klassen-Anmerkungen

  • _Field_range_(low, high)

    Das Feld befindet sich im Bereich (einschließlich) von low zu high. Entspricht dem _Satisfies_(_Curr_ >= low && _Curr_ <= high) Anwenden auf das kommentierte Objekt mithilfe der entsprechenden Vor- oder Nachbereitungsbedingungen.

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

    Ein Feld, das eine schreibbare Größe in Elementen (oder Byte) aufweist, wie angegeben.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)

    Ein Feld, das eine beschreibbare Größe in Elementen (oder Byte) aufweist, wie angegeben size, und die Elemente (Bytes), die count lesbar sind.

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

    Ein Feld, das sowohl lesbare als auch schreibbare Größe in Elementen (oder Byte) aufweist, wie angegeben size.

  • _Field_z_

    Ein Feld, das eine null-beendete Zeichenfolge enthält.

  • _Struct_size_bytes_(size)

    Gilt für Struktur- oder Klassendeklaration. Gibt an, dass ein gültiges Objekt dieses Typs größer als der deklarierte Typ sein kann, wobei die Anzahl der Byte angegeben wird size. Beispiel:

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

    Die Puffergröße in Byte eines pM Typparameters MyStruct * wird dann wie folgt übernommen:

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

Beispiel

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

Hinweise für dieses Beispiel:

  • _Field_z_ entspricht _Null_terminated_. _Field_z_ für das Namensfeld gibt an, dass das Namensfeld eine null-beendete Zeichenfolge ist.
  • _Field_range_ for bufferSize specifies that the value of bufferSize should be within 1 and MaxBufferSize (both inclusive).
  • Die Endergebnisse der _Struct_size_bytes_ Und _Field_size_ Anmerkungen sind gleichwertig. Bei Strukturen oder Klassen mit einem ähnlichen Layout ist es einfacher zu _Field_size_ lesen und Standard zu berücksichtigen, da sie weniger Bezüge und Berechnungen aufweist als die entsprechende _Struct_size_bytes_ Anmerkung. _Field_size_ erfordert keine Konvertierung in die Bytegröße. Wenn die Bytegröße die einzige Option ist, z. B. für ein leeres Zeigerfeld, _Field_size_bytes_ kann verwendet werden. Wenn beides _Struct_size_bytes_ vorhanden ist _Field_size_ , stehen beide Tools zur Verfügung. Es liegt an dem Tool, was zu tun ist, wenn die beiden Anmerkungen nicht einverstanden sind.

Siehe auch