Theolizer  Version.1.1.3
serializer for C++ / Do you want to update your classes easily ?
使用方法(全体)

ここでは、Theolizerの使い方を説明します。

TheolizerはAPIの機能テストをできるだけ自動化してます。
そして、APIの機能テストは詳細仕様を規定することでもあります。複雑なプログラムでは文書として読み取ることは困難ですが、単純なプログラムであれば、文書としての機能を果たせるのではないかと考えています。

そこで、各機能についてそれをテストするための多数のテスト群の内、代表的なものを使って説明し、詳細テストの関連部分のソースも提示します。できるだけ読み取るのに苦労しない形式でプログラムを記述し、詳細仕様書として有用であることを目指します。

まず、1~3節で全体的な説明を行い、4節以降で各機能について説明します。


1.名前の付け方

TheolizerのAPIは名前空間に入れています。また、マクロは決まったプリフィクスを付けています。 少し意味を持たせていますので説明します。

1-1.名前空間

ほぼ全てのシンボルを theolizer 名前空間へ入れています。
一部、入れると実装が難しいものについては、シンボルに Theolizer を含みます。
これにより既存のコードと被ることはまずない筈です。

次に、内部的に使用するシンボルは internal 名前空間へ入れています。
これらのシンボルが付けられたクラスや関数等は、Theolizerのアップデート時、上位互換性を考慮しませんので使用しないようお願いします。

1-2.マクロ名

全てのマクロは THEOLIZER_ で始めています。
これにより既存のコードと被ることはまずない筈です。

次に、内部的に使用するマクロは、 THEOLIZER_INTERNAL_ で始めています。
また、Theolizerが自動生成するマクロを、 THEOLIZER_GENERATED_ で始めています。
これらのマクロは、Theolizerのアップデート時、上位互換性を考慮しませんので使用しないようお願いします。

2.基本的な使い方

Theolizerをインストールした後、あなたのデータをTheolizerでシリアライズするために、あなたのプログラムを下記の順序を守るようにして下さい。

  1. Theolizerヘッダをインクルード
  2. シリアライズするクラスとenum型の定義
  3. Theolizerの自動生成ファイルをインクルード
  4. シリアライズ処理

2-1.Theolizerヘッダをインクルード

一部例外(*1)はありますが原則として、シリアライズするクラスとenum型の定義 前にシリアライザのヘッダをインクルードして下さい。

Json形式シリアライザ・ヘッダのインクルードと型定義の例:(source/samples/example/example.cpp)

(*1) 例外:非侵入型(1-2.シリアライズ可能な型についての補足事項)のクラスやenum型の非侵入型完全自動については、シリアライザのヘッダをインクルードする前でも定義できます。

現在、サポートしているシリアライザはJson形式、独自Binary形式、メモリ内専用のFast形式の3種類です。 それぞれ、下記ヘッダをインクールドして下さい。

形式インクルードするヘッダ注意事項
Json形式<theolizer/serializer_json.h>fstreamはテキスト・モードでオープンする
独自Binary形式<theolizer/serializer_binary.h>fstreamはバイナリ・モード(std::ios_base::binary)でオープンする
メモリ内専用Fast形式上記のどちから、もしくは、<theolizer/serializer.h>fstreamはバイナリ・モード(std::ios_base::binary)でオープンする


2-2.シリアライズするクラスとenum型の定義

シリアライズするクラスとenum型の定義後に、Theolizerの自動生成ファイルをインスクルード します。この順序に例外はありません。

なお、シリアライズ対象の型を含まないヘッダ・ファイルは、Theolizerに関する順序制限はありません。

2-3.Theolizerの自動生成ファイルをインクルード

4.Theolizerの仕組み で説明したようにTheolizerはシリアライズに必要なソース・コードを自動生成します。
このファイルはコンパイル単位(通常は.cppファイル)毎に生成され、当該.cppファイルと同じフォルダへ自動的に生成されます。
Theolizerは、バージョンを上げた時に古いクラス定義やenum型定義をここに残します。これにより古いシリアライズ・データを回復できます。
そこで、このファイルをお使いのバージョン管理システム(gitやsvn等)へ登録することをお勧めします。

