*** sgml.orig/datatype.sgml Mon Nov 19 01:05:00 2001
--- sgml/datatype.sgml Tue Nov 20 01:04:54 2001
***************
*** 965,987 ****
!
! Binary Data
! The bytea data type allows storage of binary data,
! specifically allowing storage of NULLs which are entered as
! '\\000'. The first backslash is interpreted by the
! single quotes, and the second is recognized by bytea and
! precedes a three digit octal value. For a similar reason, a
! backslash must be entered into a field as '\\\\' or
! '\\134'. You may also have to escape line feeds and
! carriage return if your interface automatically translates these. It
! can store values of any length. Bytea is a non-standard
! data type.
Date/Time Types
--- 965,1260 ----
!
! Binary Strings
!
! The bytea data type allows storage of binary strings.
!
!
!
! Binary String Types
!
!
!
! Type Name
! Storage
! Description
!
!
!
!
! bytea
! 4 bytes plus the actual string
! Variable (not specifically limited)
! length binary string
!
!
!
!
!
!
! A binary string is a sequence of octets that does not have either a
! character set or collation associated with it. Bytea specifically
! allows storage of NULLs and other 'non-printable' ASCII
! characters.
!
!
!
! Certain ASCII characters MUST be escaped (but all
! characters MAY be escaped) when used as part of a string literal in an
! SQL statement. In general, to escape a character, it
! is converted into the three digit octal number equal to the decimal
! ASCII value, and preceeded by two backslashes. The
! single quote (') and backslash (\) characters have special alternate
! escape sequences. Details are in
! .
!
!
!
! <acronym>SQL</acronym> Literal Escaped <acronym>ASCII</acronym>
! Characters
!
!
!
! Decimal ASCII Value
! Description
! Input Escaped Representation
! Example
! Printed Result
!
!
!
!
!
! 0
! null byte
! '\\000'
! select '\\000'::bytea;
! \000
!
!
!
! 39
! single quote
! '\\'' or '\\047'
! select '\''::bytea;
! '
!
!
!
! 92
! backslash
! '\\\\' or '\\134'
! select '\\\\'::bytea;
! \\
!
!
!
!
!
!
!
! Note that the result in each of the examples above was exactly one
! byte in length, even though the output representation of the null byte
! and backslash are more than one character. Bytea output characters
! are also escaped. In general, each "non-printable" character is
! converted into the three digit octal number equal to its decimal
! ASCII value, and preceeded by one backslash. Most
! "printable" characters are represented by their standard
! ASCII representation. The backslash (\) character
! has a special alternate output representation. Details are in
! .
!
!
!
! <acronym>SQL</acronym> Output Escaped <acronym>ASCII</acronym>
! Characters
!
!
!
! Decimal ASCII Value
! Description
! Output Escaped Representation
! Example
! Printed Result
!
!
!
!
!
!
! 39
! single quote
! '
! select '\\047'::bytea;
! '
!
!
!
! 92
! backslash
! \\
! select '\\134'::bytea;
! \\
!
!
!
! 0 to 31 and 127 to 255
! non-printable characters
! \### (octal value)
! select '\\001'::bytea;
! \001
!
!
!
! 32 to 126
! printable characters
! ASCII representation
! select '\\176'::bytea;
! ~
!
!
!
!
!
!
!
! SQL string literals (input strings) must be
! preceeded with two backslashes due to the fact that they must pass
! through two parsers in the PostgreSQL backend. The first backslash
! is interpreted as an escape character by the string literal parser,
! and therefore is consumed, leaving the characters that follow it.
! The second backslash is recognized by bytea input function
! as the prefix of a three digit octal value. For example, a string
! literal passed to the backend as '\\001' becomes
! '\001' after passing through the string literal
! parser. The '\001' is then sent to the bytea
! input function, where it is converted to a single byte with a decimal
! ASCII value of 1.
!
!
!
! For a similar reason, a backslash must be input as
! '\\\\' (or '\\134'). The first
! and third backslashes are interpreted as escape characters by the
! string literal parser, and therefore are consumed, leaving the
! second and forth backslashes untouched. The second and forth
! backslashes are recognized by bytea input function as a single
! backslash. For example, a string literal passed to the backend as
! '\\\\' becomes '\\' after passing
! through the string literal parser. The '\\' is then
! sent to the bytea input function, where it is converted to a single
! byte with a decimal ASCII value of 92.
!
!
!
! A single quote is a bit different in that it must be input as
! '\'' (or '\\134'), NOT as
! '\\''. This is because, while the literal parser
! interprets the single quote as a special character, and will consume
! the single backslash, the bytea input function does NOT recognize
! a single quote as a special character. Therefore a string
! literal passed to the backend as '\'' becomes
! ''' after passing through the string literal
! parser. The ''' is then sent to the bytea
! input function, where it is retains its single byte decimal
! ASCII value of 39.
!
! Depending on the front end to PostgreSQL you use, you may have
! additional work to do in terms of escaping and unescaping bytea
! strings. For example, you may also have to escape line feeds and
! carriage return if your interface automatically translates these.
! Or you may have to double up on backslashes if the parser for your
! language or choice also treats them as an escape character.
+
+
+ Compatibility
+
+ Bytea provides most of the functionality of the SQL99 binary string
+ type per SQL99 section 4.3. A comparison of PostgreSQL bytea and SQL99
+ Binary Strings is presented in
+ .
+
+
+
+ Comparison of SQL99 Binary String and BYTEA types
+
+
+
+ SQL99
+ BYTEA
+
+
+
+
+
+ Name of data type BINARY LARGE OBJECT or BLOB
+ Name of data type BYTEA
+
+
+
+ Sequence of octets that does not have either a character set
+ or collation associated with it.
+ same
+
+
+
+ Described by a binary data type descriptor containing the
+ name of the data type and the maximum length
+ in octets
+ Described by a binary data type descriptor containing the
+ name of the data type with no specific maximum length
+
+
+
+
+ All binary strings are mutually comparable in accordance
+ with the rules of comparison predicates.
+ same
+
+
+
+ Binary string values can only be compared for equality.
+
+ Binary string values can be compared for equality, greater
+ than, greater than or equal, less than, less than or equal
+
+
+
+
+ Operators operating on and returning binary strings
+ include concatenation, substring, overlay, and trim
+ Operators operating on and returning binary strings
+ include concatenation, substring, and trim. The
+ 'leading' and 'trailing'
+ arguments for trim are not yet implemented.
+
+
+
+
+ Other operators involving binary strings
+ include length, position, and the like predicate
+ same
+
+
+
+ A binary string literal is comprised of an even number of
+ hexidecimal digits, in single quotes, preceeded by "X",
+ e.g. X'1a43fe'
+ A binary string literal is comprised of ASCII characters
+ escaped according to the rules shown in
+
+
+
+
+
+
+
Date/Time Types