バージョンごとのドキュメント一覧

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

<title>Binary String Functions and Operators</title>

This section describes functions and operators for examining and manipulating binary strings, that is values of type <type>bytea</type>. Many of these are equivalent, in purpose and syntax, to the text-string functions described in the previous section. 本節ではバイナリ文字列、すなわちbytea型の値を調べたり操作するための関数と演算子について説明します。 これらの多くは前節で説明されているテキスト文字列関数と、目的と構文という意味で同じです。

<acronym>SQL</acronym> defines some string functions that use key words, rather than commas, to separate arguments. Details are in <xref linkend="functions-binarystring-sql"/>. <productname>PostgreSQL</productname> also provides versions of these functions that use the regular function invocation syntax (see <xref linkend="functions-binarystring-other"/>). SQLでは、引数の区切りにカンマではなくキーワードを使う文字列関数を、いくつか定義しています。 詳細は表 9.11を参照してください。 またPostgreSQLは、これらの関数に対して通常の関数呼び出し構文を使用するバージョンを提供します(表 9.12を参照してください)。

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

<title><acronym>SQL</acronym> Binary String Functions and Operators</title>

Function/Operator 関数/演算子

Description 説明

Example(s)

bytea || byteabytea

Concatenates the two binary strings. 2つのバイナリ文字列を結合します。

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

bit_length ( bytea ) → integer

Returns number of bits in the binary string (8 times the <function>octet_length</function>). 文字列中のビット数を返します(octet_lengthの8倍)。

bit_length('\x123456'::bytea)24

btrim ( bytes bytea, bytesremoved bytea ) → bytea

Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start and end of <parameter>bytes</parameter>. bytesからbytesremovedに現れるバイトのみを含む最長の文字列を先頭と末尾から取り除きます。

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

ltrim ( bytes bytea, bytesremoved bytea ) → bytea

Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start of <parameter>bytes</parameter>. bytesの先頭からbytesremovedに現れるバイトだけを含む最長の文字列を削除します。

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

octet_length ( bytea ) → integer

Returns number of bytes in the binary string. バイナリ文字列中のバイト数を返します。

octet_length('\x123456'::bytea)3

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

Replaces the substring of <parameter>bytes</parameter> that starts at the <parameter>start</parameter>'th byte and extends for <parameter>count</parameter> bytes with <parameter>newsubstring</parameter>. If <parameter>count</parameter> is omitted, it defaults to the length of <parameter>newsubstring</parameter>. bytesstart番目のバイトからcountバイトをnewsubstringで置き換えます。 countを省略するとnewsubstringの長さがデフォルトになります。

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

position ( substring bytea IN bytes bytea ) → integer

Returns first starting index of the specified <parameter>substring</parameter> within <parameter>bytes</parameter>, or zero if it's not present. bytes中のsubstringで指定する最初の文字列開始位置を返します。その文字列が存在しなければ0を返します。

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

rtrim ( bytes bytea, bytesremoved bytea ) → bytea

Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the end of <parameter>bytes</parameter>. bytesからbytesremovedに現れるバイトのみを含む最長の文字列を末尾から取り除きます。

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

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

Extracts the substring of <parameter>bytes</parameter> starting at the <parameter>start</parameter>'th byte if that is specified, and stopping after <parameter>count</parameter> bytes if that is specified. Provide at least one of <parameter>start</parameter> and <parameter>count</parameter>. startが指定されていればstart番目の文字で始まるbytesの部分文字列を返します。 countが指定されていればcount数の文字で停止します。 少なくともstartcountのどちらかを指定してください。

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

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

Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start, end, or both ends (<literal>BOTH</literal> is the default) of <parameter>bytes</parameter>. bytesからbytesremovedに現れるバイトのみを含む最長の文字列を先頭、末尾、あるいはその両方(BOTHがデフォルト)から取り除きます。

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

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

This is a non-standard syntax for <function>trim()</function>. これはtrim()の非標準構文です。

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


Additional binary string manipulation functions are available and are listed in <xref linkend="functions-binarystring-other"/>. Some of them are used internally to implement the <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-binarystring-sql"/>. この他、表 9.12に列挙するバイナリ文字列操作関数が使えます。 そのいくつかは、表 9.11で列挙した標準SQLの文字列関数を実装するため、内部的に使用されます。

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

<title>Other Binary String Functions</title>

Function 関数

Description 説明

Example(s)

bit_count ( bytes bytea ) → bigint

Returns the number of bits set in the binary string (also known as <quote>popcount</quote>). バイナリ文字列中のセットされているビットの数を返します(popcountとしても知られています)。

bit_count('\x1234567890'::bytea)15

get_bit ( bytes bytea, n bigint ) → integer

Extracts <link linkend="functions-zerobased-note">n'th</link> bit from binary string. バイナリ文字列のn番目のビットを取り出します。

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

