edit[[PageOutline]]
= 使い方(version 1.00) =
== 基礎的な知識 ==
全てのユーティリティーは、対応するクラスのヘッダーファイルをインクルードして使います。
{{{
// XMLCh2Transcoder クラスを利用する場合
#include <xercesc_utils/XMLCh2Transcoder.hpp>
}}}
また、全てのクラスは xercesc_utils 名前空間に定義されています。
名前空間を指定した完全修飾名で利用するか、using namespace を利用してください。
=== 完全修飾名を利用した場合 ===
{{{
#include <xercesc_utils/XMLCh2CharTranscoder.hpp>
class SampleHandler : public xercesc::DefaultHandler {
private:
xercesc_utils::XMLCh2CharTranscoder toTranscoder_("Shift_JIS");
...
}}}
=== using namespace を利用した場合 ===
{{{
#include <xercesc_utils/XMLCh2CharTranscoder.hpp>
using namespace xercesc_utils;
class SampleHandler : public xercesc::DefaultHandler {
private:
XMLCh2CharTranscoder toTranscoder_("Shift_JIS");
...
}
}}}
=== メモ: 完全修飾名と using namespace の使い分けについて ===
使い分けとしては、インクルードファイルでは完全修飾名を使用し、ソースファイルでは using namespace を利用するのがスタンダードだと思います。
理由はインクルードファイルで using namespace を使用してしまうと、そのインクルードファイルをインクルードした全てのファイルに using namespace が強制的に適用されてしまうからです。
インクルードファイルの中でも using namespace のスコープを限定すればこの限りではありません。
----
== XMLCh2CharTranscoder クラス ==
Xerces C++ の文字列型（XMLCh*）から C++ 標準の文字列型（char*）へのエンコード指定文字列変換をサポートします。
使い方は以下の通りです。
{{{
#include <xercesc_utils/XMLCh2CharTranscoder.hpp>
using namespace xercesc_utils;
// SAX の xercesc::DefaultHandler の startElement メソッドの例
void SampleHandler::startElement(const XMLCh* const uri, const XMLCh* const localname,
const XMLCh* const qname, const Attributes& attrs) {
XMLCh2CharTranscoder toTranscoder("Shift_JIS");
cout << "startElement: " << toTranscoder.transcode(localname) << endl;
}
}}}
コンストラクタで指定する文字コードは、変換後に期待する文字コードです。
上の例では XML ドキュメントの要素名を Shift_JIS の文字列型 char* 文字列に変換して標準出力に出力しています。
XML 要素の名前や属性値や要素内テキストなど、日本語を含むテキストを取得する際に使用します。
----
=== メモ: 文字列のメモリ管理 ===
XMLCh2CharTranscoder の transcode メソッドは、xercesc_utils::CharPtr 型の文字列を返します。
xercesc_utils::CharPtr 型は、char* をラッピングしたクラスです。
xercesc_utils::CharPtr 型は、char* と同様の扱いができますが、メモリの管理を自分で行ってくれます。
本来、動的に生成した char* 文字列はメモリの解放である delete を自分で行う必要がありますが、xercesc_utils::CharPtr が行ってくれるため開発者はメモリ管理に気を使う必要はありません。
char* 文字列のメモリの有効範囲は、xercesc_utils::CharPtr の変数のスコープと同一です。
取得した文字列をスコープ外に持ち出したい場合は、std::string を利用すると便利です。
以下のように記述することで xercesc_utils::CharPtr が持っている文字列を std::string 文字列に変換できます。
{{{
#include <string>
using namespace std;
#include <xercesc_utils/XMLCh2CharTranscoder.hpp>
using namespace xercesc_utils;
// SampleHandle が string 型のメンバ tagName_ を持っていた場合の例
void SampleHandler::startElement(const XMLCh* const uri, const XMLCh* const localname,
const XMLCh* const qname, const Attributes& attrs) {
XMLCh2CharTranscoder toTranscoder("Shift_JIS");
tagName_ = string(toTranscoder.transcode(localname));
}
}}}
----
=== メモ: 実際に使用する場合は、クラスのメンバやグローバルスコープで使用する ===
事例としてはメソッド内で XMLCh2CharTranscoder クラスのインスタンスを作成しました。この利用方法だと、メソッドが呼び出される毎にインスタンスの生成と破棄が行われます。
そのため実際の例ではクラスのメンバにする等、より広いスコープで定義し利用します。
事例の場合文字コードは基本的に１つのプログラム内では統一的に利用するはずですし、その方が利用方法としては望ましいと言えます。
ただし、グローバルスコープで定義する場合は注意が必要です。
Xerces-C++ の初期化メソッドである XMLPlatformUtils::Initialize() を呼び出すまでは XMLCh2CharTranscoder クラスのインスタンスを作ることはできません。
これを回避するために以下のようなグローバルスコープ用のファクトリメソッドを作りましょう。
{{{
XMLCh2CharTranscoder& getGlobalXMLCh2CharTranscoder() {
XMLCh2CharTranscoder transcoder("Shift_JIS");
return transcoder;
}
}}}
* 参考文献）[isbn:4756118089 Effective C++ 改訂２版(47項 非ローカル static オブジェクトは、使用前に必ず初期化されるようにしよう)]
* 参考文献）[isbn:4894714515 上の本は既に古いので今から買うなら Effective C++ 原著第3版かな…。]
----
== Char2XMLChTranscoder クラス ==
C++ 標準の文字列型（char*）から Xerces C++ の文字列型（XMLCh*）へのエンコード指定文字列変換をサポートします。
XMLCh2CharTranscoder の逆の変換を行います。
使い方は以下の通りです。
{{{
#include <xercesc_utils/XMLCh2CharTranscoder.hpp>
using namespace xercesc_utils;
// SAX の xercesc::DefaultHandler の startElement メソッドの例
void SampleHandler::startElement(const XMLCh* const uri, const XMLCh* const localname,
const XMLCh* const qname, const Attributes& attrs) {
XMLCh2CharTranscoder toTranscoder("Shift_JIS");
Char2XMLChTranscoder fromTranscoder("Shift_JIS");
cout << "attrs: " << toTranscoder.transcode(attrs.getValue(fromTranscoder.transcode("名前"))) << endl;
}
}}}
コンストラクタで指定する文字コードは、変換対象文字列（char*）の文字コードです。
上の例では XML ドキュメントの "名前" 属性の値を標準出力に出力しています。
上記ファイルの文字コードは、Shift_JIS でありファイル中にあるシンボル "名前" も Shift_JIS であることを想定しています。
メモリ管理についても XMLCh2CharTranscoder クラスと同じく自動で行われます。したがって、開発者はメモリ管理に気を使う必要はありません。
----
== XMLCh2Char, Char2XMLCh クラス ==
XMLCh2Char は、Xerces C++ の文字列型（XMLCh*）から C++ 標準の文字列型（char*）への簡易文字列変換をサポートします。
Char2XMLCh は、C++ 標準の文字列型（char*）から Xerces C++ の文字列型（XMLCh*）への簡易文字列変換をサポートします。
使い方は以下の通りです。
{{{
#include <xercesc_utils/Char2XMLCh.hpp>
#include <xercesc_utils/XMLCh2Char.hpp>
using namespace xercesc_utils;
// SAX の xercesc::DefaultHandler の startElement メソッドの例
void SampleHandler::startElement(const XMLCh* const uri, const XMLCh* const localname,
const XMLCh* const qname, const Attributes& attrs) {
cout << "attrs: " << Char2XMLCh(attrs.getValue(Char2XMLCh("name"))) << endl;
}
}}}
上の例では XML ドキュメントの "name" 属性の値を標準出力に出力しています。
XML ドキュメントの "name" 属性の値に日本語は使われていないことを想定しています。
XMLCh2CharTranscoder や Char2XMLChTranscoder に似ていますが、より簡単に変換ができるのが特徴です。
ただし、日本語文字列の変換ができないという制約があります。
日本語を使用しない場合の簡潔なコードの記述をサポートします。
メモリ管理についても他と同じく自動で行われます。したがって、開発者はメモリ管理に気を使う必要はありません。
XMLCh2Char で得た文字列（char*）を外に持ち出したい場合は、XMLCh2CharTranscoder を利用したときのように std::string に変換して利用すると便利です。
----