Tools.h++ 7.0 クラスライブラリ・リファレンスマニュアル: RWWString

バナーをクリックすれば目次に戻ります

RWWString

形式

#include <rw/wstring.h>
RWWString a;

説明

このクラスは、ワイド文字の文字列を操作するための非常に強力で使い易い機能を提供します。

このクラスは、標準 C 言語の型 wchar_t のワイド文字を処理します。この型の文字は普通 2 バイトか 4 バイトから成り、従来の "char" 型よりも豊富なコードセットを作成できます (Solaris では wchar_t は 4 バイトです)。wchar_t 型の文字はすべて同じサイズなので、インデックス付けは高速です。

複数バイト文字と ASCII 形式との変換は、RWWString() コンストラクタ、および RWWString メンバー関数の isAscii()、toAscii()、toMultiByte() によって行います。

ストリーム操作は、複数バイトストリーム表現との変換処理を含んでいます。つまり、出力時はワイド文字の文字列を複数バイト文字列に変換し、入力時は複数バイト文字列をワイド文字の文字列に変換します。ワイド文字の文字列の外部表現は通常、複数バイト文字の文字列であるため、記憶領域は節約され、複数バイト文字列を想定している装置とのインタフェースは簡単になります。

このクラスでは、埋め込まれたヌルも有効です。

const wchar_t* 型のパラメータに NULL ポインタを渡してはなりません。ライブラリのデバッグバージョンで検出されます。

このクラスは、書き込み時にコピーを行うという技法を使用して実装します。この技法では、コピーコンストラクタと代入演算子は古いオブジェクトを参照するので、処理は非常に高速です。実際のコピーは、"書き込み" が行われたとき、つまりオブジェクトが変わったときにだけ作成されます。その結果、性能は向上し、コピーの意味はわかりやすくなっています。

RWWSubString というクラスは、部分文字列の抽出と変更をサポートします。

持続性

単純

例

#include <rw/rstream.h>
#include <rw/wstring.h>

main(){
 RWWString a(L"There is no joy in Beantown");
 a.subString(L"Beantown") = L"Redmond";
 cout << a << endl;
 return 0;
}

プログラム出力:

There is no joy in Redmond.

列挙型

enum RWWString::caseCompare { exact, ignoreCase };

比較、検索およびハッシュの各関数において、大文字と小文字を区別する (exact) か、区別しない (ignoreCase) かを指定するのに使用します。

enum RWWString::multiByte_ { multiByte };

複数バイト文字列からワイド文字列への変換処理を制御します。詳細は次のコンストラクタの説明を参照してください。

enum RWWString::ascii_ {ascii };

ASCII 文字列からワイド文字列への変換処理を制御します。詳細は次のコンストラクタの説明を参照してください。

公開コンストラクタ

RWWString();

文字数がゼロの文字列 (空文字列) を作成します。

RWWString(const wchar_t* cs);

ワイド文字列 cs から文字列を作成します。作成された文字列には、最初の終端ワイドヌル文字まで文字列 cs のデータがコピーされます。

RWWString(const wchar_t* cs, size_t N);

ワイド文字列 cs から文字列を作成します。作成された文字列には、ワイド文字列 cs のデータのうち埋め込まれたヌルを含めてちょうど N ワイド文字分がコピーされます。したがって、cs が指すバッファには少なくとも N* sizeof (wchar_t) バイト長または N ワイド文字長が必要です。

RWWString(RWSize_T ic);

長さがゼロの文字列 (空文字列) を作成します。この文字列には容量 ic が与えられます。

RWWString(const RWWString& str);

コピーコンストラクタ。作成された文字列には str のデータがコピーされます。

RWWString(const RWWSubString& ss);

部分文字列から変換します。作成された文字列には ss 部分文字列がコピーされます。

RWWString(char c);

単一文字 c を含む文字列を作成します。

RWWString(char c, size_t N);

N 回繰り返された文字 c を含む文字列を作成します。

RWWString(const char* mbcs, multiByte_ mb);

mbcs に含まれる複数バイト文字列からワイド文字列を作成します。変換は標準 C ライブラリ関数 ::mbstowcs() を使用して行われます。このコンストラクタは次のようにして使用できます。

   RWWString a("\306\374\315\313\306\374", multiByte);

RWWString(const char* acs, ascii_ asc);