自動生成するファイルのファイル名は、そのコンパイル単位のファイル名に".theolzier.hpp"を繋げたものです。
例えば、example.cpp の場合は、example.cpp.theolizer.hpp となります。

クラス定義と*.theolizer.hppインクルード指定例:(source/samples/example/example.cpp)

#include <iostream>
#include <fstream>
#include <string>
//----------------------------------------------------------------------------
// 非侵入型完全自動 基底クラス
//----------------------------------------------------------------------------
// ---<<< 本体 >>>---
template<int tInitialValue>
class BaseFullAuto
{
static const int kIntPrivate =tInitialValue;
static const int kIntProtected=tInitialValue+1;
static const int kIntPublic =tInitialValue+2;
int mIntPrivate;
protected:
int mIntProtected;
public:
int mIntPublic;
// コンストラクタ
// (デフォルト・コンストラクタは意図的に無し)
BaseFullAuto(bool iIsValued) :
mIntPrivate( (iIsValued)?kIntPrivate:0),
mIntProtected((iIsValued)?kIntProtected:0),
mIntPublic( (iIsValued)?kIntPublic:0)
{ }
};
//----------------------------------------------------------------------------
// 侵入型半自動 基底クラス
//----------------------------------------------------------------------------
template<int tInitialValue>
class BaseHalfAuto
{
public:
// デフォルト・コンストラクタ
BaseHalfAuto()
{ }
// コンストラクタ
// (デフォルト・コンストラクタは意図的に無し)
BaseHalfAuto(bool)
{ }
// 侵入型半自動 指定
THEOLIZER_INTRUSIVE_TEMPLATE
(
CS,
(template<int tInitialValue>),
(BaseHalfAuto<tInitialValue>),
1,
BaseHalfAutoPrimary
);
};
class BaseHalfAuto2621
{
public:
// デフォルト・コンストラクタ
BaseHalfAuto2621()
{ }
// コンストラクタ
// (デフォルト・コンストラクタは意図的に無し)
BaseHalfAuto2621(bool)
{ }
// 侵入型半自動 指定
THEOLIZER_INTRUSIVE(CS, (BaseHalfAuto2621), 1);
};
//----------------------------------------------------------------------------
// 非侵入型手動 基底クラス
//----------------------------------------------------------------------------
// ---<<< 本体 >>>---
template<int tInitialValue>
class BaseManual
{
static const int kIntPublic =tInitialValue+2;
public:
int mIntPublic;
// コンストラクタ
// (デフォルト・コンストラクタは意図的に無し)
BaseManual(bool iIsValued=false) :
mIntPublic((iIsValued)?kIntPublic:0)
{ }
// 一致チェック
void checkPublic(bool iIsValued=false)
{
THEOLIZER_EQUAL(mIntPublic, ((!iIsValued)?0:kIntPublic));
}
};
// ---<<< シリアライズ用の手動記述 >>>---
//THEOLIZER_NON_INTRUSIVE_ORDER((BaseManual), 1);
THEOLIZER_NON_INTRUSIVE_TEMPLATE_ORDER
(
(template<int tInitialValue>),
(BaseManual<tInitialValue>),
1,
BaseManualPrimary
);
// 以下、test_class_variation.cpp.theolizer.hppから、
// #ifdef THEOLIZER_WRITE_CODE // ###### BaseManual ######の
// #if false // Sample of save/load function.
// から
// #endif // Sample of save/load function.
// までの間をコピーして、saveClassManual()/loadClassManual()の内容を記述。
template<int tInitialValue>
template<class tBaseSerializer, class tTheolizerVersion>
struct TheolizerNonIntrusive<BaseManual<tInitialValue>>::
TheolizerUserDefine<tBaseSerializer, tTheolizerVersion, 1>
{
// Save members.
static void saveClassManual
(
tBaseSerializer& iSerializer,
typename tTheolizerVersion::TheolizerTarget const*const& iInstance
)
{
THEOLIZER_PROCESS(iSerializer, iInstance->mIntPublic);
}
// Load members.
static void loadClassManual
(
tBaseSerializer& iSerializer,
typename tTheolizerVersion::TheolizerTarget*& oInstance
)
{
if (!oInstance) oInstance=new typename tTheolizerVersion::TheolizerTarget(false);
THEOLIZER_PROCESS(iSerializer, oInstance->mIntPublic);
}
};
// ***************************************************************************
// 2重組み合わせテスト
// ***************************************************************************
//----------------------------------------------------------------------------
// 侵入型半自動
//----------------------------------------------------------------------------
class DerivedHalfAuto
{
public:
BaseFullAuto<2611> mBaseFullAutoPublic;
BaseHalfAuto<2621> mBaseHalfAutoPublic;
BaseHalfAuto2621 mBaseHalfAutoPublic2;
BaseManual <2631> mBaseManualPublic;
#if 0
// デフォルト・コンストラクタ
DerivedHalfAuto() :
mBaseFullAutoPublic{false},
mBaseHalfAutoPublic{false},
mBaseManualPublic{false}
{ }
// 保存用コンストラクタ
DerivedHalfAuto(bool) :
mBaseFullAutoPublic{true},
mBaseHalfAutoPublic{true},
mBaseManualPublic{true}
{ }
#endif
// 侵入型半自動 指定
THEOLIZER_INTRUSIVE(CS, (DerivedHalfAuto), 1);
};
#include "example.cpp.theolizer.hpp" // Theolizer自動生成先

