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

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

Copyright 1999 Rogue Wave Software
Copyright 1999 Sun Microsystems, Inc.

## RWBTreeOnDisk

### 形式

      typedef long RWstoredValue ;
      typedef int (*RWdiskTreeCompare)(const char*, const char*,
                                       size_t);

      #include <rw/disktree.h>
      #include <rw/filemgr.h>
      RWFileManager fm("filename.dat");
      RWBTreeOnDisk bt(fm);

### 説明

  クラス RWBTreeOnDisk は、キーと値の連想に順序を付けたコレクションを表します。順序は、外部関数を使用してキーを比較することによって決定します。この関数はユーザー側で設定できます。キーの重複は許可されていません。キーを与えると、対応する値を得ることができます。

  このクラスは、ディスクファイル上で B ツリーを管理するために設計されています。文字配列として定義されているキーと `typedef RWstoredValue` で定義されている値を、B ツリーに格納したり取り出したりします。値は、ファイル内のオブジェクトが格納されている場所へのオフセットを表すことができます。キー長はコンストラクタで設定します。デフォルトは 16 バイトです。

  デフォルトでは、キーはヌル文字で終わります。ただしツリーでは文字列中のヌル文字を利用できるため、結果として複数バイトやバイナリのデータをキーとして使用することができます。その際、次の点を守る必要があります。

  - コンストラクタ内のパラメータ `ignoreNull` には `TRUE` を指定する (下記参照)。
  - キーに使用しているすべてのバッファには、キー長以上の長さを確保する。格納と比較の動作はヌル文字で停止しませんので、注意してください。
  - ヌル文字を無視する比較関数 (`memcmp()` など) を使用する。

  このクラスは、ディスクファイル領域の割り当ておよび解放を管理するクラス RWFileManager と一緒に使用するように設計されています。

  このクラスを作成する際は、コンストラクタ内におけるルートノードの位置を引数 `start` として指定します。この値が `RWNIL` (デフォルト) である場合、その位置は、関数 `start()` を使用して RWFileManager から取り出されます (RWFileManager を参照してください)。また列挙型 `createMode` を使用して、既存のツリーを使用するのか新しくツリーを作成するのかを設定することができます。その結果、ルートノードの位置はメンバー関数 `rootLocation()` を使用して取り出すことができます。

  1 つのディスクファイルに複数の B ツリーを置くことができます。各ツリーには独自のルートノードが必要です。各 B ツリーにルートノードを与えるには、B ツリーの数だけRWBTreeOnDisk を作成する際に `createMode` をそれぞれ `create` に設定します。

  B ツリーの order もコンストラクタ内に設定できます。大きな値を使用するとツリーは浅くなりますが、ディスク領域の使用効率は悪くなります。1 つのノードにおけるエントリの最小数も設定することができます。小さな値を使用するとツリーのバランスを早く整えることができますが、ディスク領域の使用効率は悪くなります。

### 持続性

  なし

### 列挙型

      enum styleMode {V6Style, V5Style};

    この列挙型は、16 バイトのキー長しかサポートしていない V5.X スタイルのツリーとの下位互換性を保つためにコンストラクタが使用するものです。これは新しくツリーを作成するときにのみ使用されます。更新のためにツリーをオープンすると、その型が実行時に自動的に決定されます。

    `V6Style`
      V6.X スタイルのツリーを使用して新しくツリーを初期化します。これがデフォルトです。

    `V5Style`
      V5.X スタイルのツリーを使用して新しくツリーを初期化します。キー長は 16 バイトに固定されます。

      enum createMode {autoCreate, create};

    この列挙型は、新しくツリーを作成するかどうかを決定するためにコンストラクタが使用するものです。

    `autoCreate`
      ルートノードとしてコンストラクタの引数 `start` で与えられている位置を検索し、有効であればそれを使用します。無効であれば新しくツリーを割り当てます。これがデフォルトです。

    `create`
      新しくツリーを作成します。引数 `start` は無視されます。

### 公開コンストラクタ

      RWBTreeOnDisk(RWFileManager& f,
                    unsigned nbuf        = 10,
                    createMode omode     = autoCreate,
                    unsigned keylen      = 16,
                    RWBoolean ignoreNull = FALSE,
                    RWoffset start       = RWNIL,
                    styleMode smode      = V6Style,
                    unsigned halfOrder   = 10,
                    unsigned minFill     = 10);

    ディスク上に B ツリーを作成します。パラメータは次のとおりです。

    `f`
      `B` ツリーが管理されるファイル名。必須のパラメータはこれだけです。

    `nbuf`
      メモリー内にキャッシュ可能なノードの最大数。

    `omode`
      新しく B ツリーを作成するか、または既存の B ツリーをオープ ンして更新する (デフォルト) かの指定。

    `keylen`
      キーのバイト長。既存のツリーをオープンするときは無視されます。

    `ignoreNull`
      キー内の埋め込まれたヌルを許可するかどうかの指定。`FALSE` (デフォルト) の場合、キーは終端のヌル文字で終わります。`TRUE` の場合、すべての `keylen` バイトが有効になります。既存のツリーをオープンするときは無視されます。

    `start`
      ルートノードの位置。`RWNIL` (デフォルト) に設定すると、RWFileManager のメンバー関数 `start()` から返された値を使用します。新しいツリーを作成するときは無視されます。

    `smode`
      作成する B ツリーのタイプの指定。V5.X スタイルとの下位互換性を保つように設定することができます (前述の「列挙型」を参照してください)。デフォルトでは、新しく作成される B ツリーは V6.X スタイルとなります。既存のツリーをオープンするときは無視されます。

    `halfOrder`
      B ツリーの order (すなわち、1 つのノードにおけるエントリ数) の半数。既存のツリーをオープンするときは無視されます。

    `minFill`
      1 つのノードに収めるエントリの最小数。`halfOrder` の値以下でなければなりません。既存のツリーをオープンするときは無視されます。