acs に含まれる ASCII 文字列からワイド文字列を作成します。MSB を単に取り除くだけで変換を行うため、上記の一般的なコンストラクタよりも処理が高速になります。その際、 RWCString::isAscii() を使用することができます。このコンストラクタは次のようにして使用できます。

   RWWString a("An ASCII character string", ascii);
   RWWString(const char* cs, size_t N, multiByte_ mb);
   RWWString(const char* cs, size_t N, ascii__ asc);

RWWString(const char* cs, size_t N, multiByte_ mb);
RWWString(const char* cs, size_t N, ascii_ asc);

この 2 つのコンストラクタは、埋め込まれたヌルを入れてちょうど N 文字コピーされるという点を除いて、上の 2 つのコンストラクタと似ています。したがって、cs が指すバッファには少なくとも N バイト長が必要です。

型変換

operator
const wchar_t*() const;

ワイドヌル文字で終了する文字列として RWWString のデータをアクセスします。この文字列は RWWString のデータで、削除や変更はできません。RWWString オブジェクト自身が変化したら、以前に返されたポインタ値は無効になるかもしれません。この文字列はワイドヌル文字で終わるため、長さはメンバー関数の length() から与えられるので、注意してください。つまり、この文字列には埋め込まれたヌルを含めることができます。

代入演算子

RWWString&
operator=(const char* cs);

代入演算子。cs が指す、ヌル文字で終わる文字列を自分自身にコピーします。自分自身への参照を返します。

RWWString&
operator=(const RWWString& str);

代入演算子。str のデータをコピーし、自分自身への参照を返します。

RWWString&
operator=(const RWWSubString& sub);

代入演算子。sub のデータをコピーし、自分自身への参照を返します。

RWWString&
operator+=(const wchar_t* cs);

文字列 cs を自分自身に追加し、自分自身への参照を返します。

RWWString&
operator+=(const RWWString& str);

文字列 str を自分自身に追加し、自分自身への参照を返します。

インデックス付け演算子

wchar_t&
operator[](size_t i);
wchar_t
operator[](size_t i) const;

i 番目の文字を返します。最初に記述した可変要素を左辺値として使用できます。インデックス i は 0 ～ (文字列長 -1) の範囲になければなりません。境界検査を行い、インデックスが範囲外にあると RWBoundsErr 型の例外が発生します。

wchar_t&
operator()(size_t i);
wchar_t
operator()(size_t i) const;

i 番目の文字を返します。最初に記述した可変要素を左辺値として使用できます。インデックス i は 0 ～ (文字列長 -1) の範囲になければなりません。<rw/wstring.h> を取り込む前に前処理マクロ RWBOUNDS_CHECK を定義した場合、境界検査を行います。このとき、インデックスが範囲外にあると RWBoundsErr 型の例外が発生します。

RWWSubString
operator()(size_t start, size_t len);
const RWWSubString
operator()(size_t start, size_t len) const;

部分文字列演算子。自分自身の部分文字列で、インデックス start で始まる長さ len の RWWSubString を返します。最初に記述した可変要素を左辺値として使用できます。start + len の長さは文字列長以下でなければなりません。ライブラリが RWDEBUG フラグを使用して作成されていて、かつ start や len が範囲外にあると RWBoundsErr 型の例外が発生します。

公開メンバー関数

RWWString&
append(const wchar_t* cs);

cs が指す、ワイドヌル文字で終わるワイド文字列のコピーを自分自身に追加し、自分自身への参照を返します。

RWWString&
append(const wchar_t* cs, size_t N,);

ワイド文字列 cs のコピーを自分自身に追加します。ワイド文字列中のワイドヌル文字を含めてちょうど N 文字分追加されます。したがって cs が指すバッファには少なくとも N* sizeof(wchar_t) バイト長が必要です。自分自身への参照を返します。

RWWString&
append(const RWWString& cstr);

文字列 cstr のコピーを自分自身に追加し、自分自身への参照を返します。

RWWString&
append(const RWWString& cstr, size_t N);

cstr 文字列の最初の N 文字または cstr 文字列の長さのうち少ない方を自分自身に追加し、自分自身への参照を返します。

size_t
binaryStoreSize() const;

次の大域関数を使用してオブジェクトを格納するのに必要なバイト数を返します。

   RWFile& operator<<(RWFile&, const RWWString&);
size_t
capacity() const;

自分自身の現在の容量を返します。これは文字列がサイズを変更せずに保持できる文字の数で示します。

size_t
capacity(size_t capac);