この例では、example.cppの頭でクラスを定義していますが、example.hで定義し、#include "example.h" にてインクルードするのが一般的です。

2-4.シリアライズ処理

シリアライズは下記の3つで行います。

  • シリアライザ・インスタンスの生成
  • シリアライズ処理要求(シリアライズするインスタンスを指定する)
  • シリアライザ・インスタンスの破棄

2-4-1.シリアライザ・インスタンスの生成

その際、シリアライズ先のデータ・ストリームを指定します。ファイル・ストリームやTCP/IPストリームを指定して下さい。
保存や送信時はstd::ostreamを、回復や受信時はstd::istreamを与えて下さい。

2-4-2.シリアライズ処理要求

下記マクロでシリアライズします。保存用シリアライザを指定すると保存、回復用シリアライザを指定すると回復動作となります。
これはいつくでも記述して良いです。

THEOLIZER_PROCESS(dSerializer, dInstance)

  • dSerializer : シリアライザのインスタンスを指定します。
  • dInstance : 保存/回復するインスタンスを指定します。

dInstanceを保存/回復します。
ポインタ型を指定した場合は、アドレス回復のためにポイント先のオブジェクト追跡を行います。

THEOLIZER_PROCESS_POINTEE(dSerializer, dInstance)

  • dSerializer : シリアライザのインスタンスを指定します。
  • dInstance : 保存/回復する被ポインタでもあるインスタンスを指定します。

THEOLIZER_PROCESS_OWNER(dSerializer, dInstance)

  • dSerializer : シリアライザのインスタンスを指定します。
  • dInstance : 保存/回復する所有権を持つインスタンスへのポインタを指定します。
参照
オブジェクト追跡について
このようにシリアライザを問わず、全て同じマクロでシリアライズ処理できます。
xmlも将来的にサポートする予定ですが、その際も同じマクロで対応できる筈です。
(マクロなので、#演算によりインスタンス名をC言語文字列として取り出して用います。)

2-4-3.シリアライザ・インスタンスの破棄

最後にシリアライザ・インスタンスを破棄することでシリアライズ処理を完了します。
生成時に例外発生を禁止していた場合に、エラー状態をリセットしないまま破棄すると、プロセスをアボートします。これはエラー状態の見逃しを回避するための仕様です。
例外発生を禁止している場合は、破棄する前には必ずエラー情報をチェクした上で、エラー状態をリセットして下さい。
具体的手順はエラー報告 にて説明します。

ファイルへの保存例:(source/samples/example/example.cpp)

// 保存用コンストラクタ
DerivedHalfAuto(bool) :
mBaseFullAutoPublic{true},

ファイルからの回復例:(source/samples/example/example.cpp)

}


3.各シリアライザの説明

現在、サポートしているシリアライザはJson形式、独自Binary形式、メモリ内専用のFast形式の3種類です。
ここではそれぞれの使い方を説明します。


3-1.共通事項

全てのシリアライザについて共通な事項について説明します。

3-1-1.型チェック・モード

Theolizerのシリアライザは回復時に型が一致していることをチェックできます。
その方法としてシリライズ・データ内に「型名を保存する方法」と「型に割り当てたインデックス番号(TypeIndex)を保存する方法」の2種類を用意しています。

