他のバージョンの文書 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

9.5. バイナリ文字列関数と演算子

本節ではバイナリ文字列、すなわちbytea型の値を調べたり操作するための関数と演算子について説明します。 これらの多くは前節で説明されているテキスト文字列関数と、目的と構文という意味で同じです。

SQLでは、引数の区切りにカンマではなくキーワードを使う文字列関数を、いくつか定義しています。 詳細は表 9.11を参照してください。 またPostgreSQLは、これらの関数に対して通常の関数呼び出し構文を使用するバージョンを提供します(表 9.12を参照してください)。

表9.11 SQLバイナリ文字列関数と演算子

関数/演算子

説明

bytea || byteabytea

2つのバイナリ文字列を結合します。

'\x123456'::bytea || '\x789a00bcde'::bytea\x123456789a00bcde

bit_length ( bytea ) → integer

文字列中のビット数を返します(octet_lengthの8倍)。

bit_length('\x123456'::bytea)24

octet_length ( bytea ) → integer

バイナリ文字列中のバイト数を返します。

octet_length('\x123456'::bytea)3

overlay ( bytes bytea PLACING newsubstring bytea FROM start integer [ FOR count integer ] ) → bytea

bytesstart番目のバイトからcountバイトをnewsubstringで置き換えます。 countを省略するとnewsubstringの長さがデフォルトになります。

overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)\x12020390

position ( substring bytea IN bytes bytea ) → integer

bytes中のsubstringで指定する最初の文字列開始位置を返します。その文字列が存在しなければ0を返します。

position('\x5678'::bytea in '\x1234567890'::bytea)3

substring ( bytes bytea [ FROM start integer ] [ FOR count integer ] ) → bytea

startが指定されていればstart番目の文字で始まるbytesの部分文字列を返します。 countが指定されていればcount数の文字で停止します。 少なくともstartcountのどちらかを指定してください。

substring('\x1234567890'::bytea from 3 for 2)\x5678

trim ( [ LEADING | TRAILING | BOTH ] bytesremoved bytea FROM bytes bytea ) → bytea

bytesremovedに現れるバイトのみを含む最長の文字列をbytesの最初、最後、あるいはその両方(BOTHがデフォルトです)から取り除きます。

trim('\x9012'::bytea from '\x1234567890'::bytea)\x345678

trim ( [ LEADING | TRAILING | BOTH ] [ FROM ] bytes bytea, bytesremoved bytea ) → bytea

これはtrim()の非標準構文です。

trim(both from '\x1234567890'::bytea, '\x9012'::bytea)\x345678


この他、表 9.12に列挙するバイナリ文字列操作関数が使えます。 そのいくつかは、表 9.11で列挙した標準SQLの文字列関数を実装するため、内部的に使用されます。

表9.12 その他のバイナリ文字列関数

関数

説明

bit_count ( bytes bytea ) → bigint

バイナリ文字列中のセットされているビットの数を返します(popcountとしても知られています)。

bit_count('\x1234567890'::bytea)15

btrim ( bytes bytea, bytesremoved bytea ) → bytea

bytesremovedに現れるバイトのみを含む最長のバイトをbytesの最初と最後から取り除きます。

btrim('\x1234567890'::bytea, '\x9012'::bytea)\x345678

get_bit ( bytes bytea, n bigint ) → integer

バイナリ文字列のn番目のビットを取り出します。

get_bit('\x1234567890'::bytea, 30)1

get_byte ( bytes bytea, n integer ) → integer

バイナリ文字列のn番目のバイトを取り出します。

get_byte('\x1234567890'::bytea, 4)144

length ( bytea ) → integer

バイナリ文字列のバイト数を返します。

length('\x1234567890'::bytea)5

length ( bytes bytea, encoding name ) → integer

与えられたencodingのテキストであると見なしてバイナリ文字列中の文字数を返します。

length('jose'::bytea, 'UTF8')4

ltrim ( bytes bytea, bytesremoved bytea ) → bytea

bytesの先頭からbytesremovedに現れる文字だけを含む最長の文字列を削除します。

ltrim('\x1234567890'::bytea, '\x9012'::bytea)\x34567890

md5 ( bytea ) → text

バイナリ文字列のMD5ハッシュ計算し、16進数で結果を返します。

md5('Th\000omas'::bytea)8ab2d3c9689aaf18​b4958c334c82d8b1

rtrim ( bytes bytea, bytesremoved bytea ) → bytea

bytesの最後からbytesremovedに現れる文字だけを含む最長の文字列を削除します。

rtrim('\x1234567890'::bytea, '\x9012'::bytea)\x12345678

set_bit ( bytes bytea, n bigint, newvalue integer ) → bytea

バイナリ文字列のn番目のビットをnewvalueにします。

set_bit('\x1234567890'::bytea, 30, 0)\x1234563890

set_byte ( bytes bytea, n integer, newvalue integer ) → bytea

バイナリ文字列のn番目のバイトをnewvalueにします。

set_byte('\x1234567890'::bytea, 4, 64)\x1234567840

sha224 ( bytea ) → bytea

バイナリ文字列のSHA-224 ハッシュを計算します。