get_byte ( bytes bytea, n integer ) → integer

Extracts <link linkend="functions-zerobased-note">n'th</link> byte from binary string. バイナリ文字列のn番目のバイトを取り出します。

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

length ( bytea ) → integer

Returns the number of bytes in the binary string. バイナリ文字列のバイト数を返します。

length('\x1234567890'::bytea)5

length ( bytes bytea, encoding name ) → integer

Returns the number of characters in the binary string, assuming that it is text in the given <parameter>encoding</parameter>. 与えられたencodingのテキストであると見なしてバイナリ文字列中の文字数を返します。

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

md5 ( bytea ) → text

Computes the MD5 <link linkend="functions-hash-note">hash</link> of the binary string, with the result written in hexadecimal. バイナリ文字列のMD5ハッシュ計算し、16進数で結果を返します。

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

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

Sets <link linkend="functions-zerobased-note">n'th</link> bit in binary string to <parameter>newvalue</parameter>. バイナリ文字列のn番目のビットをnewvalueにします。

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

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

Sets <link linkend="functions-zerobased-note">n'th</link> byte in binary string to <parameter>newvalue</parameter>. バイナリ文字列のn番目のバイトをnewvalueにします。

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

sha224 ( bytea ) → bytea

Computes the SHA-224 <link linkend="functions-hash-note">hash</link> of the binary string. バイナリ文字列のSHA-224 ハッシュを計算します。

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

sha256 ( bytea ) → bytea

Computes the SHA-256 <link linkend="functions-hash-note">hash</link> of the binary string. バイナリ文字列のSHA-256 ハッシュを計算します。

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

sha384 ( bytea ) → bytea

Computes the SHA-384 <link linkend="functions-hash-note">hash</link> of the binary string. バイナリ文字列のSHA-384 ハッシュを計算します。

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

sha512 ( bytea ) → bytea

Computes the SHA-512 <link linkend="functions-hash-note">hash</link> of the binary string. バイナリ文字列のSHA-512 ハッシュを計算します。

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

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

Extracts the substring of <parameter>bytes</parameter> starting at the <parameter>start</parameter>'th byte, and extending for <parameter>count</parameter> bytes if that is specified. (Same as <literal>substring(<parameter>bytes</parameter> from <parameter>start</parameter> for <parameter>count</parameter>)</literal>.) start番目の文字で始まるbytesの部分文字列を取り出します。 countが指定されていればcount数バイトを取り出します。 (substring(bytes from start for count)と同じです。)

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


Functions <function>get_byte</function> and <function>set_byte</function> number the first byte of a binary string as byte 0. Functions <function>get_bit</function> and <function>set_bit</function> number bits from the right within each byte; for example bit 0 is the least significant bit of the first byte, and bit 15 is the most significant bit of the second byte. get_byteset_byteはバイナリ文字列の先頭バイトを0バイトとして数えます。 get_bitset_bitは各バイト内で右からビットを数えます。例えばビット0は先頭バイトの最下位ビットとなり、ビット15は第二バイトの最上位ビットとなります。

For historical reasons, the function <function>md5</function> returns a hex-encoded value of type <type>text</type> whereas the SHA-2 functions return type <type>bytea</type>. Use the functions <link linkend="function-encode"><function>encode</function></link> and <link linkend="function-decode"><function>decode</function></link> to convert between the two. For example write <literal>encode(sha256('abc'), 'hex')</literal> to get a hex-encoded text representation, or <literal>decode(md5('abc'), 'hex')</literal> to get a <type>bytea</type> value. 歴史的な理由により、md5は16進のエンコード値をtext型で返すのに対し、SHA-2関数はbyteaを返します。 両者の間の変換を行うには、関数encodedecodeを使ってください。 たとえば、16進のエンコードのテキスト表現を得るには、encode(sha256('abc'),'hex')byteaを得るにはdecode(md5('abc'), 'hex')としてください。

Functions for converting strings between different character sets (encodings), and for representing arbitrary binary data in textual form, are shown in <xref linkend="functions-binarystring-conversions"/>. For these functions, an argument or result of type <type>text</type> is expressed in the database's default encoding, while arguments or results of type <type>bytea</type> are in an encoding named by another argument. 異なる文字集合(文字符号化方式)間で文字列を変換する関数と、テキスト形式の任意のバイナリデータを表現する関数を表 9.13で示します。 引数あるいは結果のtext型はデータベースのデフォルト文字符号化方式で表現され、bytea型の引数あるいは結果は別の引数で指定する文字符号化方式名で表現されます。

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

<title>Text/Binary String Conversion Functions</title>

Function 関数

Description 説明

Example(s)

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

Converts a binary string representing text in encoding <parameter>src_encoding</parameter> to a binary string in encoding <parameter>dest_encoding</parameter> (see <xref linkend="multibyte-conversions-supported"/> for available conversions). 文字符号化方式src_encodingのバイナリ文字列で表現したテキストを文字符号化方式dest_encodingのバイナリ文字列に変換します。(利用可能な変換は23.3.4を参照してください。)

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