自分自身の容量を capac に変更することが望ましいことをライブラリに伝えます。実際の容量を返します。

int
collate(const RWWString& str) const;
int
collate(const wchar_t*   str) const;

自分自身に対して POSIX 関数 ::wscoll() を呼び出し、その結果と引数 str に応じて、ゼロ未満、ゼロより大きい、またはゼロの整数を返します。ロケール依存型の照合 (コレート) をサポートします。

int
compareTo(const RWWString& str,
          caseCompare = RWWString::exact) const;
int
compareTo(const wchar_t*   str,
          caseCompare = RWWString::exact) const;

自分自身に対して標準 C ライブラリ関数 ::memcmp() を呼び出し、その結果と引数 str に応じて、ゼロ未満、ゼロより大きい、またはゼロの整数を返します。大文字と小文字を区別するかどうかは caseCompare 引数によって決まります。RWWString::exact か RWWString::ignoreCase のいずれかになります。

RWBoolean
contains(const RWWString& cs,
         caseCompare = RWWString::exact) const;
RWBoolean
contains(const wchar_t* str,
         caseCompare = RWWString::exact) const;

パターンマッチング。cs が自分自身内に存在すれば TRUE を返します。大文字と小文字を区別するかどうかは caseCompare 引数によって決まります。RWWString::exact か RWWString::ignoreCase のいずれかになります。

const wchar_t*
data() const;

ワイドヌル文字で終了する文字列 RWWString のデータにアクセスします。使用には注意を要します。この文字列は RWWString が管理するデータで、削除や変更はできません。RWWString オブジェクト自身が変化したら、以前に返されたポインタ値は無効になるかもしれません。この文字列はワイドヌル文字で終わりますが、長さはメンバー関数の length() から与えられるので注意してください。つまり、この文字列にはヌル文字が埋め込まれているかもしれません。

size_t
first(wchar_t c) const;

自分自身内で最初に現われるワイド文字 c のインデックスを返します。c がなければ、または c を見つける前に文字列中のワイドヌル文字があれば、RW_NPOS を返します。

size_t
first(wchar_t c, size_t) const;

自分自身内で最初に現われるワイド文字 c のインデックスを返します。文字列中のワイドヌル文字を越えても検索を続けます。c がなければ、RW_NPOS を返します。

size_t
first(const wchar_t* str) const;

自分自身内で最初に現われる str 内の任意の文字 c のインデックスを返します。文字列がないか、または str 内の任意の文字列を見つける前に文字列中のワイドヌル文字があれば、RW_NPOS を返します。

size_t
first(const wchar_t* str, size_t N) const;

自分自身内で最初に現われる str 内の任意の文字 c のインデックスを返します。文字列中のワイドヌル文字も含めて正確に N 文字がチェックされるため、str は少なくとも N ワイド文字を含むバッファを指していなければなりません。そのようなパターンが存在しないときは RW_NPOS を返します。

unsigned
hash(caseCompare = RWWString::exact) const;

適切なハッシュ値を返します。

size_t
index(const wchar_t* pat,size_t i=0,
      caseCompare = RWWString::exact) const;
size_t
index(const RWWString& pat,size_t i=0,
      caseCompare = RWWString::exact) const;

パターンマッチング。自分自身内でインデックス i から pat の検索を開始し、最初に検出した pat のインデックスを返します。そのようなパターンが存在しないときは、RW_NPOS を返します。大文字と小文字を区別するかどうかは caseCompare 引数によって決まります。デフォルトは RWWString::exact です。

size_t
index(const wchar_t* pat, size_t patlen,size_t i,
      caseCompare) const;
size_t
index(const RWWString& pat, size_t patlen,size_t i,
      caseCompare) const;

パターンマッチング。自分自身内の pat でインデックス i から最初の patlen 文字を検索し、一致した文字列の先頭のインデックスを返します。そのようなパターンが存在しないときは、RW_NPOS を返します。大文字と小文字を区別するかどうかは caseCompare 引数によって決まります。

RWWString&
insert(size_t pos, const wchar_t* cs);

ワイドヌル文字で終わる文字列 cs のコピーを自分自身の pos の位置に挿入し、自分自身への参照を返します。

RWWString&
insert(size_t pos, const wchar_t* cs, size_t N);

文字列 cs の最初の N ワイド文字のコピーを自分自身の pos の位置に挿入します。N ワイド文字の中にはワイドヌル文字が含まれていてもかまいません。したがって、cs が指すバッファには少なくとも N* sizeof(wchar_t) バイト長が必要です。自分自身への参照を返します。