sha224('abc'::bytea)\x23097d223405d8228642a477bda2​55b32aadbce4bda0b3f7e36c9da7

sha256 ( bytea ) → bytea

バイナリ文字列のSHA-256 ハッシュを計算します。

sha256('abc'::bytea)\xba7816bf8f01cfea414140de5dae2223​b00361a396177a9cb410ff61f20015ad

sha384 ( bytea ) → bytea

バイナリ文字列のSHA-384 ハッシュを計算します。

sha384('abc'::bytea)\xcb00753f45a35e8bb5a03d699ac65007​272c32ab0eded1631a8b605a43ff5bed​8086072ba1e7cc2358baeca134c825a7

sha512 ( bytea ) → bytea

バイナリ文字列のSHA-512 ハッシュを計算します。

sha512('abc'::bytea)\xddaf35a193617abacc417349ae204131​12e6fa4e89a97ea20a9eeee64b55d39a​2192992a274fc1a836ba3c23a3feebbd​454d4423643ce80e2a9ac94fa54ca49f

substr ( bytes bytea, start integer [, count integer ] ) → bytea

start番目の文字で始まるbytesの部分文字列を取り出します。 countが指定されていればcount数バイトを取り出します。 (substring(bytes from start for count)と同じです。)

substr('\x1234567890'::bytea, 3, 2)\x5678


get_byteset_byteはバイナリ文字列の先頭バイトを0バイトとして数えます。 get_bitset_bitは各バイト内で右からビットを数えます。例えばビット0は先頭バイトの最下位ビットとなり、ビット15は第二バイトの最上位ビットとなります。

歴史的な理由により、md5は16進のエンコード値を返すのに対し、SHA-2関数はbyteaを返します。 両者の間の変換を行うには、関数encodedecodeを使ってください。 たとえば、16進のエンコードのテキスト表現を得るには、encode(sha256('abc'),'hex')byteaを得るにはdecode(md5('abc'), 'hex')としてください。

異なる文字集合(文字符号化方式)間で文字列を変換する関数と、テキスト形式の任意のバイナリデータを表現する関数を表 9.13で示します。 引数あるいは結果のtext型はデータベースのデフォルト文字符号化方式で表現され、bytea型の引数あるいは結果は別の引数で指定する文字符号化方式名で表現されます。

表9.13 テキスト/バイナリ文字列変換関数

関数

説明

convert ( bytes bytea, src_encoding name, dest_encoding name ) → bytea

文字符号化方式src_encodingのバイナリ文字列で表現したテキストを文字符号化方式dest_encodingのバイナリ文字列に変換します。(利用可能な変換は24.3.4を参照してください。)

convert('text_in_utf8', 'UTF8', 'LATIN1')\x746578745f696e5f75746638

convert_from ( bytes bytea, src_encoding name ) → text

文字符号化方式src_encodingのバイナリ文字列で表現したテキストをデータベース文字符号化方式のテキストに変換します。(利用可能な変換は24.3.4を参照してください。)

convert_from('text_in_utf8', 'UTF8')text_in_utf8

convert_to ( string text, dest_encoding name ) → bytea

text文字列(データベース文字符号化方式で表現)を文字符号化方式dest_encodingのバイナリ文字列に変換します。(利用可能な変換は24.3.4を参照してください。)

convert_to('some_text', 'UTF8')\x736f6d655f74657874

encode ( bytes bytea, format text ) → text

バイナリデータをテキスト表現形式に符号化します。サポートされているformat値は、base64escapehexです。

encode('123\000\001', 'base64')MTIzAAE=

decode ( string text, format text ) → bytea

テキスト表現からバイナリデータに復号します。 format値はencodeと同じです。

decode('MTIzAAE=', 'base64')\x3132330001


encodedecode関数は以下のテキスト形式をサポートしています。

base64

base64形式はRFC 2045 6.8節のものです。 RFCに従い、符号化された行は76文字に分割されます。 しかし、MIME CRLF行端指示子ではなくて単に改行が行端として使われます。 decode関数はキャリッジ・リターン、改行、空白、タブ文字を無視します。 行端文字が不正な場合を含み、decodeに不正なbase64のデータが与えられるとエラーが生じます。

escape

escape形式はゼロバイトとハイビットがセットされたバイトを8進エスケープシーケンス(\nnn)に変換し、バックスラッシュを二重化します。 他のバイト値は文字通りに表現されます。 バックスラッシュの後が二番目のバックスラッシュあるいは3つの8進数のどちらでもなければ、decode関数はエラーを生じます。他のバイト値はそのまま受け付けます。

hex

hex形式はデータの各々の4ビットを、それぞれのバイトの上位桁を最初にして、0からfの16進数で表現します。 encode関数はa-fの16進数を小文字で出力します。 最小のデータ単位は8ビットなので、encodeが返す文字数は常に偶数です。 decode関数はa-fの文字が大文字でも小文字でも受け付けます。 奇数の文字数を含み、不正な16進データを与えられるとエラーが生じます。

9.21内の集約関数string_agg35.4内のラージオブジェクト関数も参照してください。