convert_from ( bytes bytea, src_encoding name ) → text

Converts a binary string representing text in encoding <parameter>src_encoding</parameter> to <type>text</type> in the database encoding (see <xref linkend="multibyte-conversions-supported"/> for available conversions). 文字符号化方式src_encodingのバイナリ文字列で表現したテキストをデータベース文字符号化方式のテキストに変換します。(利用可能な変換は23.3.4を参照してください。)

convert_from('text_in_utf8', 'UTF8')text_in_utf8

convert_to ( string text, dest_encoding name ) → bytea

Converts a <type>text</type> string (in the database encoding) to a binary string encoded in encoding <parameter>dest_encoding</parameter> (see <xref linkend="multibyte-conversions-supported"/> for available conversions). text文字列(データベース文字符号化方式で表現)を文字符号化方式dest_encodingのバイナリ文字列に変換します。(利用可能な変換は23.3.4を参照してください。)

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

encode ( bytes bytea, format text ) → text

Encodes binary data into a textual representation; supported <parameter>format</parameter> values are: <link linkend="encode-format-base64"><literal>base64</literal></link>, <link linkend="encode-format-escape"><literal>escape</literal></link>, <link linkend="encode-format-hex"><literal>hex</literal></link>. バイナリデータをテキスト表現形式に符号化します。サポートされているformat値は、base64escapehexです。

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

decode ( string text, format text ) → bytea

Decodes binary data from a textual representation; supported <parameter>format</parameter> values are the same as for <function>encode</function>. テキスト表現からバイナリデータに復号します。 format値はencodeと同じです。

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


The <function>encode</function> and <function>decode</function> functions support the following textual formats: encodedecode関数は以下のテキスト形式をサポートしています。

base64 #

The <literal>base64</literal> format is that of <ulink url="https://datatracker.ietf.org/doc/html/rfc2045#section-6.8">RFC 2045 Section 6.8</ulink>. As per the <acronym>RFC</acronym>, encoded lines are broken at 76 characters. However instead of the MIME CRLF end-of-line marker, only a newline is used for end-of-line. The <function>decode</function> function ignores carriage-return, newline, space, and tab characters. Otherwise, an error is raised when <function>decode</function> is supplied invalid base64 data &mdash; including when trailing padding is incorrect. base64形式はRFC 2045 6.8節のものです。 RFCに従い、符号化された行は76文字に分割されます。 しかし、MIME CRLF行端指示子ではなくて単に改行が行端として使われます。 decode関数はキャリッジ・リターン、改行、空白、タブ文字を無視します。 行端パディング文字が不正な場合を含み、decodeに不正なbase64のデータが与えられるとエラーが生じます。

escape #

The <literal>escape</literal> format converts zero bytes and bytes with the high bit set into octal escape sequences (<literal>\</literal><replaceable>nnn</replaceable>), and it doubles backslashes. Other byte values are represented literally. The <function>decode</function> function will raise an error if a backslash is not followed by either a second backslash or three octal digits; it accepts other byte values unchanged. escape形式はゼロバイトとハイビットがセットされたバイトを8進エスケープシーケンス(\nnn)に変換し、バックスラッシュを二重化します。 他のバイト値は文字通りに表現されます。 バックスラッシュの後が二番目のバックスラッシュあるいは3つの8進数のどちらでもなければ、decode関数はエラーを生じます。他のバイト値はそのまま受け付けます。

hex #

The <literal>hex</literal> format represents each 4 bits of data as one hexadecimal digit, <literal>0</literal> through <literal>f</literal>, writing the higher-order digit of each byte first. The <function>encode</function> function outputs the <literal>a</literal>-<literal>f</literal> hex digits in lower case. Because the smallest unit of data is 8 bits, there are always an even number of characters returned by <function>encode</function>. The <function>decode</function> function accepts the <literal>a</literal>-<literal>f</literal> characters in either upper or lower case. An error is raised when <function>decode</function> is given invalid hex data &mdash; including when given an odd number of characters. hex形式はデータの各々の4ビットを、それぞれのバイトの上位桁を最初にして、0からfの16進数で表現します。 encode関数はa-fの16進数を小文字で出力します。 最小のデータ単位は8ビットなので、encodeが返す文字数は常に偶数です。 decode関数はa-fの文字が大文字でも小文字でも受け付けます。 decode関数は、奇数の文字数を含み、不正な16進データを与えられるとエラーが生じます。

See also the aggregate function <function>string_agg</function> in <xref linkend="functions-aggregate"/> and the large object functions in <xref linkend="lo-funcs"/>. 9.21内の集約関数string_agg33.4内のラージオブジェクト関数も参照してください。