Binary resource inclusion (since C23)

#embed — это директива препроцессора для включения (бинарных) ресурсов в сборку, где ресурс определяется как источник данных, доступный из среды трансляции.

Синтаксис

Объяснение

В случае, если ресурс не найден или один из параметров не поддерживается реализацией, программа является некорректно сформированной.

__has_embed может раскрываться в выражениях #if и #elif . Он рассматривается как определённый макрос в #ifdef , #ifndef , #elifdef , #elifndef и defined , но не может использоваться где-либо ещё.

Ресурс имеет ширину ресурса реализации — это определенный реализацией размер в битах размещенного ресурса. Его ширина ресурса равна ширине ресурса реализации, если не изменена параметром limit . Если ширина ресурса равна 0, ресурс считается пустым. Ширина элемента внедрения равна CHAR_BIT , если не изменена параметром, определенным реализацией. Ширина ресурса должна быть кратна ширине элемента внедрения.

Расширение директивы #embed представляет собой последовательность токенов, сформированную из списка целочисленных константных выражений , описанных ниже. Группа токенов для каждого целочисленного константного выражения в списке отделяется в последовательности токенов от группы токенов для предыдущего целочисленного константного выражения в списке запятой. Последовательность не начинается и не заканчивается запятой. Если список целочисленных константных выражений пуст, последовательность токенов также пуста. Директива заменяется своим расширением и, при наличии определённых параметров embed, дополнительными или замещающими последовательностями токенов.

Значения целочисленных константных выражений в расширенной последовательности определяются реализационно-зависимым отображением данных ресурса. Значение каждого целочисленного константного выражения находится в диапазоне [ 0 , 2 ^{embed element width} ) . Если:

1. Список целочисленных константных выражений используется для инициализации массива типа, совместимого с unsigned char , или совместимого с char , если char не может содержать отрицательные значения, и
2. Ширина элемента embed равна CHAR_BIT ,

тогда содержимое инициализированных элементов массива таково, как если бы двоичные данные ресурса были fread в массив во время трансляции.

Реализациям рекомендуется учитывать порядок битов и байтов на этапе трансляции, а также порядок битов и байтов во время выполнения, чтобы более точно представлять двоичные данные ресурса из директивы. Это максимизирует вероятность того, что если ресурс, на который ссылаются на этапе трансляции через директиву #embed , совпадает с ресурсом, доступным во время выполнения, данные, которые, например, считываются с помощью fread или аналогичной функции в непрерывное хранилище, будут побитово идентичны массиву символьного типа, инициализированному из расширенного содержимого директивы #embed .

Параметры

Стандарт определяет параметры limit , prefix , suffix и if_empty . Любые другие параметры, присутствующие в директиве, должны быть определены реализацией, иначе программа является некорректной. Определяемые реализацией параметры embed могут изменять семантику директивы.

предел

`, `$`\; и\; C++\; специфические\; термины\; (такие\; как\; `limit`,\; `\_\_limit\_\_`,\; `constant-expression`)\; не\; подлежат\; переводу\; согласно\; инструкциям.\; HTML\; структура\; и\; форматирование\; полностью\; сохранены.$

Параметр встраивания limit может встречаться не более одного раза в последовательности параметров встраивания. Он должен иметь аргумент, который должен быть целочисленным (препроцессорным) константным выражением , вычисляющимся в неотрицательное число и не содержащим токен defined . Ширина ресурса устанавливается как минимум из целочисленного константного выражения, умноженного на ширину элемента встраивания, и ширины ресурса реализации.

суффикс

Параметр встраивания suffix может встречаться не более одного раза в последовательности параметров встраивания. Он должен иметь (возможно, пустой) аргумент препроцессора. Если ресурс не пуст, содержимое параметра помещается непосредственно после раскрытия директивы. В противном случае он не оказывает никакого эффекта.

префикс

Параметр встраивания prefix может встречаться не более одного раза в последовательности параметров встраивания. Он должен иметь (возможно, пустой) аргумент препроцессора. Если ресурс не пуст, содержимое параметра помещается непосредственно перед раскрытием директивы. В противном случае он не оказывает никакого эффекта.

if_empty

Параметр встраивания if_empty может встречаться не более одного раза в последовательности параметров встраивания. Он должен иметь (возможно, пустой) аргумент препроцессора. Если ресурс пуст, содержимое параметра заменяет директиву. В противном случае он не оказывает никакого эффекта.

Пример

#include <stdint.h>
#include <stdio.h>
const uint8_t image_data[] =
{
#embed "image.png"
};
const char message[] =
{
#embed "message.txt" if_empty('M', 'i', 's', 's', 'i', 'n', 'g', '\n')
,'\0' // нулевой терминатор
};
void dump(const uint8_t arr[], size_t size)
{
    for (size_t i = 0; i != size; ++i)
        printf("%02X%c", arr[i], (i + 1) % 16 ? ' ' : '\n');
    puts("");
}
int main()
{
    puts("image_data[]:");
    dump(image_data, sizeof image_data);
    puts("message[]:");
    dump((const uint8_t*)message, sizeof message);
}

image_data[]:
89 50 4E 47 0D 0A 1A 0A 00 00 00 0D 49 48 44 52
00 00 00 01 00 00 00 01 01 03 00 00 00 25 DB 56
...
message[]:
4D 69 73 73 69 6E 67 0A 00

Ссылки

Смотрите также