Включение бинарных ресурсов (с C23)

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

Синтаксис

Объяснение

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

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

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

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

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

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

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

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

Параметры

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

limit

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

suffix

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

prefix

Параметр вставки 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' // null terminator
};
 
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

Ссылки

• Стандарт C23 (ISO/IEC 9899:2023):
• 6.4.7 Имена заголовков (стр. 69)
• 6.10.1 Условное включение (стр. 165-169)
• 6.10.2 Включение двоичных ресурсов (стр. 170-177)