theolizer::CheckMode

列挙値意味
NoTypeCheck型チェック無し
TypeCheck型名による型チェック
TypeCheckByIndexTypeIndexによる型チェック

NoTypeCheckは型情報をシリライズ・データに含みませんのでデータ量が少ない場合の効率は良いです。しかし、メンバ名をヘッダではなくデータ側に含むためデータ量が多くなると効率は悪化します。
TypeCheckはテキスト型の場合、データを目視確認し易いです。データ量が少ない時の効率はNoTypeCheckの次に良いです。
TypeCheckByIndexはデータ量が多い時は3種のCheckModeの中で最大の効率を発揮します。

型情報等の管理データを下記のように記録します。

  • シリアライズ・データのヘッダ部
    NoTypeCheck:型情報を記録しません。
    TypeCheck:クラスについて、各メンバのメンバ名(名前対応時)と型名を記録します。
    TypeCheckByIndex:全ての型について、TypeIndexに対応する型名を記録します。 更にクラスについては、各メンバのメンバ名(名前対応時)とTypeIndexを記録します。

  • シリアライズ・データの各データ部
    NoTypeCheck:クラスについて、各メンバのデータとメンバ名(名前対応時)をセットで記録します。
    TypeCheck:THEOLIZER_PROCESS()マクロで指定したデータと共にその型名を記録します。
    TypeCheckByIndex:THEOLIZER_PROCESS()マクロで指定したデータと共にそのTypeIndexを記録します。

回復時に回復先の変数の型と上記の情報と照らし合わせることで型チェックを行います。

3-1-2.メンバ関数

幾つかの制御のため、各シリアライザは下記のメンバ関数を公開しています。

メンバ名意味
unsigned getGlobalVersionNo() const;処理中のグローバル・バージョン番号を返却します。
void clearTracking() ;オブジェクト追跡の区切り(オブジェクト追跡について 参照)
bool getRequireClearTracking() const;clearTracking()が必要な時trueを返却します。
theolizer::CheckMode getCheckMode() const;現在のCheckModeを返却します。
void setCharIsMultiByte();Windowsにおいて、EncodedStringがtrueのシリアライザにおいて
std::string変数の文字エンコードをMultiByte文字列として処理するかどうかを指定します。
theolizer::ErrorInfo const& getErrorInfo() const;エラー情報を返却します。
bool isError() const;エラーが発生している時trueを返却します。
void resetError();エラー状態を解除します。(3.Theolizerで検出したエラーの通知方法 参照)

3-1-3.プロパティ

各シリアライザは、その属性をプロバティとして提供しています。

プロバティ名意味JsonBinaryFast
IsSaver保存処理用ならtrue、回復処理用ならfalse
EncodedString文字列のエンコードを処理するtruefalsefalse
SupportModifyingクラスやenum型の定義変更に対応するtruetruefalse
BinaryOpenfstreamをstd::ios_base::binaryモードでオープンする必要がある<td>falsetruetrue

プロパテイは以下の構文で受け取ります。

bool property = <シリアライザ・クラス>::hasProperty(theolizer::Property::<プロパティ名>);


3-1-4.EncodedStringについて補足

テキスト型のシリアライザは、文字列を読める形式で記録されます。
そのため、例えばJsonフォーマットはデフォルトではUTF-8でエンコードすると規定されています。
そして、C++の各std::stringシリーズもUnicodeでエンコードされることが期待されます。(そうしないことも可能です。)

そこで、TheolizerのEncodedStringプロパティをサポートしたシリアライザ(現在はJsonのみ)は、下記のようにstd::stringシリーズを処理します。

  • setCharIsMultiByte(false)(デフォルト)
    全ての文字列を特定のUnicodeエンコードで記録する。(JsonシリアライザはUTF-8)
    std::stringはUnicodeでエンコードされているものとして処理する。(そのまま保存/回復する。)
    以下は全てUnicodeへ変換して保存し、読み出し後当該エンコードへ変換する。
    std::wstringはUTF-16かUTF-32(wchar_tのサイズによる)でエンコードされているものとして処理する。
    std::u16stringはUTF-16でエンコードされているものとして処理する。
    std::u32stringはUTF-32でエンコードされているものとして処理する。

  • setCharIsMultiByte(true)
    std::stringはMultiByte文字列としてエンコードされているものとして処理する。(Unicodeへ変換して保存/回復する。)
    その他は、デフォルトと同じ。

