この項では、文字列のフォーマット関数について説明します。
表20-7 文字列のフォーマット関数
関数 | 用途 |
---|---|
|
OCIFormatパッケージを初期化します。 |
|
テキスト文字列を指定されたテキスト・バッファに書き込みます。 |
|
OCIFormatパッケージを終了します。 |
用途
OCIFormatパッケージを初期化します。
構文
sword OCIFormatInit( void *hndl, OCIError *err);
パラメータ
OCI環境ハンドルまたはユーザー・セッション・ハンドルです。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。
コメント
このルーチンをコールしてから、他のOCIFormatルーチンをコールする必要があります。またこのルーチンは1度しかコールできません。
戻り値
OCI_SUCCESS
OCI_INVALID_HANDLE
OCI_ERROR
用途
OCIFormatパッケージを終了します。
構文
sword OCIFormatTerm( void *hndl, OCIError *err);
パラメータ
OCI環境ハンドルまたはユーザー・セッション・ハンドルです。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。
コメント
この関数は、OCIFormatパッケージを使用しなくなってからコールする必要があります。また、コールは1度しか実行できません。
戻り値
OCI_SUCCESS
OCI_INVALID_HANDLE
OCI_ERROR
用途
送られた引数リストを使用し、指定のフォーマット文字列に従って、指定されたテキスト・バッファにテキスト文字列を書き込みます。
構文
sword OCIFormatString( void *hndl, OCIError *err, OraText *buffer, sbig_ora bufferLength, sbig_ora *returnLength, const OraText *formatString,... );
パラメータ
OCI環境ハンドルまたはユーザー・セッション・ハンドルです。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。
文字列を含むバッファです。
バイトで示したバッファの長さです。
バッファに書き込むバイト数です(終了のNULL
を除く)。
リテラル・テキストとフォーマット指定の任意の組合せを指定できるフォーマット文字列です。フォーマット指定は%文字で区切られ、任意の数(ない場合もあります)のオプションのフォーマット修飾子が続き、必須の書式コードで終了します。フォーマット文字列が%で終わる場合、つまり、後続のフォーマット修飾子やフォーマット指定がない場合、アクションは実行されません。使用可能なフォーマット修飾子および書式コードについては、次に説明します。
フォームOCIFormat type wrapper
(variable
)の引数の変数値です。このvariable
は、使用される値を含む変数にする必要があります。定数値または式はOCIFormat type wrappers
の引数にはできません。使用可能なOCIFormat type wrappers
を次にリストします。引数リストはOCIFormatEnd
で終了してください。
OCIFormatUb1(ub1 variable);
OCIFormatUb2(ub2 variable);
OCIFormatUb4(ub4 variable);
OCIFormatUword(uword variable);
OCIFormatUbig_ora(ubig_ora variable);
OCIFormatSb1(sb1 variable);
OCIFormatSb2(sb2 variable);
OCIFormatSb4(sb4 variable);
OCIFormatSword(sword variable);
OCIFormatSbig_ora(sbig_ora variable);
OCIFormatEb1(eb1 variable);
OCIFormatEb2(eb2 variable);
OCIFormatEb4(eb4 variable);
OCIFormatEword(eword variable);
OCIFormatChar (text variable);
OCIFormatText(const text *variable);
OCIFormatDouble(double variable);
OCIFormatDvoid(const dvoid *variable);
OCIFormatEnd
コメント
このルーチンの最初のコールを実行する前に、OCIFormatInit
ルーチンのコールを実行してOCIFormat
パッケージを使用できるように初期化する必要があります。このルーチンが必要なくなった場合は、OCIFormatTerm
ルーチンをコールしてOCIFormat
パッケージを終了します。
フォーマット修飾子
フォーマット修飾子は、より詳細な出力が可能になるようにフォーマット指定を変更または拡張します。フォーマット修飾子は任意の順序で指定でき、すべてオプションです。
表20-8 フォーマット修飾子フラグ
フラグ | 操作 |
---|---|
|
フィールド内の出力を左揃えにします。 |
|
数値型の符号('+'または'-')を常に出力します。 |
|
数値の符号が出力されない場合は、符号の位置が空白で出力されます。 |
|
数値出力に空白ではなく0(ゼロ)を埋め込みます。 |
'+'
および' '
の両方のフラグが同じフォーマット指定で使用されている場合、' '
フラグは無視されます。
'-'
および'0'
の両方のフラグが同じフォーマット指定で使用されている場合、'-'
フラグは無視されます。
代替出力:
8進書式コードの場合は、先行0(ゼロ)を追加します。
16進書式コードの場合は、先行'0x'を追加します。
浮動小数点書式コードの場合は、出力で常に基数文字が利用されます。
フィールド幅
<w>
。この<w>
は最小のフィールド幅を指定する数値です。変換された引数は、この最小幅で出力され、必要に応じてより広い幅にもできます。変換された引数がフィールド幅よりも少ない表示位置を使用する場合は、フィールド幅を調整するために左側(左文字位置の場合は右側)に埋め込まれます。埋込み文字は通常空白ですが、0(ゼロ)の埋込みフラグが指定された場合は0(ゼロ)になります。特殊文字'*'
は<w>
のかわりに使用でき、現行の引数はフィールド幅値のために使用されることを示します。実際のフィールドまたは精度が次の後続引数として続きます。
精度
.<p>
は、ピリオドとそれに続く数値<p>
を指定して、文字列から出力する表示位置の最大数、または10進数値の小数点の後の桁、あるいは整数型で出力する場合の最小桁数を指定します(相違を補うために先行0(ゼロ)が追加されます)。特殊文字'*'
は、<p>
のかわりに使用され、現行の引数に精度値があることを示します。
引数索引
(<n>
)。この<n>
は、最初の引数が1の引数リストに対する整数索引です。引数索引がフォーマット指定で指定されていない場合は、最初の引数が選択されます。次に引数索引をフォーマット指定で指定しないときは2番目の引数が選択され、それ以降も同じように続きます。引数索引の使用の有無に関係なくフォーマット指定は任意の順序にすることができ、個別に実行されます。
たとえば、フォーマット文字列"%u %(4)u %u %(2)u %u"
では、OCIFormatString()
に指定された1番目、4番目、2番目、2番目および3番目の引数が選択されます。
書式コード
書式コードは文字列中の引数のフォーマット方法を指定します。
これらの書式コードは大文字にすると、テキスト文字列を除くすべてのアルファベット文字が大文字で出力されます。テキスト文字列には、この変換は行われません。
表20-9 コード
コード | 操作 |
---|---|
|
コンパイラ・キャラクタ・セット内のシングルバイト文字。 |
|
符号付き10進整数。 |
|
フォーム[ |
|
フォーム |
|
変数浮動小数点表記法。 |
|
|
|
符号なし8進整数。 |
|
オペレーティング・システム固有のポインタ印刷出力。 |
|
次の型ではデフォルトの書式コードを使用して引数を出力します。
使用される書式コードは'u'です。
使用される書式コードは'd'です。
使用される書式コードは'c'です。
後続の
使用される書式コードは'g'です。
使用される書式コードは'p'です。
|
|
符号なし10進整数。 |
'x' |
符号なし16進整数。 |
例
/* This example shows the power of arbitrary argument */ /* selection in the context of internationalization. A */ /* date is formatted in 2 different ways for 2 different */ /* countries according to the format string yet the */ /* argument list submitted to OCIFormatString remains */ /* invariant. */ text buffer[255]; ub1 day, month, year; OCIError *err; void *hndl; sbig_ora returnLen; /* Set the date. */ day = 10; month = 3; year = 97; /* Work out the date in United States' style: mm/dd/yy */ OCIFormatString(hndl, err, buffer, (sbig_ora)sizeof(buffer), &returnLen (const text *)"%(2)02u/%(1)02u/%(3)02u", OCIFormatUb1(day), OCIFormatUb1(month), OCIFormatUb1(year), OCIFormatEnd); /* Buffer is "03/10/97". */ /* Work out the date in New Zealand style: dd/mm/yy */ OCIFormatString(hndl, err, buffer, (sbig_ora)sizeof(buffer), &returnLen (const text *)"%(1)02u/%(2)02u/%(3)02u", OCIFormatUb1(day), OCIFormatUb1(month), OCIFormatUb1(year), OCIFormatEnd); /* Buffer is "10/03/97". */
戻り値
OCI_SUCCESS
OCI_INVALID_HANDLE
OCI_ERROR