Theolizer  Version.1.2.0
serializer for C++ / Do you want to update your classes easily ?
7e.support_stl.h
[詳解]
1 //############################################################################
2 /*!
3  @brief ドキュメント・ファイル－使用方法（個別）
4  @ingroup Documents
5  @file 7e.support_stl.h
6  @author Yoshinori Tahara
7  @date 2017/02/08 Created
8 */
9 /*
10  © 2016 Theoride Technology (http://theolizer.com/) All Rights Reserved.
11  "Theolizer" is a registered trademark of Theoride Technology.
12 
13  "Theolizer" License
14  In the case where you are in possession of a valid “Theolizer” License,
15  you may use this file in accordance with the terms and conditions of
16  the use license determined by Theoride Technology.
17 
18  General Public License Version 3 ("GPLv3")
19  You may use this file in accordance with the terms and conditions of
20  GPLv3 published by Free Software Foundation.
21  Please confirm the contents of GPLv3 at https://www.gnu.org/licenses/gpl.txt .
22  A copy of GPLv3 is also saved in a LICENSE.TXT file.
23 
24  商用ライセンス
25  あなたが有効なTheolizer商用ライセンスを保持している場合、
26  セオライド テクノロジーの定める使用許諾書の条件に従って、
27  このファイルを取り扱うことができます。
28 
29  General Public License Version 3(以下GPLv3)
30  Free Software Foundationが公表するGPLv3の使用条件に従って、
31  あなたはこのファイルを取り扱うことができます。
32  GPLv3の内容を https://www.gnu.org/licenses/gpl.txt にて確認して下さい。
33  またGPLv3のコピーをLICENSE.TXTファイルにおいてます。
34 */
35 //############################################################################
36 
37 /*!
38  @page SupportSTL スマート・ポインタ、および、標準コンテナ・サポートの使い方
39 ここでは、スマート・ポイントと標準コンテナをシリアライズするための機能について説明します。
40 
41 基本は単にシリアライズするだけです。特別な操作は必要ありませんが、コンテナについては２つ応用的な使い方があります。
42 
43 - コンテナへ保存する要素をオブジェクト追跡する場合
44 - 保存先指定機能(@ref Destinations )により分割保存したコンテナのデータを合成する場合
45 
46 <br>
47 //############################################################################
48 @section HowToUseSmartPointer 1.スマート・ポインタのシリアライズ方法
49 //############################################################################
50 
51 Theolizerはスマート・ポインタが管理するポインタをオーナー指定ポインタとしてシリアライズします。シリアライズする手順は通常のクラスと同じですが、少し注意事項があります。
52 
53 スマート・ポインタをシリアライズするために、theolizer/memory.hをインクルードして下さい。
54 
55 @code
56 #include <theolizer/memory.h>
57 @endcode
58 
59 - unique_ptr<br>
60 unique_ptrは通常通りシリアライズ可能です。<br>
61 なお、`std::unique_ptr<T[]>`はサポートしていません。T[]をシリアライズするためには、その要素数が必要ですが管理されていないため、対応できないのです。<br>
62 
63 - shared_ptr<br>
64 同じインスタンスを管理するshared_ptrを保存し回復すると、その状況を回復します。<br>
65 なお、同じインスタンスを管理するshared_ptrは同じオジェクト追跡単位内でシリアライズするようにして下さい。ポリモーフィズムにより回復処理中にポインタが置き換わった場合、シリアライズされていなかったshared_ptrとの共有状態が解除されます。<br>
66 
67 - weak_ptr<br>
68 バインドしているshared_ptrをシリアライズします。ですので、shared_ptrと同様同じインスタンスを管理するものは同じオブジェクト追跡単位内でシリアライズして下さい。
69 
70 <b>スマート・ポインタの保存と回復処理（source/reference_and_test/basic2/test_support_stl.cpp）</b><br>
71 unique_ptr、shared_ptr、weak_ptrの保存／回復のサンプル・ソースです。
72 
73 @snippet basic2/test_support_stl.cpp SmartPtr
74 
75 //############################################################################
76 @section HowToUseContainer 2.標準コンテナのシリアライズ方法
77 //############################################################################
78 
79 Theolizerは各種標準コンテナのシリアライズにも対応しています。<br>
80 
81 - それぞれ対応するインクルードが必要です。
82 - 一部の標準コンテナについて<br>
83 保存先指定による合成回復、および、各要素を被ポインタとすること（他のシリアライズ対象のポインタから指す）に対応しています。
84 
85 下記にその対応表を示します。
86 
87 |標準コンテナ|ヘッダ|被ポインタ対応|合成回復|
88 |------------|------|--------------|--------|
89 |`array`|`<theolizer/array.h>`|YES|YES|
90 |`vector`|同上|YES|YES|
91 |`vector<bool>`|`<theolizer/vector.h>`|NO|NO|
92 |`deque`|`<theolizer/deque.h>`|YES|YES|
93 |`forward_list`|`<theolizer/forward_list.h>`|YES|YES|
94 |`list`|`<theolizer/list.h>`|YES|YES|
95 |`set`|`<theolizer/set.h>`|NO|NO|
96 |`multiset`|同上|NO|NO|
97 |`map`|`<theolizer/map.h>`|YES|YES|
98 |`multimap`|同上|NO|NO|
99 |`unordered_set`|`<theolizer/unordered_set.h>`|NO|NO|
100 |`unordered_multiset`|同上|NO|NO|
101 |`unordered_map`|`<theolizer/unordered_map.h>`|YES|YES|
102 |`unordered_multimap`|同上|NO|NO|
103 
104 特記事項が幾つかあります。
105 
106 - キー無しコンテナは先頭から順番にデータを回復します。<br>
107 arrayはコンテナを拡張できないので、余分なシリアライス・データは破棄されます。<br>
108 それ以外のキー無しコンテナ（vector, deque, forward_list, list）はシリアライズ・データの方が多い場合、コンテナを拡張して回復します。<br>
109 両者ともシリアライズ・データの方が少ない場合、コンテナの余分な要素はそのまま保持されます。<br>
110 <br>
111 - mapとunordered_mapは合成回復に対応しています。<br>
112 これらはキー基準で回復しますので、保存先指定機能で分割したファイルを別々に編集した場合でも、同じキーのデータを同じインスタンスへ合成回復できます。<br>
113 <br>
114 - setとunordered_setについて<br>
115 これらは回復する際、シリアライズ・データを新規にコンストラクトしたインスタンスへ回復してからコンテナへ追加します。ですので、対応するシリアライズ・データがあった要素は単純回復（非合成回復）します。対応するシリアライズ・データがなかったコンテナの要素はそのまま維持されます。<br>
116 <br>
117 - キーの重複を許すコンテナについて<br>
118 multiset, multimap, unordered_multiset, unordered_multimapは、回復する際、一旦コンテナをクリアしてから、シリアライズ・データを回復します。これはキーの重複を許すため、シリアライズ・データと対応するコンテナの要素を特定できないためです。<br>
119 
120 @subsection HowToUseContainer21 2-1.標準コンテナを通常の使い方で保存／回復するサンプル・ソース
121 
122 <b>サンプル・ソース（source/reference_and_test/basic2/test_support_stl.cpp）</b><br>
123 
124 @snippet basic2/test_support_stl.cpp ContaierNomal
125 
126 @subsection HowToUseContainer22 2-2.標準コンテナの要素を被ポインタとする保存／回復するサンプル・ソース
127 
128 <b>サンプル・ソース（source/reference_and_test/basic2/test_support_stl.cpp）</b><br>
129 
130 @snippet basic2/test_support_stl.cpp ContaierPointee
131 
132 @subsection HowToUseContainer23 2-3.標準コンテナの要素を合成回復サンプル・ソース
133 
134 <b>サンプル・ソースsource/reference_and_test/basic2/test_support_stl.cpp）</b><br>
135 
136 @snippet basic2/test_support_stl.cpp ContaierDestinations
137 
138 <br>
139 //############################################################################
140 @section TestContainer 3.網羅的な使用例（自動テスト）の説明
141 //############################################################################
142 
143 スマート・ポインタと標準コンテナのサポートについて、全てのシリアライザ、全ての書式でテストしています。
144 また、保存先指定で分割保存後、合成回復のテストも同様に全てのシリアライザ、全ての書式でテストしています。
145 
146 @subsection TestContainer31 3-1.スマート・ポインタ
147 
148 @subsubsection TestContainer311 3-1-1.通常
149 
150 unique_ptrとweak_ptrについては、使い方説明にて保存／回復テストしています。
151 
152 オーナー指定ポインタを回復する時、例えばある派生クラスAのインスタンスを指しているポインタへ異なる派生クラスBを回復する場合があります。その時、元の派生クラスAのインスタンスは解放し、派生クラスBのインスタンスをコンストラクトして回復します。
153 しかし、shared_ptrは他のshared_ptrとポイント先を共有しているため元のインスタンスを解放できません。そのための対策を実装していいます。（shared_ptr回復中フラグを設け、元のインスタンスはshared_ptr処理側で管理しています。)
154 その機能のテストのため、回復先のポインタが下記の３種類についてテストします。
155 - nullptrの時
156 - 回復するものと同じインスタンスを指している時
157 - 回復するものと異なるインスタンスを指している時
158 
159 この時のシリアライズ対象クラスはSmartBaseとそれを派生したSmartDerivedです。
160 
161 そして、それぞれについて、手動(トップ・レベル)、自動、手動(非トップ・レベル)による保存／回復をテストしています。
162 そのための補助クラスとして、SmartTestAutoとSmartTestManualを使っています。
163 
164 <b>source/reference_and_test/basic2/test_support_stl.cpp</b>でテスト関数を定義してます。<br>
165 
166 1. 保存処理<br>
167 template<class tSerializer><br>
168 void saveSupportStl(tSerializer& iSerializer)の前半<br>
169 <br>
170 
171 2. 回復処理<br>
172 template<class tSerializer><br>
173 void loadSupportStl(tSerializer& iSerializer)の前半<br>
174 
175 @subsubsection TestContainer312 3-1-2.合成回復
176 
177 unique_ptrとshared_ptrについて、それが管理するクラスをDestAとDestBに分割して保存し合成回復できることを確認しています。
178 <b>source/reference_and_test/basic2/test_support_stl.cpp</b>でテスト関数を定義してます。<br>
179 
180 1. 保存処理<br>
181 template<class tSerializer><br>
182 void saveSupportStlDestinations(tSerializer& iSerializer)の前半<br>
183 <br>
184 
185 2. 回復処理<br>
186 template<class tSerializer><br>
187 void saveSupportStlDestinations(tSerializer& iSerializer)の前半<br>
188 
189 @subsection TestContainer32 3-2.標準コンテナのテスト
190 
191 @subsubsection TestContainer321 3-2-1.通常
192 
193 サポートしている全てのコンテナについて、下記について正しく保存／回復できることをテストしています。
194 
195 - 要素の型はint型とクラス（TestStl）
196 - 被ポインタをサポートしているコンテナについてはオブジェクト追跡
197 
198 unorderedコンテナに対応するため、TestStlはstd::hashクラスを特殊化しています。
199 
200 下記関数テンプレートを使っています。
201 
202 |対象コンテナ|関数テンプレート|
203 |------------|----------------|
204 |array|saveContainerFixed, loadContainerFixed|
205 |vector(bool以外), deque, list, forward_list|saveContainer, loadContainer|
206 |set, multiset, unordered_set, unordered_multiset|saveContainerSet, loadContainerSet|
207 |map, multimap, unordered_map, unordered_multimap|saveContainerMap, loadContainerMap|
208 
209 <b>source/reference_and_test/basic2/test_support_stl.cpp</b>でテスト関数を定義してます。<br>
210 
211 1. 保存処理<br>
212 template<class tSerializer><br>
213 void saveSupportStl(tSerializer& iSerializer)の後半<br>
214 <br>
215 
216 2. 回復処理<br>
217 template<class tSerializer><br>
218 void loadSupportStl(tSerializer& iSerializer)の後半<br>
219 
220 @subsubsection TestContainer322 3-2-2.合成回復
221 
222 合成回復をサポートしている全てのコンテナについて、下記について正しく保存／回復できることをテストしています。
223 
224 - 要素の型はクラス（TestStlDestinations）<br>
225 TestStlDestinationsは保存先としてDestAとDestBを指定したメンバを定義しています。
226 
227 下記関数テンプレートを使っています。
228 
229 |対象コンテナ|関数テンプレート|
230 |------------|----------------|
231 |array|saveFixed, loadFixed|
232 |vector(bool以外), deque, list, forward_list|saveNoKey, loadNoKey|
233 |map, unordered_map|saveKey, loadeKey|
234 
235 <b>source/reference_and_test/basic2/test_support_stl.cpp</b>でテスト関数を定義してます。<br>
236 
237 1. 保存処理<br>
238 template<class tSerializer><br>
239 void saveSupportStlDestinations(tSerializer& iSerializer)の後半<br>
240 <br>
241 
242 2. 回復処理<br>
243 template<class tSerializer><br>
244 void loadSupportStlDestinations(tSerializer& iSerializer)の後半<br>
245 
246 */