Hinzufügen einer Anmerkung zu Strukturen und KlassenAnnotating Structs and Classes

  • 2 Minuten Lesedauer

Sie können Struktur-und Klassenmember mit Anmerkungen versehen, die wie invarianten funktionieren – Sie werden als true an jedem Funktions-oder Funktions Eintrag bzw. in einem Funktionswert, der die einschließende Struktur als Parameter oder Ergebniswert einschließt, angenommen.You can annotate struct and class members by using annotations that act like invariants—they are presumed to be true at any function call or function entry/exit that involves the enclosing structure as a parameter or a result value.

Struktur- und Klassen-AnmerkungenStruct and Class Annotations

  • _Field_range_(low, high)

    Das Feld befindet sich im Bereich (einschließlich) von low bis high .The field is in the range (inclusive) from low to high. Entspricht dem _Satisfies_(_Curr_ >= low && _Curr_ <= high) , das auf das mit Anmerkungen versehene Objekt angewendet wird, indem die entsprechenden Prä-oder Post Bedingungen verwendet werden.Equivalent to _Satisfies_(_Curr_ >= low && _Curr_ <= high) applied to the annotated object by using the appropriate pre or post conditions.

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

    Ein Feld, das über eine beschreibbare Größe in Elementen (oder Bytes) verfügt, wie von angegeben size .A field that has a writable size in elements (or bytes) as specified by 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)_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 über eine beschreibbare Größe in Elementen (oder Bytes) verfügt, wie von angegeben size , und die count der lesbaren Elemente (Bytes).A field that has a writable size in elements (or bytes) as specified by size, and the count of those elements (bytes) that are readable.

  • _Field_size_full_(size), _Field_size_full_opt_(size), _Field_size_bytes_full_(size), _Field_size_bytes_full_opt_(size)_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 beschreibbare Größe in Elementen (oder Bytes) aufweist, wie von angegeben size .A field that has both readable and writable size in elements (or bytes) as specified by size.

  • _Field_z_

    Ein Feld, das eine NULL-terminierte Zeichenfolge aufweist.A field that has a null-terminated string.

  • _Struct_size_bytes_(size)

    Gilt für die Struktur-oder Klassen Deklaration.Applies to struct or class declaration. Gibt an, dass ein gültiges Objekt dieses Typs größer als der deklarierte Typ und die Anzahl von Bytes sein kann, die von angegeben werden size .Indicates that a valid object of that type may be larger than the declared type, with the number of bytes being specified by size. Zum Beispiel:For example:

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

    Die Puffergröße eines Parameters pM vom Typ in Byte MyStruct * wird dann wie folgt angenommen:The buffer size in bytes of a parameter pM of type MyStruct * is then taken to be:

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

BeispielExample

#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:Notes for this example:

  • _Field_z_ entspricht _Null_terminated_._Field_z_ is equivalent to _Null_terminated_. _Field_z_ für das Feld Name gibt an, dass das Feld Name eine NULL-terminierte Zeichenfolge ist._Field_z_ for the name field specifies that the name field is a null-terminated string.
  • _Field_range_ for bufferSize gibt an, dass der Wert von bufferSize innerhalb von 1 und MaxBufferSize (beide inklusiv) liegen muss._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-Anmerkungen _Field_size_ sind gleichwertig.The end results of the _Struct_size_bytes_ and _Field_size_ annotations are equivalent. Für Strukturen oder Klassen, die über ein ähnliches Layout verfügen, _Field_size_ ist einfacher zu lesen und zu verwalten, da es weniger Verweise und Berechnungen als die entsprechende _Struct_size_bytes_ Anmerkung aufweist.For structures or classes that have a similar layout, _Field_size_ is easier to read and maintain, because it has fewer references and calculations than the equivalent _Struct_size_bytes_ annotation. _Field_size_ erfordert keine Konvertierung in die Bytegröße._Field_size_ doesn’t require conversion to the byte size. Wenn die Byte Größe die einzige Option ist, z. b. für ein void-Zeiger Feld, _Field_size_bytes_ kann verwendet werden.If byte size is the only option, for example, for a void pointer field, _Field_size_bytes_ can be used. Wenn sowohl _Struct_size_bytes_ als auch _Field_size_ vorhanden sind, sind beide für Tools verfügbar.If both _Struct_size_bytes_ and _Field_size_ exist, both will be available to tools. Es liegt an dem Tool, was zu tun ist, wenn die zwei Anmerkungen nicht übereinstimmen.It is up to the tool what to do if the two annotations disagree.

Siehe auchSee also