つまり、例えば、UTF-8でエンコードされたstd::string型の変数を保存し、それをUTF-16でエンコードされたstd::u16string型の変数へ回復できます。

サンプル・ソース(source/reference_and_test/basic/test_basic_process.cpp)

#if defined(_WIN32)
// CP932で"[こんにちは。]"
const char gHelloCP932[] = "\x5B\x82\xB1\x82\xF1\x82\xC9\x82\xBF\x82\xCD\x81\x42\x5D";
#else
// UTF-8で"[こんにちは。]" 非Windows用
const char gHelloCP932[] = u8"[こんにちは。]";
#endif
void tutoriseBasic()
{
//----------------------------------------------------------------------------
// 保存
//----------------------------------------------------------------------------
{
std::ofstream aStream("tutorise_basic.json");
theolizer::JsonOSerializer<> aSerializer(aStream);
// ---<<< Shift-JISコードのテスト >>>---
// MultiByte指定
aSerializer.setCharIsMultiByte(true);
std::string aString = gHelloCP932;
THEOLIZER_PROCESS(aSerializer, aString);
// UTF-8へ戻す
aSerializer.setCharIsMultiByte(false);
aString = u8"ユニコードUTF-8";
THEOLIZER_PROCESS(aSerializer, aString);
// ---<<< 文字列互換テスト >>>---
// charをwchar_t, char16_t, char32_tへ回復
THEOLIZER_PROCESS(aSerializer, aString);
THEOLIZER_PROCESS(aSerializer, aString);
THEOLIZER_PROCESS(aSerializer, aString);
}
//----------------------------------------------------------------------------
// 回復
//----------------------------------------------------------------------------
{
std::ifstream aStream("tutorise_basic.json");
theolizer::JsonISerializer<> aSerializer(aStream);
// ---<<< Shift-JISコードのテスト >>>---
// MultiByte指定
aSerializer.setCharIsMultiByte(true);
std::string aString = "";
THEOLIZER_PROCESS(aSerializer, aString);
THEOLIZER_EQUAL(aString, gHelloCP932);
// UTF-8へ戻す
aSerializer.setCharIsMultiByte(false);
aString = "";
THEOLIZER_PROCESS(aSerializer, aString);
THEOLIZER_EQUAL(aString, u8"ユニコードUTF-8");
// ---<<< 文字列互換テスト >>>---
std::wstring aWString;
std::u16string aU16String;
std::u32string aU32String;
// charをwchar_t, char16_t, char32_tへ回復
THEOLIZER_PROCESS(aSerializer, aWString);
THEOLIZER_EQUAL(aWString, L"ユニコードUTF-8");
THEOLIZER_PROCESS(aSerializer, aU16String);
THEOLIZER_EQUAL(aU16String, u"ユニコードUTF-8");
THEOLIZER_PROCESS(aSerializer, aU32String);
THEOLIZER_EQUAL(aU32String, U"ユニコードUTF-8");
}
}

3-1-5.BinaryOpenについて補足

バイナリ形式のシリアライザをfstreamで用いる時は、必ずバイナリ・モード(std::ios_base::binary)でfstreamをオープンする必要があります。
Windowsの場合、fstreamがテキスト・モードでオープンされ、ストリームへ数値26(0x1A)が出力されると、0x1AはWindowsではEOFコードなので回復時にEOFエラーになります。また、Windowsで数値10(0x0A)が出力されるとCR LFへ展開されてしまい、適切に回復できません。
このような事態をさけるため、Theolizer側でエラーにしたいのですが、iostreamではそのオープン・モードを確認できないためチェックが困難なのです。

バイナリ形式のシリアライザは、hasProperty(theolzier::Property::BinaryOpen)がtrueになります。 また、各シリアライザはstd::ios_base::openmode型の静的定数kOpenModeを定義しています。 バイナリ形式のシリアライザではstd::ios_base::binary、それ以外のシリアライザで 0 となっています。

サンプル・ソース(source/reference_and_test/basic/test_basic_process.cpp)

