begriffs open source - ai-pg/blob - full-docs/src/sgml/html/isn.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.20. isn — data types for international standard numbers (ISBN, EAN, UPC, etc.)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="intarray.html" title="F.19. intarray — manipulate arrays of integers" /><link rel="next" href="lo.html" title="F.21. lo — manage large objects" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.20. isn — data types for international standard numbers (ISBN, EAN, UPC, etc.)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="intarray.html" title="F.19. intarray — manipulate arrays of integers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo.html" title="F.21. lo — manage large objects">Next</a></td></tr></table><hr /></div><div class="sect1" id="ISN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.20. isn — data types for international standard numbers (ISBN, EAN, UPC, etc.) <a href="#ISN" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="isn.html#ISN-DATA-TYPES">F.20.1. Data Types</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-CASTS">F.20.2. Casts</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-FUNCS-OPS">F.20.3. Functions and Operators</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-CONFIGURATION-PARAMETERS">F.20.4. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-EXAMPLES">F.20.5. Examples</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-BIBLIOGRAPHY">F.20.6. Bibliography</a></span></dt><dt><span class="sect2"><a href="isn.html#ISN-AUTHOR">F.20.7. Author</a></span></dt></dl></div><a id="id-1.11.7.30.2" class="indexterm"></a><p>
   3   The <code class="filename">isn</code> module provides data types for the following
   4   international product numbering standards: EAN13, UPC, ISBN (books), ISMN
   5   (music), and ISSN (serials).  Numbers are validated on input according to a
   6   hard-coded list of prefixes; this list of prefixes is also used to hyphenate
   7   numbers on output.  Since new prefixes are assigned from time to time, the
   8   list of prefixes may be out of date.  It is hoped that a future version of
   9   this module will obtain the prefix list from one or more tables that
  10   can be easily updated by users as needed; however, at present, the
  11   list can only be updated by modifying the source code and recompiling.
  12   Alternatively, prefix validation and hyphenation support may be
  13   dropped from a future version of this module.
  14  </p><p>
  15   This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
  16   installed by non-superusers who have <code class="literal">CREATE</code> privilege
  17   on the current database.
  18  </p><div class="sect2" id="ISN-DATA-TYPES"><div class="titlepage"><div><div><h3 class="title">F.20.1. Data Types <a href="#ISN-DATA-TYPES" class="id_link">#</a></h3></div></div></div><p>
  19    <a class="xref" href="isn.html#ISN-DATATYPES" title="Table F.10. isn Data Types">Table F.10</a> shows the data types provided by
  20    the <code class="filename">isn</code> module.
  21   </p><div class="table" id="ISN-DATATYPES"><p class="title"><strong>Table F.10. <code class="filename">isn</code> Data Types</strong></p><div class="table-contents"><table class="table" summary="isn Data Types" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">EAN13</code></td><td>
  22        European Article Numbers, always displayed in the EAN13 display format
  23       </td></tr><tr><td><code class="type">ISBN13</code></td><td>
  24        International Standard Book Numbers to be displayed in
  25        the new EAN13 display format
  26       </td></tr><tr><td><code class="type">ISMN13</code></td><td>
  27        International Standard Music Numbers to be displayed in
  28        the new EAN13 display format
  29       </td></tr><tr><td><code class="type">ISSN13</code></td><td>
  30        International Standard Serial Numbers to be displayed in the new
  31        EAN13 display format
  32       </td></tr><tr><td><code class="type">ISBN</code></td><td>
  33        International Standard Book Numbers to be displayed in the old
  34        short display format
  35       </td></tr><tr><td><code class="type">ISMN</code></td><td>
  36        International Standard Music Numbers to be displayed in the
  37        old short display format
  38       </td></tr><tr><td><code class="type">ISSN</code></td><td>
  39        International Standard Serial Numbers to be displayed in the
  40        old short display format
  41       </td></tr><tr><td><code class="type">UPC</code></td><td>
  42        Universal Product Codes
  43       </td></tr></tbody></table></div></div><br class="table-break" /><p>
  44    Some notes:
  45   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>ISBN13, ISMN13, ISSN13 numbers are all EAN13 numbers.</p></li><li class="listitem"><p>EAN13 numbers aren't always ISBN13, ISMN13 or ISSN13 (some
  46     are).</p></li><li class="listitem"><p>Some ISBN13 numbers can be displayed as ISBN.</p></li><li class="listitem"><p>Some ISMN13 numbers can be displayed as ISMN.</p></li><li class="listitem"><p>Some ISSN13 numbers can be displayed as ISSN.</p></li><li class="listitem"><p>UPC numbers are a subset of the EAN13 numbers (they are basically
  47     EAN13 without the first <code class="literal">0</code> digit).</p></li><li class="listitem"><p>All UPC, ISBN, ISMN and ISSN numbers can be represented as EAN13
  48     numbers.</p></li></ol></div><p>
  49    Internally, all these types use the same representation (a 64-bit
  50    integer), and all are interchangeable.  Multiple types are provided
  51    to control display formatting and to permit tighter validity checking
  52    of input that is supposed to denote one particular type of number.
  53   </p><p>
  54    The <code class="type">ISBN</code>, <code class="type">ISMN</code>, and <code class="type">ISSN</code> types will display the
  55    short version of the number (ISxN 10) whenever it's possible, and will show
  56    ISxN 13 format for numbers that do not fit in the short version.
  57    The <code class="type">EAN13</code>, <code class="type">ISBN13</code>, <code class="type">ISMN13</code> and
  58    <code class="type">ISSN13</code> types will always display the long version of the ISxN
  59    (EAN13).
  60   </p></div><div class="sect2" id="ISN-CASTS"><div class="titlepage"><div><div><h3 class="title">F.20.2. Casts <a href="#ISN-CASTS" class="id_link">#</a></h3></div></div></div><p>
  61    The <code class="filename">isn</code> module provides the following pairs of type casts:
  62   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  63      ISBN13 &lt;=&gt; EAN13
  64     </p></li><li class="listitem"><p>
  65      ISMN13 &lt;=&gt; EAN13
  66     </p></li><li class="listitem"><p>
  67      ISSN13 &lt;=&gt; EAN13
  68     </p></li><li class="listitem"><p>
  69      ISBN &lt;=&gt; EAN13
  70     </p></li><li class="listitem"><p>
  71      ISMN &lt;=&gt; EAN13
  72     </p></li><li class="listitem"><p>
  73      ISSN &lt;=&gt; EAN13
  74     </p></li><li class="listitem"><p>
  75      UPC  &lt;=&gt; EAN13
  76     </p></li><li class="listitem"><p>
  77      ISBN &lt;=&gt; ISBN13
  78     </p></li><li class="listitem"><p>
  79      ISMN &lt;=&gt; ISMN13
  80     </p></li><li class="listitem"><p>
  81      ISSN &lt;=&gt; ISSN13
  82     </p></li></ul></div><p>
  83    When casting from <code class="type">EAN13</code> to another type, there is a run-time
  84    check that the value is within the domain of the other type, and an error
  85    is thrown if not.  The other casts are simply relabelings that will
  86    always succeed.
  87   </p></div><div class="sect2" id="ISN-FUNCS-OPS"><div class="titlepage"><div><div><h3 class="title">F.20.3. Functions and Operators <a href="#ISN-FUNCS-OPS" class="id_link">#</a></h3></div></div></div><p>
  88    The <code class="filename">isn</code> module provides the standard comparison operators,
  89    plus B-tree and hash indexing support for all these data types.  In
  90    addition, there are several specialized functions, shown in <a class="xref" href="isn.html#ISN-FUNCTIONS" title="Table F.11. isn Functions">Table F.11</a>.
  91    In this table,
  92    <code class="type">isn</code> means any one of the module's data types.
  93   </p><div class="table" id="ISN-FUNCTIONS"><p class="title"><strong>Table F.11. <code class="filename">isn</code> Functions</strong></p><div class="table-contents"><table class="table" summary="isn Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  94         Function
  95        </p>
  96        <p>
  97         Description
  98        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  99         <a id="id-1.11.7.30.7.3.2.2.1.1.1.1" class="indexterm"></a>
 100         <code class="function">make_valid</code> ( <code class="type">isn</code> )
 101         → <code class="returnvalue">isn</code>
 102        </p>
 103        <p>
 104         Clears the invalid-check-digit flag of the value.
 105        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 106         <a id="id-1.11.7.30.7.3.2.2.2.1.1.1" class="indexterm"></a>
 107         <code class="function">is_valid</code> ( <code class="type">isn</code> )
 108         → <code class="returnvalue">boolean</code>
 109        </p>
 110        <p>
 111         Checks for the presence of the invalid-check-digit flag.
 112        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 113         <a id="id-1.11.7.30.7.3.2.2.3.1.1.1" class="indexterm"></a>
 114         <code class="function">isn_weak</code> ( <code class="type">boolean</code> )
 115         → <code class="returnvalue">boolean</code>
 116        </p>
 117        <p>
 118         Sets the weak input mode, and returns the new setting.
 119         This function is retained for backward compatibility.
 120         The recommended way to set weak mode is via
 121         the <code class="varname">isn.weak</code> configuration parameter.
 122        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 123         <code class="function">isn_weak</code> ()
 124         → <code class="returnvalue">boolean</code>
 125        </p>
 126        <p>
 127         Returns the current status of the weak mode.
 128         This function is retained for backward compatibility.
 129         The recommended way to check weak mode is via
 130         the <code class="varname">isn.weak</code> configuration parameter.
 131        </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="ISN-CONFIGURATION-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">F.20.4. Configuration Parameters <a href="#ISN-CONFIGURATION-PARAMETERS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="ISN-CONFIGURATION-PARAMETERS-WEAK"><span class="term">
 132      <code class="varname">isn.weak</code> (<code class="type">boolean</code>)
 133      <a id="id-1.11.7.30.8.2.1.1.3" class="indexterm"></a>
 134     </span> <a href="#ISN-CONFIGURATION-PARAMETERS-WEAK" class="id_link">#</a></dt><dd><p>
 135       <code class="varname">isn.weak</code> enables the weak input mode, which allows
 136       ISN input values to be accepted even when their check digit is wrong.
 137       The default is <code class="literal">false</code>, which rejects invalid check
 138       digits.
 139      </p></dd></dl></div><p>
 140    Why would you want to use the weak mode? Well, it could be that
 141    you have a huge collection of ISBN numbers, and that there are so many of
 142    them that for weird reasons some have the wrong check digit (perhaps the
 143    numbers were scanned from a printed list and the OCR got the numbers wrong,
 144    perhaps the numbers were manually captured... who knows). Anyway, the point
 145    is you might want to clean the mess up, but you still want to be able to
 146    have all the numbers in your database and maybe use an external tool to
 147    locate the invalid numbers in the database so you can verify the
 148    information and validate it more easily; so for example you'd want to
 149    select all the invalid numbers in the table.
 150   </p><p>
 151    When you insert invalid numbers in a table using the weak mode, the number
 152    will be inserted with the corrected check digit, but it will be displayed
 153    with an exclamation mark (<code class="literal">!</code>) at the end, for example
 154    <code class="literal">0-11-000322-5!</code>.  This invalid marker can be checked with
 155    the <code class="function">is_valid</code> function and cleared with the
 156    <code class="function">make_valid</code> function.
 157   </p><p>
 158    You can also force the insertion of marked-as-invalid numbers even when not
 159    in the weak mode, by appending the <code class="literal">!</code> character at the
 160    end of the number.
 161   </p><p>
 162    Another special feature is that during input, you can write
 163    <code class="literal">?</code> in place of the check digit, and the correct check digit
 164    will be inserted automatically.
 165   </p></div><div class="sect2" id="ISN-EXAMPLES"><div class="titlepage"><div><div><h3 class="title">F.20.5. Examples <a href="#ISN-EXAMPLES" class="id_link">#</a></h3></div></div></div><pre class="programlisting">
 166 --Using the types directly:
 167 SELECT isbn('978-0-393-04002-9');
 168 SELECT isbn13('0901690546');
 169 SELECT issn('1436-4522');
 170
 171 --Casting types:
 172 -- note that you can only cast from ean13 to another type when the
 173 -- number would be valid in the realm of the target type;
 174 -- thus, the following will NOT work: select isbn(ean13('0220356483481'));
 175 -- but these will:
 176 SELECT upc(ean13('0220356483481'));
 177 SELECT ean13(upc('220356483481'));
 178
 179 --Create a table with a single column to hold ISBN numbers:
 180 CREATE TABLE test (id isbn);
 181 INSERT INTO test VALUES('9780393040029');
 182
 183 --Automatically calculate check digits (observe the '?'):
 184 INSERT INTO test VALUES('220500896?');
 185 INSERT INTO test VALUES('978055215372?');
 186
 187 SELECT issn('3251231?');
 188 SELECT ismn('979047213542?');
 189
 190 --Using the weak mode:
 191 SET isn.weak TO true;
 192 INSERT INTO test VALUES('978-0-11-000533-4');
 193 INSERT INTO test VALUES('9780141219307');
 194 INSERT INTO test VALUES('2-205-00876-X');
 195 SET isn.weak TO false;
 196
 197 SELECT id FROM test WHERE NOT is_valid(id);
 198 UPDATE test SET id = make_valid(id) WHERE id = '2-205-00876-X!';
 199
 200 SELECT * FROM test;
 201
 202 SELECT isbn13(id) FROM test;
 203 </pre></div><div class="sect2" id="ISN-BIBLIOGRAPHY"><div class="titlepage"><div><div><h3 class="title">F.20.6. Bibliography <a href="#ISN-BIBLIOGRAPHY" class="id_link">#</a></h3></div></div></div><p>
 204    The information to implement this module was collected from
 205    several sites, including:
 206    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.isbn-international.org/" target="_top">https://www.isbn-international.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.issn.org/" target="_top">https://www.issn.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.ismn-international.org/" target="_top">https://www.ismn-international.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.wikipedia.org/" target="_top">https://www.wikipedia.org/</a></p></li></ul></div><p>
 207
 208    The prefixes used for hyphenation were also compiled from:
 209    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.gs1.org/standards/id-keys" target="_top">https://www.gs1.org/standards/id-keys</a></p></li><li class="listitem"><p><a class="ulink" href="https://en.wikipedia.org/wiki/List_of_ISBN_registration_groups" target="_top">https://en.wikipedia.org/wiki/List_of_ISBN_registration_groups</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.isbn-international.org/content/isbn-users-manual/29" target="_top">https://www.isbn-international.org/content/isbn-users-manual/29</a></p></li><li class="listitem"><p><a class="ulink" href="https://en.wikipedia.org/wiki/International_Standard_Music_Number" target="_top">https://en.wikipedia.org/wiki/International_Standard_Music_Number</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.ismn-international.org/ranges/tools" target="_top">https://www.ismn-international.org/ranges/tools</a></p></li></ul></div><p>
 210
 211    Care was taken during the creation of the algorithms and they
 212    were meticulously verified against the suggested algorithms
 213    in the official ISBN, ISMN, ISSN User Manuals.
 214   </p></div><div class="sect2" id="ISN-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.20.7. Author <a href="#ISN-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
 215    Germán Méndez Bravo (Kronuz), 2004–2006
 216   </p><p>
 217    This module was inspired by Garrett A. Wollman's
 218    <code class="filename">isbn_issn</code> code.
 219   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intarray.html" title="F.19. intarray — manipulate arrays of integers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo.html" title="F.21. lo — manage large objects">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.19. intarray — manipulate arrays of integers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.21. lo — manage large objects</td></tr></table></div></body></html>