註釋結構和類別

  • 發行項

您可以使用作用類似非變異項目的註釋為結構和類別加上附註，在包含封入結構做為參數或結果值的任何函式呼叫或函式進入/結束點，會假定這些註釋為真。

結構與類別注釋

  • _Field_range_(low, high)

    欄位在 範圍中（內含）從 low 到 high 。 相當於使用適當的前置或後置條件套用至已標註物件的 _Satisfies_(_Curr_ >= low && _Curr_ <= high)。

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

    欄位，其可寫入的大小是由 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)

    欄位，其可寫入的大小是由 size 以項目 (或位元組) 為單位指定，而且可以讀取這些項目 (位元組) 的 count。

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

    具有可讀取及可寫入大小的欄位，其大小是以 size 所指定的項目 (或位元組) 為單位表示。

  • _Field_z_

    具有 Null 終止字串的欄位。

  • _Struct_size_bytes_(size)

    適用于結構或類別宣告。 指出該類型的有效物件可能大於所宣告的類型，其位元組數目是由 size 所指定。 例如：

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

    然後，以類型參數 pMMyStruct * 的位元組為單位的緩衝區大小會採用為：

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

範例

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

此範例的附注：

  • _Field_z_ 等於 _Null_terminated_。 _Field_z_ 針對名稱欄位，指定名稱欄位是 Null 終止的字串。
  • _Field_range_ 的 bufferSize 指定 的值 bufferSize 應該在 1 和 MaxBufferSize （兩者皆包含） 內。
  • 和 _Field_size_ 注釋的 _Struct_size_bytes_ 結束結果相等。 對於具有類似配置的結構或類別， _Field_size_ 更容易讀取和維護，因為它的參考和計算比對等 _Struct_size_bytes_ 注釋少。 _Field_size_ 不需要轉換成位元組大小。 如果位元組大小是唯一的選項，例如，對於 void 指標欄位， _Field_size_bytes_ 可以使用。 如果 和 _Field_size_ 都 _Struct_size_bytes_ 存在，則兩者都可供工具使用。 這要由工具決定，如果兩個注釋不同意，該怎麼做。

另請參閱