// Json
{
std::ofstream aStream("openmode_json.json", theolizer::JsonOSerializer<>::kOpenMode);
theolizer::JsonOSerializer<> aSerializer(aStream);
int aInt=0x1a;
THEOLIZER_PROCESS(aSerializer, aInt);
}
// Binary
{
std::ofstream aStream("openmode_binary.bin", theolizer::BinaryOSerializer<>::kOpenMode);
theolizer::BinaryOSerializer<> aSerializer(aStream);
int aInt=0x1a;
THEOLIZER_PROCESS(aSerializer, aInt);
}


3-2.Json形式(JsonSerializer)

Json形式でシリアライズする場合は、theolizer/serializer_json.hをインクルードして下さい。

3-2-1.保存用JsonSerialzier

通常のコンストラクタ

JsonOSerializer
(
std::ostream& iOStream,
unsigned iGlobalVersionNo=kLastGlobalVersionNo,
CheckMode iCheckMode=CheckMode::NoTypeCheck,
bool iNoPrettyPrint=false,
bool iNoThrowException=false
);

GlobalVersionNo以外のオプションを指定するコンストラクタ

JsonOSerializer
(
std::ostream& iOStream,
CheckMode iCheckMode,
bool iNoPrettyPrint=false,
bool iNoThrowException=false
);
パラメータ名意味
iOStream出力先のストリーム(ofstreamはテキスト・モードでオープンして下さい)
iGlobalVersionNo保存するグローバル・バージョン番号(省略時は最新版)
iCheckMode型チェック・モード(省略時はNoTypeCheck)
iNoPrettyPrint整形出力しない時true(省略時はfalse)
iNoThrowException例外禁止時true(省略時はfalse)

専用継承関数

void setCharIsMultiByte(bool iCharIsMultiByte);
iCharIsMultiByte=trueの時、std::stringをWindowsマルチ・バイト文字コードとして取り扱います。
コンストラクト直後はiCharIsMultiByte=falseです。
Windowsのみ機能します。それ以外のOSではUTF-8のままです。

3-2-2.回復用JsonSerialzier

コンストラクタ

JsonISerializer
(
std::istream& iIStream,
bool iNoThrowException=false
);
パラメータ名意味
iIStream入力元のストリーム(ofstreamならテキスト・モードでオープンして下さい)
iNoThrowException例外禁止時true(省略時はfalse)

専用継承関数

void setCharIsMultiByte(bool iCharIsMultiByte);
iCharIsMultiByte=trueの時、std::stringをWindowsマルチ・バイト文字コードとして取り扱います。
コンストラクト直後はiCharIsMultiByte=falseです。
Windowsのみ機能します。それ以外のOSではUTF-8のままです。


3-3.独自Binary形式(BinarySerializer)

独自Binary形式でシリアライズする場合は、theolizer/serializer_binary.hをインクルードして下さい。

Big Endianでエンコードします。Little Endianの処理系の場合Big Endianとの間で自動変換します。
整数型は値を表現するために十分なバイト数で保存します。例えば、long long型でも値が10ならタグと値で合わせて2バイトで保存します。
浮動小数点型はIEEE754フォーマットのみサポートします。バイト単位でEndian変換します。
long doubleは「radix==2、digits==64、max_exponent==16384」の80ビット拡張精度形式である処理系(gcc)とbinary64である処理系(msvc)に対応しています。
文字コードの変換は行いません。Endianのみ変換してシリアライズします。

3-3-1.保存用BinarySerialzier

通常のコンストラクタ

BinaryOSerializer
(
std::ostream& iOStream,
unsigned iGlobalVersionNo=kLastGlobalVersionNo,
CheckMode iCheckMode=CheckMode::NoTypeCheck,
bool iNoThrowException=false
);

GlobalVersionNo以外のオプションを指定するコンストラクタ

BinaryOSerializer
(
std::ostream& iOStream,
CheckMode iCheckMode,
bool iNoThrowException=false
);
パラメータ名意味
iOStream出力先のストリーム(ofstreamはstd::ios_base::binaryでオープンして下さい)
iGlobalVersionNo保存するグローバル・バージョン番号(省略時は最新版)
iCheckMode型チェック・モード(省略時はNoTypeCheck)
iNoThrowException例外禁止時true(省略時はfalse)

