Binary resource inclusion (since C23)

#embed es una directiva del preprocesador para incluir recursos (binarios) en la compilación, donde un recurso se define como una fuente de datos accesible desde el entorno de traducción.

Sintaxis

Explicación

En caso de que el recurso no se encuentre o uno de los parámetros no sea compatible con la implementación, el programa está mal formado.

__has_embed puede expandirse en la expresión de #if y #elif . Es tratado como una macro definida por #ifdef , #ifndef , #elifdef , #elifndef y defined pero no puede utilizarse en ningún otro lugar.

Un recurso tiene un ancho de recurso de implementación que es el tamaño definido por la implementación en bits del recurso localizado. Su ancho de recurso es el ancho de recurso de implementación a menos que sea modificado por un parámetro limit . Si el ancho de recurso es 0, el recurso se considera vacío. El ancho de elemento de incrustación es igual a CHAR_BIT a menos que sea modificado por un parámetro definido por la implementación. El ancho de recurso debe ser divisible por el ancho de elemento de incrustación.

La expansión de una directiva #embed es una secuencia de tokens formada a partir de la lista de expresiones constantes enteras descritas a continuación. El grupo de tokens para cada expresión constante entera en la lista está separado en la secuencia de tokens del grupo de tokens para la expresión constante entera anterior en la lista por una coma. La secuencia no comienza ni termina con una coma. Si la lista de expresiones constantes enteras está vacía, la secuencia de tokens está vacía. La directiva es reemplazada por su expansión y, con la presencia de ciertos parámetros de embed, secuencias de tokens adicionales o de reemplazo.

Los valores de las expresiones constantes enteras en la secuencia expandida se determinan mediante un mapeo definido por la implementación de los datos del recurso. El valor de cada expresión constante entera está en el rango [ 0 , 2 ^{embed element width} ) . Si:

1. La lista de expresiones constantes enteras se utiliza para inicializar un array de un tipo compatible con unsigned char , o compatible con char si char no puede contener valores negativos, y
2. El ancho del elemento embed es igual a CHAR_BIT ,

entonces los contenidos de los elementos inicializados del array son como-si los datos binarios del recurso se fread en el array en tiempo de traducción.

Se recomienda a las implementaciones que consideren los órdenes de bits y bytes en tiempo de traducción, así como los órdenes de bits y bytes en tiempo de ejecución, para representar de manera más apropiada los datos binarios del recurso desde la directiva. Esto maximiza la probabilidad de que, si el recurso referenciado en tiempo de traducción a través de la directiva #embed es el mismo al que se accede por medios en tiempo de ejecución, los datos que son, por ejemplo, fread o similares en almacenamiento contiguo se compararán bit a bit iguales a un arreglo de tipo carácter inicializado a partir del contenido expandido de una directiva #embed .

Parámetros

El estándar define los parámetros limit , prefix , suffix y if_empty . Cualquier otro parámetro que aparezca en la directiva debe estar definido por la implementación, o el programa está mal formado. Los parámetros de incrustación definidos por la implementación pueden cambiar la semántica de la directiva.

límite

El limit parámetro embed puede aparecer como máximo una vez en la secuencia de parámetros embed. Debe tener un argumento, que debe ser una expresión constante (preprocesador) constant expression que evalúe a un número no negativo y no contenga el token defined . El ancho del recurso se establece al mínimo del resultado de multiplicar la expresión constante entera por el ancho del elemento embed y el ancho del recurso de implementación.

sufijo

El parámetro de incrustación suffix puede aparecer como máximo una vez en la secuencia de parámetros de incrustación. Debe tener una cláusula de argumento de preprocesador (posiblemente vacía). Si el recurso no está vacío, el contenido de la cláusula de parámetro se coloca inmediatamente después de la expansión de la directiva. De lo contrario, no tiene efecto.

prefijo

El prefix parámetro embed puede aparecer como máximo una vez en la secuencia de parámetros embed. Debe tener una cláusula de argumento de preprocesador (posiblemente vacía). Si el recurso no está vacío, el contenido de la cláusula de parámetro se coloca inmediatamente antes de la expansión de la directiva. De lo contrario, no tiene efecto.

if_empty

El parámetro de incrustación if_empty puede aparecer como máximo una vez en la secuencia de parámetros de incrustación. Debe tener una cláusula de argumento de preprocesador (posiblemente vacía). Si el recurso está vacío, el contenido de la cláusula del parámetro reemplaza la directiva. De lo contrario, no tiene efecto.

Ejemplo

#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' // terminador nulo
};
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

Referencias

Véase también