RWWString&
insert(size_t pos, const RWWString& str);

文字列 str のコピーを自分自身の pos の位置に挿入し、自分自身への参照を返します。

RWWString&
insert(size_t pos, const RWWString& str, size_t N);

文字列 str の最初の N ワイド文字か str 文字列長のうちどちらか少ないほうを自分自身の pos の位置に挿入し、自分自身への参照を返します。

RWBoolean
isAscii() const;

問題なく変換 toAscii() が実行できる、つまり自分自身内の文字がすべて ASCII 文字ならば TRUE を返します。

RWBoolean
isNull() const;

自分自身が長さゼロのワイド文字列 (空文字列) の場合、TRUE を返します。

size_t
last(wchar_t c) const;

文字列内で最後に現れる文字 c のインデックスを返します。c がなければ、RW_NPOS を返します。

size_t
length() const;

自分自身内の文字数を返します。

RWWString&
prepend(const wchar_t* cs);

cs が指す、ワイドヌル文字で終わる文字列のコピーを自分自身の先頭に追加します。自分自身への参照を返します。

RWWString&
prepend(const wchar_t* cs, size_t N,);

文字列 cs のコピーを自分自身の先頭に追加します。文字列中のワイドヌル文字を含めてちょうど N 文字分コピーします。したがって、cs が指すバッファには少なくとも N* sizeof(wchar_t) ワイド文字長が必要です。

RWWString&
prepend(const RWWString& str);

文字列 str を自分自身の先頭に追加し、自分自身への参照を返します。

RWWString&
prepend(const RWWString& cstr, size_t N);

文字列 cstr の最初の N 文字か cstr 文字列長のうちどちらか少ないほうを自分自身の先頭に追加し、自分自身への参照を返します。

istream&
readFile(istream& s);

EOF に達するまで入力ストリーム s から文字を読み込み、自分自身の以前の内容を書き換えます。入力ストリームは複数バイト文字のシーケンスとみなされ、それぞれの文字は標準 C ライブラリ関数 mbtowc() を使用してワイド文字に変換されてから格納されます。ヌル文字は他の文字と同様に扱われます。

istream&
readLine(istream& s, RWBoolean skipWhite = TRUE);

復帰改行か EOF に達するまで入力ストリーム s から文字を読み込み、自分自身の以前の内容を書き換えます。復帰改行は、入力ストリームから取り除かれますが、格納されません。入力ストリームは複数バイト文字のシーケンスとみなされ、それぞれの文字は標準 C ライブラリ関数 mbtowc() を使用してワイド文字に変換されてから格納されます。ヌル文字は他の文字と同様に扱われます。skipWhite 引数が TRUE であれば iostream ライブラリマニピュレータ ws を使用して空白をスキップし、その後文字を保存します。

istream&
readString(istream& s);

EOF かヌル終端文字に達するまで入力ストリーム s から文字を読み込み、自分自身の以前の内容を書き換えます。入力ストリームは複数バイト文字のシーケンスとみなされ、それぞれの文字は標準 C ライブラリ関数 mbtowc() を使用してワイド文字に変換されてから格納されます。

istream&
readToDelim(istream&, wchar_t delim=(wchar_t)'\n');

EOF か区切り文字 delim に達するまで入力ストリーム s から文字を読み込み、自分自身の以前の内容を書き換えます。区切り文字は入力ストリームから取り除かれますが、格納されません。入力ストリームは複数バイト文字のシーケンスとみなされ、それぞれの文字は標準 C ライブラリ関数 mbtowc() を使用してワイド文字に変換されてから格納されます。ヌル文字は、他の文字と同様に扱われます。

istream&
readToken(istream& s);

空白を読み飛ばしてから文字をワイド文字列に格納します。後続の空白か EOF に達するまで、入力ストリーム s から文字を読み込み、自分自身の以前の内容を書き換えます。入力ストリーム内の残りの空白はそのまま残されます。標準 C ライブラリ関数 isspace() で定義された ASCII 空白文字だけが認識されます。入力ストリームは複数バイト文字のシーケンスとみなされ、それぞれの文字は標準 C ライブラリ関数 mbtowc() を使用してワイド文字に変換されてから格納されます。

RWWString&
remove(size_t pos);

pos の位置から文字列の最後までの文字 (長さは length() を超えない) を取り除き、自分自身への参照を返します。

