mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-10 09:39:34 +02:00
9c4c70321d
theory floating elements.
382 lines
10 KiB
Plaintext
382 lines
10 KiB
Plaintext
<!-- $PostgreSQL: pgsql/doc/src/sgml/isn.sgml,v 1.5 2009/05/18 11:08:24 petere Exp $ -->
|
||
|
||
<sect1 id="isn">
|
||
<title>isn</title>
|
||
|
||
<indexterm zone="isn">
|
||
<primary>isn</primary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
The <filename>isn</filename> module provides data types for the following
|
||
international product numbering standards: EAN13, UPC, ISBN (books), ISMN
|
||
(music), and ISSN (serials). Numbers are validated on input, and correctly
|
||
hyphenated on output.
|
||
</para>
|
||
|
||
<sect2>
|
||
<title>Data types</title>
|
||
|
||
<table>
|
||
<title><filename>isn</filename> data types</title>
|
||
<tgroup cols="2">
|
||
<thead>
|
||
<row>
|
||
<entry>Data type</entry>
|
||
<entry>Description</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry><type>EAN13</type></entry>
|
||
<entry>
|
||
European Article Numbers, always displayed in the EAN13 display format
|
||
</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><type>ISBN13</type></entry>
|
||
<entry>
|
||
International Standard Book Numbers to be displayed in
|
||
the new EAN13 display format
|
||
</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><type>ISMN13</type></entry>
|
||
<entry>
|
||
International Standard Music Numbers to be displayed in
|
||
the new EAN13 display format
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><type>ISSN13</type></entry>
|
||
<entry>
|
||
International Standard Serial Numbers to be displayed in the new
|
||
EAN13 display format
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><type>ISBN</type></entry>
|
||
<entry>
|
||
International Standard Book Numbers to be displayed in the old
|
||
short display format
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><type>ISMN</type></entry>
|
||
<entry>
|
||
International Standard Music Numbers to be displayed in the
|
||
old short display format
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><type>ISSN</type></entry>
|
||
<entry>
|
||
International Standard Serial Numbers to be displayed in the
|
||
old short display format
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><type>UPC</type></entry>
|
||
<entry>
|
||
Universal Product Codes
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
Some notes:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>ISBN13, ISMN13, ISSN13 numbers are all EAN13 numbers.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>EAN13 numbers aren't always ISBN13, ISMN13 or ISSN13 (some
|
||
are).</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Some ISBN13 numbers can be displayed as ISBN.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Some ISMN13 numbers can be displayed as ISMN.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Some ISSN13 numbers can be displayed as ISSN.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>UPC numbers are a subset of the EAN13 numbers (they are basically
|
||
EAN13 without the first <literal>0</> digit).</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>All UPC, ISBN, ISMN and ISSN numbers can be represented as EAN13
|
||
numbers.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>
|
||
Internally, all these types use the same representation (a 64-bit
|
||
integer), and all are interchangeable. Multiple types are provided
|
||
to control display formatting and to permit tighter validity checking
|
||
of input that is supposed to denote one particular type of number.
|
||
</para>
|
||
|
||
<para>
|
||
The <type>ISBN</>, <type>ISMN</>, and <type>ISSN</> types will display the
|
||
short version of the number (ISxN 10) whenever it's possible, and will show
|
||
ISxN 13 format for numbers that do not fit in the short version.
|
||
The <type>EAN13</type>, <type>ISBN13</type>, <type>ISMN13</type> and
|
||
<type>ISSN13</type> types will always display the long version of the ISxN
|
||
(EAN13).
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2>
|
||
<title>Casts</title>
|
||
|
||
<para>
|
||
The <filename>isn</> module provides the following pairs of type casts:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
ISBN13 <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISMN13 <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISSN13 <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISBN <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISMN <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISSN <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
UPC <=> EAN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISBN <=> ISBN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISMN <=> ISMN13
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
ISSN <=> ISSN13
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
When casting from <type>EAN13</> to another type, there is a run-time
|
||
check that the value is within the domain of the other type, and an error
|
||
is thrown if not. The other casts are simply relabelings that will
|
||
always succeed.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2>
|
||
<title>Functions and Operators</title>
|
||
|
||
<para>
|
||
The <filename>isn</> module provides the standard comparison operators,
|
||
plus btree and hash indexing support for all these datatypes. In
|
||
addition there are several specialized functions; shown in <xref linkend="isn-functions">.
|
||
In this table,
|
||
<type>isn</> means any one of the module's data types.
|
||
</para>
|
||
|
||
<table id="isn-functions">
|
||
<title><filename>isn</> functions</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Function</entry>
|
||
<entry>Returns</entry>
|
||
<entry>Description</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry><function>isn_weak(boolean)</function></entry>
|
||
<entry><type>boolean</type></entry>
|
||
<entry>Sets the weak input mode (returns new setting)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><function>isn_weak()</function></entry>
|
||
<entry><type>boolean</type></entry>
|
||
<entry>Gets the current status of the weak mode</entry>
|
||
</row>
|
||
<row>
|
||
<entry><function>make_valid(isn)</function></entry>
|
||
<entry><type>isn</type></entry>
|
||
<entry>Validates an invalid number (clears the invalid flag)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><function>is_valid(isn)</function></entry>
|
||
<entry><type>boolean</type></entry>
|
||
<entry>Checks for the presence of the invalid flag</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
<firstterm>Weak</firstterm> mode is used to be able to insert invalid data
|
||
into a table. Invalid means the check digit is wrong, not that there are
|
||
missing numbers.
|
||
</para>
|
||
|
||
<para>
|
||
Why would you want to use the weak mode? Well, it could be that
|
||
you have a huge collection of ISBN numbers, and that there are so many of
|
||
them that for weird reasons some have the wrong check digit (perhaps the
|
||
numbers were scanned from a printed list and the OCR got the numbers wrong,
|
||
perhaps the numbers were manually captured... who knows). Anyway, the point
|
||
is you might want to clean the mess up, but you still want to be able to
|
||
have all the numbers in your database and maybe use an external tool to
|
||
locate the invalid numbers in the database so you can verify the
|
||
information and validate it more easily; so for example you'd want to
|
||
select all the invalid numbers in the table.
|
||
</para>
|
||
|
||
<para>
|
||
When you insert invalid numbers in a table using the weak mode, the number
|
||
will be inserted with the corrected check digit, but it will be displayed
|
||
with an exclamation mark (<literal>!</>) at the end, for example
|
||
<literal>0-11-000322-5!</>. This invalid marker can be checked with
|
||
the <function>is_valid</> function and cleared with the
|
||
<function>make_valid</> function.
|
||
</para>
|
||
|
||
<para>
|
||
You can also force the insertion of invalid numbers even when not in the
|
||
weak mode, by appending the <literal>!</> character at the end of the
|
||
number.
|
||
</para>
|
||
|
||
<para>
|
||
Another special feature is that during input, you can write
|
||
<literal>?</> in place of the check digit, and the correct check digit
|
||
will be inserted automatically.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2>
|
||
<title>Examples</title>
|
||
|
||
<programlisting>
|
||
--Using the types directly:
|
||
SELECT isbn('978-0-393-04002-9');
|
||
SELECT isbn13('0901690546');
|
||
SELECT issn('1436-4522');
|
||
|
||
--Casting types:
|
||
-- note that you can only cast from ean13 to another type when the
|
||
-- number would be valid in the realm of the target type;
|
||
-- thus, the following will NOT work: select isbn(ean13('0220356483481'));
|
||
-- but these will:
|
||
SELECT upc(ean13('0220356483481'));
|
||
SELECT ean13(upc('220356483481'));
|
||
|
||
--Create a table with a single column to hold ISBN numbers:
|
||
CREATE TABLE test (id isbn);
|
||
INSERT INTO test VALUES('9780393040029');
|
||
|
||
--Automatically calculate check digits (observe the '?'):
|
||
INSERT INTO test VALUES('220500896?');
|
||
INSERT INTO test VALUES('978055215372?');
|
||
|
||
SELECT issn('3251231?');
|
||
SELECT ismn('979047213542?');
|
||
|
||
--Using the weak mode:
|
||
SELECT isn_weak(true);
|
||
INSERT INTO test VALUES('978-0-11-000533-4');
|
||
INSERT INTO test VALUES('9780141219307');
|
||
INSERT INTO test VALUES('2-205-00876-X');
|
||
SELECT isn_weak(false);
|
||
|
||
SELECT id FROM test WHERE NOT is_valid(id);
|
||
UPDATE test SET id = make_valid(id) WHERE id = '2-205-00876-X!';
|
||
|
||
SELECT * FROM test;
|
||
|
||
SELECT isbn13(id) FROM test;
|
||
</programlisting>
|
||
</sect2>
|
||
|
||
<sect2>
|
||
<title>Bibliography</title>
|
||
|
||
<para>
|
||
The information to implement this module was collected from
|
||
several sites, including:
|
||
</para>
|
||
<programlisting>
|
||
http://www.isbn-international.org/
|
||
http://www.issn.org/
|
||
http://www.ismn-international.org/
|
||
http://www.wikipedia.org/
|
||
</programlisting>
|
||
|
||
<para>
|
||
The prefixes used for hyphenation were also compiled from:
|
||
</para>
|
||
<programlisting>
|
||
http://www.gs1.org/productssolutions/idkeys/support/prefix_list.html
|
||
http://www.isbn-international.org/en/identifiers.html
|
||
http://www.ismn-international.org/ranges.html
|
||
</programlisting>
|
||
|
||
<para>
|
||
Care was taken during the creation of the algorithms and they
|
||
were meticulously verified against the suggested algorithms
|
||
in the official ISBN, ISMN, ISSN User Manuals.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2>
|
||
<title>Author</title>
|
||
<para>
|
||
Germ<72>n M<>ndez Bravo (Kronuz), 2004 - 2006
|
||
</para>
|
||
|
||
<para>
|
||
This module was inspired by Garrett A. Wollman's
|
||
isbn_issn code.
|
||
</para>
|
||
</sect2>
|
||
|
||
</sect1>
|