3-3-2.回復用BinarySerialzier

通常のコンストラクタ

BinaryISerializer
(
std::istream& iIStream,
bool iNoThrowException=false
);
パラメータ名意味
iIStream入力元のストリーム(ofstreamはstd::ios_base::binaryでオープンして下さい)
iNoThrowException例外禁止時true(省略時はfalse)


3-4.メモリ内専用のFast形式(FastSerializer)

FastSerializerの使用目的はデータ構造のプログラム内コピーです。外部プログラムとのデータ交換は想定していません

Theolizerが内部的に使用していますので、他のシリアライザのヘッダをインクルードすれば改めてヘッダをインクルードする必要はありません。
もし、他のシリアライザを使用しない時は、theolizer/serializer.hをインクルードして下さい。
また、ストリームはstd::stringstreamを用いることを想定していますが、もしも、ファイル・ストリームを与える場合は必ず std::ios_base::binaryモード でオープンして下さい。
FastSerializerはデータ変換しません。バージョンの相違にも対応していません。
オーナー指定ポインタでない通常のポインタは、ポイント先をシリアライズしていない場合はシャロー・コピーになります。(ポインタ値を単純にコピーする。)

3-4-1.保存用FastSerializer

コンストラクタ

FastOSerializer
(
std::ostream& iOStream,
bool iNoThrowException=false
);
パラメータ名意味
iOStream出力先のストリーム(ofstreamはstd::ios_base::binaryでオープンして下さい)
iNoThrowException例外禁止時true(省略時はfalse)

3-4-2.回復用FastSerializer

コンストラクタ

FastISerializer
(
std::istream& iIStream,
bool iNoThrowException=false
);
パラメータ名意味
iIStream入力元のストリーム(ofstreamはstd::ios_base::binaryでオープンして下さい)
iNoThrowException例外禁止時true(省略時はfalse)

FastSerializerを用いたグローバル関数

template<typename tType>
void copySerializable(tType const& iSource, tType& oDestination);

tType型の変数iSourceをoDestinationへコピーします。
iSourceをFastSerializerでメモリ・ストリームへシリアライズし、続けてoDestinationへ回復することでコピーします。
保存先指定も有効ですので、柔軟なデータ構造のコピーを容易に実装できます。


4.テスト・プログラムの構造


4-1.テスト・プログラムの全体構造

4-1-1.アップデートとバージョンのバリエーション

主な機能テスト・プログラムは、 source/reference_and_test 以下にアップデート/バージョン・アップによる変更(修正版)毎にフォルダを分けて保存しています。

Theolizerはenum型とclass/struct型について定義変更に対応しています。そのテストも行うため、以下のように分類してテストを行います。

  1. 基本的なシリアライズ機能の定義変更を除く様々なバリエーションのテスト
  2. バージョン番号を更新しない定義変更のテスト
  3. バージョン番号を更新する定義変更のテスト

現時点では下記修正版を用意しています。

フォルダ名バージョン番号説明
basic無し基本的なシリアライズ機能の定義変更を除く様々なバリエーションのテスト
basic2無し同上
ver1a1最初のバージョン
ver1b1バージョン番号を変えずに可能な定義変更のテスト
ver1c1バージョン番号を変えるための準備のテスト
ver2a2バージョン番号を変更した時の定義変更のテスト
ver3a3更にバージョン番号を変更のテスト
ver3b3そしてバージョン番号を変えずに定義変更のテスト

class/structでメンバ変数を削除した場合、1つ前のバージョンの自動生成ソースに削除されたことを反映します。なので、最新版と1つ前のバージョンと、更にもう1つ前に問題が出ないかテストするため、3つのバージョンでテストします。

各変更テスト・プログラムは他の変更テスト・プログラムが出力したデータを読み込んで回復できることやエラーを検出できることをテストします。

4-1-2.テストの組み合わせ

下記組み合わせとなります。1行毎に各修正版プログラムが出力するデータ概要を記述しています。
列に記載した各バージョンのプログラムが当該データの回復テストをする時◯印を付けています。