RWWString&
remove(size_t pos, size_t N);

pos の位置から N ワイド文字、または文字列の終わりのうちどちらか (長さは length() を超えない) 速い方を取り除き、自分自身に参照を返します。

RWWString&
replace(size_t pos, size_t N, const wchar_t* cs);

pos の位置から N ワイド文字、または文字列の終わりのうちどちらか (長さは length() を超えない) 速い方を、ワイドヌル文字で終わる文字列 cs で置き換えます。自分自身の参照を返します。

RWWString&
replace(size_t pos, size_t N1,const wchar_t* cs, size_t N2);

pos の位置から N1 文字、または文字列の終わりのうちどちらか (長さは length() を超えない) 速い方を、文字列 cs で置き換えます。コピーされるのは文字列中のワイドヌル文字を含む N2 文字です。したがって、cs が指すバッファには少なくとも N2* sizeof(wchar_t) ワイド文字長が必要です。自分自身への参照を返します。

RWWString&
replace(size_t pos, size_t N, const RWWString& str);

pos の位置から N 文字、または文字列の終わりのうちどちらか (長さは length() を超えない) 速い方を、文字列 str のコピーで置き換えます。自分自身への参照を返します。

RWWString&
replace(size_t pos, size_t N1,
        const RWWString& str, size_t N2);

pos の位置から N1 文字、または文字列の終わりのうちどちらか (長さは length() を超えない) 速い方を、文字列 str の最初の N2 文字または str 文字列長のうちどちらか少ない方で置き換えます。自分自身への参照を返します。

void
resize(size_t n);

自分自身の長さを変更します。必要に応じて、空白 (L' ') を補うか文字列を切り捨てます。

RWWSubString
strip(stripType s = RWWString::trailing, wchar_t c = L' ');
const RWWSubString
strip(stripType s = RWWString::trailing, wchar_t c = L' ')
      const;

自分自身から、その最初、最後または両端にある文字 c を取り除いた部分文字列を返します。最初に記述したほうは左辺値として使用できます。列挙型 stripType は次のような値を取ります。

`stripType`	意味
`leading`	文字列の最初から文字を取り除く
`trailing`	文字列の最後から文字を取り除く
`both`	文字列の最初と最後から文字を取り除く

RWWSubString
subString(const wchar_t* cs, size_t start=0,
          caseCompare = RWWString::exact);
const RWWSubString
subString(const wchar_t* cs, size_t start=0,
          caseCompare = RWWString::exact) const;

文字列 cs が最初に現われる部分文字列を返します。大文字と小文字を区別するかどうかは caseCompare 引数によって決まります。デフォルトは RWWString::exact です。最初に記述したほうは左辺値として使用できます。

RWCString
toAscii() const;

ASCII 文字だけを含む、自分自身と同じ長さの RWCString オブジェクトを返します。自分自身内の非 ASCII 文字は MSB がオフになります。この関数を使用してよいかどうかは、isAscii() で決めます。

RWCString
toMultiByte() const;

標準 C ライブラリ関数 wcstombs() を自分自身に適用した結果を含む RWCString を返します。この関数はいつでも使用できます。

void
toLower();

自分自身内の大文字をすべて小文字に変換します。C ライブラリ関数 towlower() を使用します。

void
toUpper();

自分自身内の小文字をすべて大文字に変換します。C ライブラリ関数 towupper() を使用します。

静的公開メンバー関数

static unsigned
hash(const RWWString& wstr);

wstr.hash(RWWString::exact) により返される wstr のハッシュ値を返します。

static size_t
initialCapacity(size_t ic = 15);

RWWString の最小初期容量を設定し、以前の値を返します。初期設定値は 15 ワイド文字です。値が大きいとメモリーを多く必要としますが、文字列を連結したり読み込むときにサイズ変更を頻繁に行う必要がありません。値が小さいとメモリーは少なくて済みますが、サイズ変更を頻繁に行うことになります。

static size_t
maxWaste(size_t mw = 15);

文字列内の未使用領域の最大容量を設定し、以前の値を返します。初期設定値は 15 ワイド文字です。mw 文字以上消費すると、超過した領域は返還を要求されます。

static size_t
resizeIncrement(size_t ri = 16);

文字列を拡張するためにさらにメモリーが必要になったときのサイズ増分量を設定し、以前の値を返します。初期設定値は 16 ワイド文字です。