<!-- doc/src/sgml/intarray.sgml -->

<sect1 id="intarray" xreflabel="intarray">
 <title>intarray &mdash; manipulate arrays of integers</title>

 <indexterm zone="intarray">
  <primary>intarray</primary>
 </indexterm>

 <para>
  The <filename>intarray</filename> module provides a number of useful functions
  and operators for manipulating null-free arrays of integers.
  There is also support for indexed searches using some of the operators.
 </para>

 <para>
  All of these operations will throw an error if a supplied array contains any
  NULL elements.
 </para>

 <para>
  Many of these operations are only sensible for one-dimensional arrays.
  Although they will accept input arrays of more dimensions, the data is
  treated as though it were a linear array in storage order.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="intarray-funcs-ops">
  <title><filename>intarray</filename> Functions and Operators</title>

  <para>
   The functions provided by the <filename>intarray</filename> module
   are shown in <xref linkend="intarray-func-table"/>, the operators
   in <xref linkend="intarray-op-table"/>.
  </para>

  <table id="intarray-func-table">
   <title><filename>intarray</filename> Functions</title>
    <tgroup cols="1">
     <thead>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        Function
       </para>
       <para>
        Description
       </para>
       <para>
        Example(s)
       </para></entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm><primary>icount</primary></indexterm>
        <function>icount</function> ( <type>integer[]</type> )
        <returnvalue>integer</returnvalue>
       </para>
       <para>
        Returns the number of elements in the array.
       </para>
       <para>
        <literal>icount('{1,2,3}'::integer[])</literal>
        <returnvalue>3</returnvalue>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm><primary>sort</primary></indexterm>
        <function>sort</function> ( <type>integer[]</type>, <parameter>dir</parameter> <type>text</type> )
        <returnvalue>integer[]</returnvalue>
       </para>
       <para>
        Sorts the array in either ascending or descending order.
        <parameter>dir</parameter> must be <literal>asc</literal>
        or <literal>desc</literal>.
       </para>
       <para>
        <literal>sort('{1,3,2}'::integer[], 'desc')</literal>
        <returnvalue>{3,2,1}</returnvalue>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>sort</function> ( <type>integer[]</type> )
        <returnvalue>integer[]</returnvalue>
       </para>
       <para role="func_signature">
        <indexterm><primary>sort_asc</primary></indexterm>
        <function>sort_asc</function> ( <type>integer[]</type> )
        <returnvalue>integer[]</returnvalue>
       </para>
       <para>
        Sorts in ascending order.
       </para>
       <para>
        <literal>sort(array[11,77,44])</literal>
        <returnvalue>{11,44,77}</returnvalue>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm><primary>sort_desc</primary></indexterm>
        <function>sort_desc</function> ( <type>integer[]</type> )
        <returnvalue>integer[]</returnvalue>
       </para>
       <para>
        Sorts in descending order.
       </para>
       <para>
        <literal>sort_desc(array[11,77,44])</literal>
        <returnvalue>{77,44,11}</returnvalue>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">