### 公開メンバー関数

      void
      applyToKeyAndValue((*ap)(const char*,RWstoredValue), void* x);

    コレクション内のすべての項目に対して最小項目から最大項目の順番で、ユーザー定義関数 `ap` をキーと値を引数として呼び出します。この関数には、次のようなプロトタイプが必要です。

          void yourApplyFunction(const char* ky,
                                 RWstoredValue val,void* x);

    関数 `yourApplyFunction` は、キーを変更しない場合があります。`x` はどんな値もとれて、`applyToKeyAndValue()` に引き渡されます。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWoffset
      baseLocation() const;

    RWFileManager 内におけるこのツリーの開始位置のオフセットを返します。これは、1 つの管理ファイルに格納されたいくつかのツリーの 1 つを開きたいときに `start` 引数としてコンストラクタに渡す値です。

      unsigned
      cacheCount() const;

    現在キャッシュされている最大ノード数を返します。

      unsigned
      cacheCount(unsigned newcount);

    キャッシュされるノード数を `newcount` に設定します。古い数を返します。

      void
      clear();

    コレクションからすべての項目を取り除きます。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWBoolean
      contains(const char* ky) const;

    ツリーが `ky` が指す文字列と等しいキーを持っていれば `TRUE` を、持たなければ `FALSE` を返します。このメンバー関数は RWFileErr 例外を送出する場合があります。

      size_t
      entries();

    RWTreeOnDisk の項目数を返します。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWoffset
      extraLocation(RWoffset newlocation);

    RWBTreeOnDisk がアプリケーション固有の情報を保存する場所を `newlocation` に設定します。以前の値を返します。

      RWBoolean
      findKey( const char* ky, RWCString& foundKy)const ;

    `ky` が発見された場合、`TRUE` を返し、それ以外は `FALSE` を返します。成功した場合、検索されたキーは参照として `foundKy` に返されます。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWBoolean
      findKeyAndValue( const char* ky,
                       RWCString& foundKy,
                       RWStoredValue& foundVal)const ;

    `ky` が発見された場合、`TRUE` を返し、それ以外は `FALSE` を返します。成功した場合、検索されたキーは参照として `foundKy` に返され、値は参照として `foundVal` に返されます。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWstoredValue
      findValue(const char* ky)const;

    `ky` が指す文字列と等しいキーの値を返します。等しいキーがなければ `RWNIL` を返します。このメンバー関数は RWFileErr 例外を送出する場合があります。

      int
      height();

    RWBTreeOnDisk の高さを返します。このメンバー関数は RWFileErr 例外を送出する場合があります。

      int
      insertKeyAndValue(const char* ky,RWstoredValue v);

    キーと値の対を B ツリーに追加します。追加が成功すれば `TRUE` を、失敗すれば `FALSE` を返します。このメンバー関数は RWFileErr 例外を送出する場合があります。

      unsigned
      keyLength() const;

    RWBtreeOnDisk のキーの長さを返します。この数は、ツリーがはじめて作成される時に設定され、変更できません。

      unsigned
      minOrder()const;

    この RWBtreeOnDisk にあるルート以外のノードで検出される可能性がある項目の最小数を返します。この数はツリーがはじめて作成されるときに設定され、変更できません。

      unsigned
      nodeSize() const;

    この RWBtreeOnDisk の各ノードにより使用されるバイト数を返します。この数は、キーの長さとツリーの次数から計算され、変更できません。キャッシュするノード数の計算には利用できるようになっています。

      unsigned
      order()const;

    RWBtreeOnDisk の任意のノードに格納される可能性がある項目の最大数の半分の値を返します。ツリーがはじめて作成されるときに設定され、変更できません。このメソッドの名前を「halfOrder」に変更すべきですが、下方互換性のため「order」と呼んでいます。

      RWBoolean
      isEmpty() const;

    RWBTreeOnDisk が空のときは `TRUE` を、空でないときは `FALSE` を返します。

      void
      remove(const char* ky);

    キーが `ky` と一致するキーと値の対を取り除きます。このメンバー関数は RWFileErr 例外を送出する場合があります。

      RWBoolean
      replaceValue(const RWCString& key,
                   const RWstoredValue newval,
                   RWstoredValue& oldVal);

    現在 `key` に関連付けられている RWstoredValue を値 `newval` で置換しようと試みます。成功すると、以前の値が参照により `oldVal` に返され、メソッドが `TRUE` を返します。失敗すると、`FALSE` を返します。

      RWdiskTreeCompare
      setComparison(RWdiskTreeCompare fun);

    比較関数を `fun` に変更し、前の関数を返します。この関数は、次のプロトタイプを持っていなければなりません。

         int yourFun(const char* key1, const char* key2, size_t N);

    最初の引数が 2 番目の引数と比べて小さいか、等しいか、または大きいかに応じて、それぞれ 0 未満、0、0 より大きい値を返します。3 番目の引数はキー長です。選択できる関数の例は、`strncmp()` (デフォルト) か、`strnicmp()` (大文字、小文字を区別しない比較) などです。