プロ
グラ
バー
ジョン
指定
ファイル名basicbasic2ver1aver1bver1cver2aver3aver3b
basic 指定無し ①-basic-②
basic 1 ①-basic-basic-②
basic2指定無し ①-basic2-②
basic21 ①-basic-basic2-②
ver1a 指定無し ①-ver1a-②
ver1a 1 ①-ver1a-ver1a-②
ver1b 指定無し ①-ver1b-②
ver1b 1 ①-ver1b-ver1b-②
ver1c 指定無し ①-ver1c-②
ver1c 1 ①-ver1c-ver1c-②
ver2a 指定無し ①-ver2a-②
ver2a 1 ①-ver1c-ver2a-②
ver2a 2 ①-ver2a-ver2a-②
ver3a 指定無し ①-ver3a-②
ver3a 1 ①-ver1c-ver3a-②
ver3a 2 ①-ver2a-ver3a-②
ver3a 3 ①-ver3a-ver3a-②
ver3b 指定無し ①-ver3b-②
ver3b 1 ①-ver1c-ver3b-②
ver3b 2 ①-ver2a-ver3b-②
ver3b 3 ①-ver3b-ver3b-②

①にはシリアライザ名と一部のオプションが入ります。

  • json-np (非整形出力)
  • json-pp (整形出力)
  • binary
  • fast

②は以下の通りです。

  • 残りのオプション指定
    • jsonとbinaryの場合
      • NoTypeCheck
      • TypeCheck
      • TypeCheckByIndex
    • fastの場合は、最新版のみ対応でオプションもないため、上記表の「指定無し」のみです。

  • 保存先指定用のサフィックス
    • 無印
    • A(保存先DestA)
    • B(保存先DestB)
    • AB(保存先DestA | DestB)

  • 拡張子
    • jsonの拡張子はjson
    • binaryとfastの拡張子はbin

例えば、json整形出力で、ver3aのプログラムがver1cデータを型チェック無し、保存先指定無しで出力したファイル名は、"json-pp-ver1c-ver3a-NoTypeCheck.json"となります。


4-2.テスト・プログラムの構造

basic、および、各変更テスト用プログラムは共通部分があります。それらはreference_and_testフォルダ直下に配置し、ビルドする時に各サブ・フォルダへコピーしています。

共通部

ファイル関数概要
disable_test.h 各個別テストをディセーブルするシンボル定義。
デバッグ時の便利のために用意。
all_common.h テスト用の全バージョン共通定義。
アップデートとバージョン名とバージョン番号対応表のgVersionListを定義。
main.inc main() 各サブ・フォルダ内のmain.cppから::includeされる。
コマンドライン解析を行い、パラメータが無い時は保存処理、ある時は回復処理を実行する。
4-1節 表の全組み合わせを生成し、callTests()を呼び出す。
callTests()各シリアライザのパラメータを振ってインスタンスを生成し、
saveBasic(), loadBasic(),callSaveDestinations(),callLoadDestinations()を呼び出す。

各サブフォルダ部

ファイル関数概要
main.cpp 各個別フォルダ内テスト関数を呼び出す。
saveBasic()自動テスト基本部の保存処理。個別テストを呼び出す。
loadBasic()自動テスト基本部の回復処理。個別テストを呼び出す。
callSaveDestinations()自動テスト保存先指定部の保存処理。個別テストを呼び出す。
callLoadDestinations()自動テスト保存先指定部の回復処理。個別テストを呼び出す。

各個別テストは別途*.cppファイルを用意し、その中で定義しています。
それぞれについては 使用方法(個別) にて解説します。


4-3.説明で用いるマクロについて

テスト用のマクロはtest_tool.hで定義しています。
その内、使い方の説明(兼 自動テスト)で用いるマクロについてここで簡単に説明します。

1.THEOLIZER_EQUAL(dLhs, dRhs, ...)

(dLhs == dRhs) ならばPASS、そうでないならFAILと判定します。
PASSならば、テストの数とPASS数をインクリメントします。
FAILならば、テストの数とFAIL数をインクリメントし、テストを失敗させます。
また、dRhsとそれ以降のアイテム(1個以上7個まで)を標準出力へ出力します。

下記はシリアライザを使って回復したint型のaIntの値が-3000であることをチェックしています。

int aInt=0;
THEOLIZER_PROCESS(aSerializer, aInt);
THEOLIZER_EQUAL(aInt, 0x1a);