Аннотация структур и классов

Вы можете добавить примечание к структурам и членам классов, используя примечания, которые действуют как инварианты — предполагается, что они будут выполнены в любом вызове функции или функции входа и выхода, которая содержит включающую структуру в качестве значения параметров или результатов.

Структуры и заметки к классам

  • _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;
        ...
    };
    
    

    Затем размер буфера в байтах параметра pM типа MyStruct * принимается следующим образом:

    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 (включительно).
  • Конечные результаты _Struct_size_bytes_ и _Field_size_ заметки эквивалентны. Для структур или классов, имеющих аналогичный макет, _Field_size_ проще читать и обслуживать, так как он содержит меньше ссылок и вычислений, чем эквивалентная _Struct_size_bytes_ заметка. _Field_size_ не требует преобразования в размер байта. Если размер байта является единственным вариантом, например для поля указателя void, _Field_size_bytes_ можно использовать. Если оба _Struct_size_bytes_ варианта существуют и _Field_size_ существуют, они будут доступны для средств. Это до инструмента, что делать, если две заметки не согласны.

См. также раздел