-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathembed.html
More file actions
515 lines (443 loc) · 36.7 KB
/
Copy pathembed.html
File metadata and controls
515 lines (443 loc) · 36.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
<!doctype html>
<html class="cpprefjp" lang="ja" itemscope="" itemtype="http://schema.org/WebPage">
<head>
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-NXNBNVBTJS"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-NXNBNVBTJS');
</script>
<meta charset="UTF-8">
<title>ファイルを読み込む#embed命令を追加 [P1967R14] - cpprefjp C++日本語リファレンス</title>
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="keywords" content="
C++,標準ライブラリ,リファレンス,ドキュメント,STL,std,cpp26
">
<meta name="title" content="ファイルを読み込む#embed命令を追加 [P1967R14] - cpprefjp C++日本語リファレンス" />
<meta itemprop="name" content="ファイルを読み込む#embed命令を追加 [P1967R14] - cpprefjp C++日本語リファレンス" />
<meta property="og:title" content="ファイルを読み込む#embed命令を追加 [P1967R14] - cpprefjp C++日本語リファレンス" />
<meta property="og:url" content="https://cpprefjp.github.io/lang/cpp26/embed.html" />
<meta property="og:site_name" content="cpprefjp - C++日本語リファレンス" />
<meta property="og:type" content="article" />
<meta property="og:description" content="C++26では、ファイルなどのリソースの内容をソースコードへ埋め込む`#embed`前処理ディレクティブが追加される。" />
<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="ファイルを読み込む#embed命令を追加 [P1967R14] - cpprefjp C++日本語リファレンス" />
<meta name="twitter:url" content="https://cpprefjp.github.io/lang/cpp26/embed.html" />
<meta name="twitter:description" content="C++26では、ファイルなどのリソースの内容をソースコードへ埋め込む`#embed`前処理ディレクティブが追加される。" />
<link rel="alternate" type="application/atom+xml" title="Atom" href="https://cpprefjp.github.io/rss.xml" />
<link rel="apple-touch-icon" sizes="180x180" href="../../static/favicons/apple-touch-icon.png?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8">
<link rel="icon" type="image/png" sizes="32x32" href="../../static/favicons/favicon-32x32.png?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8">
<link rel="icon" type="image/png" sizes="16x16" href="../../static/favicons/favicon-16x16.png?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8">
<link rel="manifest" href="../../manifest.json?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8">
<meta name="theme-color" content="#f5f8fc">
<link rel="stylesheet" href="../../static/pygments/default.css?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8">
<!-- <link rel="stylesheet" href="../../static/css/root.css"> -->
<link href="../../static/kunai/css/kunai-stage-0.css?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8" rel="stylesheet">
<link href="../../static/kunai/css/kunai-stage-1.css?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8" rel="stylesheet">
<link href="../../static/kunai/css/kunai-stage-2.css?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8" rel="stylesheet">
<link href="../../static/kunai/css/kunai-stage-3.css?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8" rel="stylesheet">
<script type="text/javascript" src="../../static/kunai/js/kunai-vendor.js?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8"></script>
<script type="text/javascript" src="../../static/kunai/js/kunai.js?cachebust=f86c46a60db5ac737e5f16bddeeecab4f10ce6b8"></script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function() {
var kn = new Kunai;
kn.cpprefjp();
});
</script>
</head>
<body>
<header data-kunai-mdinfo="{"meta": {"cpp": ["cpp26"]}, "sources": [{"id": "147671bcd5440a8885d62155795f083b7cffcdcb", "source": "// ABCDEF\n#include <print>\n\nint main()\n{\n // \u3053\u306e\u30bd\u30fc\u30b9\u30d5\u30a1\u30a4\u30eb\u306e\u5148\u982d9\u30d0\u30a4\u30c8\uff081\u884c\u76ee\u306e\u30b3\u30e1\u30f3\u30c8\uff09\u3092\u8aad\u307f\u8fbc\u3080\n constexpr unsigned char head[] = {\n#embed __FILE__ limit(9)\n };\n std::println(\"{}\", std::string_view{reinterpret_cast<const char*>(head), sizeof(head)});\n\n // limit(0)\u306b\u3088\u3063\u3066\u30ea\u30bd\u30fc\u30b9\u306f\u7a7a\u3068\u306a\u308b\u305f\u3081\u3001if_empty\u306e\u30c8\u30fc\u30af\u30f3\u5217\u3078\u7f6e\u304d\u63db\u3048\u3089\u308c\u308b\u3002\n // \u3053\u306e\u3068\u304d\u3001prefix\u3068suffix\u306f\u7121\u8996\u3055\u308c\u308b\n constexpr int marker[] = {\n#embed __FILE__ limit(0) prefix(1,) suffix(, 2) if_empty(42)\n };\n std::println(\"{} {}\", marker[0], sizeof(marker) / sizeof(int));\n\n // \u7a7a\u3067\u306f\u306a\u3044\u5834\u5408\u306f\u3001prefix\u3068suffix\u304c\u9069\u7528\u3055\u308c\u3001if_empty\u304c\u7121\u8996\u3055\u308c\u308b\n constexpr unsigned char fixed[] = {\n#embed __FILE__ limit(2) prefix(0x01,) suffix(, 0x02) if_empty(42)\n };\n std::println(\"{} {} {}\", fixed[0], fixed[3], sizeof(fixed));\n}\n"}, {"id": "bb9b047961d41f25fcdcd4da55afe6af2aaf2e52", "source": "#include <print>\n#include <random>\n#include <cstdint>\n\nint main()\n{\n // \u30b3\u30f3\u30d1\u30a4\u30eb\u6642\u306b/dev/urandom\u304b\u30894\u30d0\u30a4\u30c8\u3092\u8aad\u307f\u8fbc\u3080\u3002\n // \u3053\u306e\u30ea\u30bd\u30fc\u30b9\u306b\u306f\u7d42\u7aef\u304c\u306a\u3044\u305f\u3081\u3001limit\u306e\u6307\u5b9a\u304c\u5fc5\u9808\u3068\u306a\u308b\n constexpr unsigned char seed_bytes[] = {\n#embed \"/dev/urandom\" limit(4)\n };\n\n // \u8aad\u307f\u8fbc\u3093\u30604\u30d0\u30a4\u30c8\u309232\u30d3\u30c3\u30c8\u306e\u5024\u306b\u307e\u3068\u3081\u3001\u4e71\u6570\u30a8\u30f3\u30b8\u30f3\u306e\u30b7\u30fc\u30c9\u3068\u3059\u308b\n std::uint32_t seed = 0;\n for (unsigned char b : seed_bytes) {\n seed = (seed << 8) | b;\n }\n\n std::mt19937 engine{seed};\n std::uniform_int_distribution<int> dist{1, 6};\n\n std::println(\"{}\", dist(engine));\n}\n"}, {"id": "50298c610b1c6d581ec526b6a840714ac9d1c556", "source": "// ABCDEF\n#include <print>\n\nint main()\n{\n#if __has_embed(__FILE__) == __STDC_EMBED_FOUND__\n std::println(\"found\");\n#endif\n\n#if __has_embed(__FILE__ limit(0)) == __STDC_EMBED_EMPTY__\n std::println(\"empty\");\n#endif\n\n#if __has_embed(\"no_such_resource.bin\") == __STDC_EMBED_NOT_FOUND__\n std::println(\"not found\");\n#endif\n}\n"}], "page_id": ["lang", "cpp26", "embed"]}">
<nav class="navbar navbar-default" role="navigation">
<div class="container-fluid">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../../index.html">
<div class="title-wrapper clearfix">
<div class="title">cpprefjp - C++日本語リファレンス</div>
</div>
</a>
</div>
<div class="collapse navbar-collapse" id="navbar-collapse">
<ul class="nav navbar-nav navbar-right">
<li>
<div class="google-search">
<script>
(function() {
var cx = '013316413321391058734:ji_u66hl7hq';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
<div class="gcse-search"></div>
</div>
</li>
<li>
<a href="https://github.com/cpprefjp/site">GitHub Project</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<main id="main" role="main">
<div class="container-fluid">
<div class="row">
<div class="col-sm-9 col-sm-push-3" itemscope itemtype="http://schema.org/Article">
<div class="row">
<div class="col-sm-12 google-search-result">
<gcse:searchresults></gcse:searchresults>
</div>
</div>
<div class="row">
<div class="col-sm-12 content-header">
<ol class="breadcrumb">
<li itemscope itemtype="http://www.schema.org/SiteNavigationElement">
<span>
<a href="../../index.html" itemprop="url">
<i class="fa fa-fw fa-home"></i>
</a>
</span>
</li>
<li itemscope itemtype="http://www.schema.org/SiteNavigationElement">
<span>
<a href="../../lang.html" itemprop="url">
<span itemprop="name">言語機能</span>
</a>
</span>
</li>
<li itemscope itemtype="http://www.schema.org/SiteNavigationElement">
<span>
<a href="../../lang/cpp26.html" itemprop="url">
<span itemprop="name">C++26</span>
</a>
</span>
</li>
<li class="active" itemscope itemtype="http://www.schema.org/SiteNavigationElement">
<span>
<span itemprop="name">ファイルを読み込む#embed命令を追加 [P1967R14]</span>
</span>
</li>
</ol>
<div class="crsearch"></div>
</div>
</div>
<div class="row">
<div class="col-sm-12 edit-button">
<p class="text-right"><small>
最終更新日時:
<time itemprop="datePublished" class="js-local-time"
datetime="2026-09-08T20:49:05+09:00">
2026年09月08日 20時49分05秒 (JST)
</time>
<br/>
<span itemprop="author" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Akira Takahashi</span>
</span>
が更新
</small></p>
<script>
(function () {
// 最終更新日時を閲覧者のローカルタイムゾーンで表示し直す (issue #53 の正規化)。
// JS が無効な環境ではサーバ生成の JST 表記がそのまま残る。
function pad(n) { return (n < 10 ? '0' : '') + n; }
var els = document.querySelectorAll('time.js-local-time[datetime]');
for (var i = 0; i < els.length; i++) {
var el = els[i];
var d = new Date(el.getAttribute('datetime'));
if (isNaN(d.getTime())) { continue; }
var tz = '';
try {
var parts = new Intl.DateTimeFormat(undefined, { timeZoneName: 'short' }).formatToParts(d);
for (var j = 0; j < parts.length; j++) {
if (parts[j].type === 'timeZoneName') { tz = parts[j].value; break; }
}
} catch (e) {}
el.textContent = d.getFullYear() + '年' + pad(d.getMonth() + 1) + '月' + pad(d.getDate()) + '日 '
+ pad(d.getHours()) + '時' + pad(d.getMinutes()) + '分' + pad(d.getSeconds()) + '秒'
+ (tz ? ' (' + tz + ')' : '');
}
})();
</script>
<p class="text-right">
<a class="history" target="_blank" href="https://github.com/cpprefjp/site/commits/master/lang/cpp26/embed.md">
<span class="fa fa-fw fa-clock-o fa-flip-horizontal"></span>履歴
</a>
<a class="edit" target="_blank" href="https://github.com/cpprefjp/site/edit/master/lang/cpp26/embed.md">
<span class="fa fa-fw fa-pencil"></span>編集
</a>
</p>
</div>
</div>
<div class="row">
<div class="col-sm-12 content-body">
<h1 itemprop="name"><span class="token">ファイルを読み込む#embed命令を追加 [P1967R14]</span><span class="cpp cpp26" title="C++26で追加">(C++26)</span></h1>
<div itemprop="articleBody"><p>
</p>
<p>このページはC++26に採用される見込みの言語機能の変更を解説しています。</p>
<p>のちのC++規格でさらに変更される場合があるため<a href="#relative-page">関連項目</a>を参照してください。</p>
<p>
</p>
<h2>概要</h2>
<p>C++26では、ファイルなどのリソースの内容をソースコードへ埋め込む<code>#embed</code>前処理ディレクティブが追加される。</p>
<p>これによって、これまで実行時に読み込んでいた画像・音声・シェーダなどのバイナリリソースを、コンパイル時に読み込んで実行ファイルへ埋め込めるようになる。</p>
<p><div class="codehilite"><pre><span></span><code><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">image</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed "image.png"</span>
<span class="p">};</span>
</code></pre></div>
</p>
<p>従来は、外部ツールでバイナリを<code>0x89, 0x50, ...</code>のようなソースコードへ変換してからインクルードする必要があった。この方法はビルド手順が複雑になるうえ、巨大な初期化子リストのコンパイルに長い時間とメモリを要していた。<code>#embed</code>は処理系がリソースを直接読み込むため、これらの問題を避けられる。</p>
<h2>仕様</h2>
<h3>リソース</h3>
<p><code>#embed</code>が読み込む対象は、規格では「ファイル」ではなく「リソース (resource)」と呼ばれ、翻訳環境からアクセスできるデータの供給源として定義されている。リソースをどのように特定・検索するかは<a class="cpprefjp-defined-word" data-desc="処理系定義の動作。処理系によって事前に定めた動作をする" href="../../implementation-compliance.html#dfn-implementation-defined-behavior">処理系定義</a>であるため、通常のファイル以外も対象となりうる。</p>
<ul>
<li>POSIXのキャラクタデバイスや疑似ファイル（<code>/dev/urandom</code>など）。このような「無限に読み出せるリソース」の存在が、読み込む要素数の上限を指定する<code>limit</code>パラメータが導入された動機となっている</li>
<li>処理系が独自にサポートする、URIのような指定方法によるリソース（ネットワーク越しの取得や、認証・権限の確認をともなうものを含む）</li>
<li>ビルドシステムなどが提供する、実体がファイルではないリソース</li>
</ul>
<p>リソースは<code><a href="../../reference/cstdio/fgetc.html">std::fgetc()</a></code>によってバイナリファイルとして読み出されたかのように、先頭から1バイトずつ読み込まれる。</p>
<h3>構文</h3>
<p><code>#embed</code>ディレクティブは、<code>#include</code>と同じ2つの形式でリソースを指定する。</p>
<p><div class="codehilite"><pre><span></span><code><span class="cp">#embed <ヘッダ名> </span><span class="c1">// 処理系定義の場所からリソースを検索する</span>
<span class="cp">#embed "ファイル名" </span><span class="c1">// 名前でリソースを特定する。失敗した場合は<>形式と同じ検索を行う</span>
</code></pre></div>
</p>
<p>リソースの検索方法は<a class="cpprefjp-defined-word" data-desc="処理系定義の動作。処理系によって事前に定めた動作をする" href="../../implementation-compliance.html#dfn-implementation-defined-behavior">処理系定義</a>であり、<code>#include</code>とは別の検索パスをもつことが推奨されている。リソースが見つからない場合、およびリソースを処理できない場合、プログラムは<a class="cpprefjp-defined-word" data-desc="プログラムが適格でないこと。コンパイルエラーなどになる" href="../../implementation-compliance.html#dfn-ill-formed">不適格</a>となる。</p>
<p>指定部分にマクロを使用することもできる。この場合、マクロを展開した結果からヘッダ名を形成する。</p>
<p><div class="codehilite"><pre><span></span><code><span class="cp">#define RESOURCE "data.bin"</span>
<span class="cp">#embed RESOURCE</span>
</code></pre></div>
</p>
<h3>置き換えの結果</h3>
<p><code>#embed</code>ディレクティブは、<code>int</code>型の整数リテラルをカンマで区切ったリストへ置き換えられる。配列になるわけではないため、初期化子リストの中だけでなく、単一の値が必要な場所にも使用できる。</p>
<p><div class="codehilite"><pre><span></span><code><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">data</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed "data.bin" </span><span class="c1">// 複数の要素へ展開される</span>
<span class="p">};</span>
<span class="kt">int</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">=</span>
<span class="cp">#embed "single.bin" </span><span class="c1">// 1バイトのリソースであれば、単一の値としても使用できる</span>
<span class="p">;</span>
</code></pre></div>
</p>
<p>リストの各要素はリソースの1バイトに対応し、その値は<code>unsigned char</code>で表現できる範囲となる。リソースのビット幅が<code><a href="../../reference/climits/char_bit.html">CHAR_BIT</a></code>の整数倍でない場合、プログラムは<a class="cpprefjp-defined-word" data-desc="プログラムが適格でないこと。コンパイルエラーなどになる" href="../../implementation-compliance.html#dfn-ill-formed">不適格</a>となる。</p>
<p>なお、<code>char</code>が符号付き型である処理系では、<code>128</code>以上のバイトを<code>char</code>の配列へ格納しようとすると縮小変換によってコンパイルエラーとなる。バイナリを格納する配列の要素型には<code>unsigned char</code>または<code><a href="../../reference/cstddef/byte.html">std::byte</a></code>を使用する。</p>
<h3>埋め込みパラメータ</h3>
<p>リソースの指定に続けて、以下のパラメータを指定できる。各パラメータは高々1回のみ指定でき、順序は問わない。</p>
<table border="1" bordercolor="#888" style="border-collapse:collapse">
<thead>
<tr>
<th>パラメータ</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>limit(定数式)</code></td>
<td>リストの要素数の上限を指定する</td>
</tr>
<tr>
<td><code>prefix(トークン列)</code></td>
<td>リストの直前へトークン列を挿入する</td>
</tr>
<tr>
<td><code>suffix(トークン列)</code></td>
<td>リストの直後へトークン列を挿入する</td>
</tr>
<tr>
<td><code>if_empty(トークン列)</code></td>
<td>リソースが空である場合に、ディレクティブ全体をトークン列で置き換える</td>
</tr>
</tbody>
</table>
<p><div class="codehilite"><pre><span></span><code><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">data</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed "data.bin" limit(1024) prefix(0x01, 0x02,) suffix(, 0xFF) if_empty(0x00)</span>
<span class="p">};</span>
</code></pre></div>
</p>
<ul>
<li><code>limit</code>の引数は、条件付き取り込み（<code>#if</code>）と同じ規則で評価される整数定数式であり、<code>0</code>以上でなければならない。<code>defined</code>は使用できないが、<code>__has_include</code>は使用できる</li>
<li><code>/dev/urandom</code>のような終端のないリソースを読み込む場合、<code>limit</code>を指定しなければ処理系がメモリを使い果たすまで読み込みを続けることになる</li>
<li><code>prefix</code>と<code>suffix</code>のトークン列は任意の前処理トークン列であり、バイト値に限られない。上記のように、区切りのカンマも自分で書く必要がある</li>
<li><code>prefix</code>と<code>suffix</code>は、リソースが空である場合には無視される</li>
<li><code>if_empty</code>は、リソースが空ではない場合には無視される</li>
<li>リソースは、要素数が<code>0</code>である場合に空とみなされる。<code>limit(0)</code>を指定した場合や、<code><a href="../cpp29/embed_offset_parameter.html">offset</a></code>（C++29）でリソースの終端を越えた場合も空となる</li>
</ul>
<p>これらの標準のパラメータに加えて、<code>vendor::param</code>のように<code>::</code>で区切った形式の、処理系独自のパラメータを指定できる（条件付きサポート）。</p>
<h3><code>__has_embed</code>前処理演算子</h3>
<p><code>#if</code>などの条件付き取り込みの中で、リソースが存在するかを検査できる。</p>
<p><div class="codehilite"><pre><span></span><code><span class="cp">#if __has_embed("data.bin")</span>
<span class="c1">// data.binが存在し、空でない場合の処理</span>
<span class="cp">#endif</span>
</code></pre></div>
</p>
<p><code>__has_embed</code>は、<code><a href="../cpp17/has_include.html">__has_include</a></code>と同様の前処理演算子であり、<code>#embed</code>と同じ形式でリソースと埋め込みパラメータを受け取って、以下のいずれかの値へ置き換えられる。これらの値は、定義済みマクロとしても提供される。</p>
<table border="1" bordercolor="#888" style="border-collapse:collapse">
<thead>
<tr>
<th>定義済みマクロ</th>
<th>値</th>
<th>意味</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>__STDC_EMBED_NOT_FOUND__</code></td>
<td><code>0</code></td>
<td>リソースが見つからない、または指定されたパラメータが未サポートである</td>
</tr>
<tr>
<td><code>__STDC_EMBED_FOUND__</code></td>
<td><code>1</code></td>
<td>リソースが見つかり、空ではない</td>
</tr>
<tr>
<td><code>__STDC_EMBED_EMPTY__</code></td>
<td><code>2</code></td>
<td>リソースが見つかり、空である</td>
</tr>
</tbody>
</table>
<p><code>__has_embed</code>では、未知の埋め込みパラメータを指定してもプログラムは<a class="cpprefjp-defined-word" data-desc="プログラムが適格でないこと。コンパイルエラーなどになる" href="../../implementation-compliance.html#dfn-ill-formed">不適格</a>とはならず、「未サポート」として<code>__STDC_EMBED_NOT_FOUND__</code>が返る。この性質によって、処理系独自のパラメータが使用できるかを検査できる。</p>
<h3>機能テストマクロ</h3>
<ul>
<li><code>__cpp_pp_embed</code>が<code>202502L</code>として定義される</li>
</ul>
<h2>例</h2>
<h3>リソースを読み込む</h3>
<p><div class="codehilite"><pre><span></span><code><span class="cp">#include <a href="../../reference/print.html"><print></a></span>
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// ファイルの内容をバイト列として読み込む</span>
<span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">data</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed "data.bin"</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"{} bytes"</span><span class="p">,</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">data</span><span class="p">));</span>
<span class="p">}</span>
</code></pre></div>
</p>
<h3>埋め込みパラメータを使用する</h3>
<p>以下の例は、自身のソースファイルを読み込むことで、外部のファイルなしに動作を確認できるようにしている。</p>
<p><div class="yata" id="147671bcd5440a8885d62155795f083b7cffcdcb"><div class="codehilite"><pre><span></span><code><span class="c1">// ABCDEF</span>
<span class="cp">#include <a href="../../reference/print.html"><print></a></span>
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// このソースファイルの先頭9バイト（1行目のコメント）を読み込む</span>
<span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">head</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed __FILE__ limit(9)</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../../reference/string_view/basic_string_view.html">std::string_view</a></span><span class="p">{</span><span class="k">reinterpret_cast</span><span class="o"><</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*></span><span class="p">(</span><span class="n">head</span><span class="p">),</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">head</span><span class="p">)});</span>
<span class="w"> </span><span class="c1">// limit(0)によってリソースは空となるため、if_emptyのトークン列へ置き換えられる。</span>
<span class="w"> </span><span class="c1">// このとき、prefixとsuffixは無視される</span>
<span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">marker</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed __FILE__ limit(0) prefix(1,) suffix(, 2) if_empty(42)</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"{} {}"</span><span class="p">,</span><span class="w"> </span><span class="n">marker</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">marker</span><span class="p">)</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="kt">int</span><span class="p">));</span>
<span class="w"> </span><span class="c1">// 空ではない場合は、prefixとsuffixが適用され、if_emptyが無視される</span>
<span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">fixed</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed __FILE__ limit(2) prefix(0x01,) suffix(, 0x02) if_empty(42)</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"{} {} {}"</span><span class="p">,</span><span class="w"> </span><span class="n">fixed</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span><span class="w"> </span><span class="n">fixed</span><span class="p">[</span><span class="mi">3</span><span class="p">],</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">fixed</span><span class="p">));</span>
<span class="p">}</span>
</code></pre></div>
</div></p>
<h4>出力</h4>
<p><pre><code>// ABCDEF
42 1
1 2 4
</code></pre></p>
<h3>ファイル以外のリソースを読み込む</h3>
<p><div class="yata" id="bb9b047961d41f25fcdcd4da55afe6af2aaf2e52"><div class="codehilite"><pre><span></span><code><span class="cp">#include <a href="../../reference/print.html"><print></a></span>
<span class="cp">#include <a href="../../reference/random.html"><random></a></span>
<span class="cp">#include <a href="../../reference/cstdint.html"><cstdint></a></span>
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// コンパイル時に/dev/urandomから4バイトを読み込む。</span>
<span class="w"> </span><span class="c1">// このリソースには終端がないため、limitの指定が必須となる</span>
<span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">seed_bytes</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="cp">#embed "/dev/urandom" limit(4)</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="c1">// 読み込んだ4バイトを32ビットの値にまとめ、乱数エンジンのシードとする</span>
<span class="w"> </span><span class="n"><a href="../../reference/cstdint/uint32_t.html">std::uint32_t</a></span><span class="w"> </span><span class="n">seed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">b</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">seed_bytes</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">seed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">seed</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="mi">8</span><span class="p">)</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">b</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="n"><a href="../../reference/random/mt19937.html">std::mt19937</a></span><span class="w"> </span><span class="n">engine</span><span class="p">{</span><span class="n">seed</span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/random/uniform_int_distribution.html">std::uniform_int_distribution</a></span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="w"> </span><span class="n">dist</span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">};</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span><span class="w"> </span><span class="n">dist</span><span class="p">(</span><span class="n">engine</span><span class="p">));</span>
<span class="p">}</span>
</code></pre></div>
</div></p>
<p>シードはコンパイル時に確定するため、生成される乱数列は実行のたびではなく、コンパイルのたびに変化する。</p>
<h4>出力例</h4>
<p><pre><code>4
</code></pre></p>
<h3><code>__has_embed</code>でリソースの有無を検査する</h3>
<p><div class="yata" id="50298c610b1c6d581ec526b6a840714ac9d1c556"><div class="codehilite"><pre><span></span><code><span class="c1">// ABCDEF</span>
<span class="cp">#include <a href="../../reference/print.html"><print></a></span>
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="cp">#if __has_embed(__FILE__) == __STDC_EMBED_FOUND__</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"found"</span><span class="p">);</span>
<span class="cp">#endif</span>
<span class="cp">#if __has_embed(__FILE__ limit(0)) == __STDC_EMBED_EMPTY__</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"empty"</span><span class="p">);</span>
<span class="cp">#endif</span>
<span class="cp">#if __has_embed("no_such_resource.bin") == __STDC_EMBED_NOT_FOUND__</span>
<span class="w"> </span><span class="n"><a href="../../reference/print/println.html">std::println</a></span><span class="p">(</span><span class="s">"not found"</span><span class="p">);</span>
<span class="cp">#endif</span>
<span class="p">}</span>
</code></pre></div>
</div></p>
<h4>出力</h4>
<p><pre><code>found
empty
not found
</code></pre></p>
<h2>この機能が必要になった背景・経緯</h2>
<p>バイナリリソースをプログラムへ埋め込むという要求は古くからあり、実際には以下のような方法がとられてきた。</p>
<ul>
<li>外部ツールでバイナリを<code>0x89, 0x50, 0x4E, ...</code>のようなカンマ区切りのソースコードへ変換し、インクルードする</li>
<li>リンカのオプションや、アセンブラの<code>.incbin</code>のような処理系固有の機能を使用する</li>
<li>実行時にファイルを読み込む</li>
</ul>
<p>このうち移植性のある方法は最初のものだが、生成されたソースは1バイトあたり数文字のテキストになるため、数MBのリソースでも巨大なファイルとなり、コンパイル時間とメモリ消費が大きな問題になっていた。処理系がリソースを直接読み込む<code>#embed</code>であれば、この変換自体が不要になる。</p>
<p>この機能はC23で<code><stdio.h></code>とは独立した前処理ディレクティブとして先に標準化され、C++26でも同じ構文・意味論で取り込まれた。</p>
<h2><a href="#relative-page" id="relative-page">関連項目</a></h2>
<ul>
<li><a href="../cpp17/has_include.html">C++17 <code>__has_include</code></a></li>
<li><a href="../cpp29/embed_offset_parameter.html">C++29 <code>#embed</code>に<code>offset</code>パラメータを追加</a></li>
<li><code><a href="../../reference/cstddef/byte.html">std::byte</a></code></li>
</ul>
<h2>参照</h2>
<ul>
<li><a href="https://open-std.org/jtc1/sc22/wg21/docs/papers/2025/p1967r14.html" target="_blank">P1967R14 #embed - a scannable, tooling-friendly binary resource inclusion mechanism</a></li>
</ul></div>
</div>
</div>
</div>
<div id="sidebar" class="col-sm-3 col-sm-pull-9">
</div>
</div>
</div>
</main>
<footer class="footer navbar navbar-default">
<div class="container-fluid">
<p><small>
本サイトの情報は、
<a href="https://creativecommons.org/licenses/by/4.0/deed.ja" rel="nofollow">クリエイティブ・コモンズ 表示 4.0 非移植 ライセンス(CC BY)</a>
の下に提供されています。
</small></p>
</div>
</footer>
</body>
</html>