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

  • Статья

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

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

  • _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_ существуют, оба будут доступны для инструментов. Это до инструмента, что делать, если две заметки не согласны.

См. также