<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2020 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="fn_vector">
  <refmeta>
    <refentrytitle>vector</refentrytitle>
    <refmiscinfo>array</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>vector</refname>
    <refpurpose>make a vector</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis id="fsyn_vector">
      <funcprototype id="fproto_vector">
        <funcdef><function>vector</function></funcdef>
        <paramdef><parameter>elem1</parameter> any</paramdef>
	<paramdef><parameter>elem2</parameter> any</paramdef>
        <paramdef><parameter>...</parameter> </paramdef>
        <paramdef><parameter>elem-n</parameter> any</paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="desc_vector">
    <title>Description</title>
      <para><function>vector</function> returns a new vector (one-dimensional array) constructed from the given arguments.</para>
  </refsect1>
  <refsect1 id="params_vector"><title>Parameters</title>
    <refsect2><title><parameter>elem1..n</parameter></title>
      <para>Values of any types (not necessarily of one and the same type).
      </para>
    </refsect2>
  </refsect1>
  <refsect1 id="ret_vector"><title>Return Values</title>
    <para>A vector (heterogeneous array) of as many elements as there
    were arguments containing copies of the arguments.</para>
  </refsect1>
  <refsect1 id="examples_vector"><title>Examples</title>
    <example id="ex_vector_1"><title>Inspecting a vector with dbg_obj_print</title>
      <para>SQL clients can not process vectors directly so the simplest way to look at the content of a vector is to print it no server's console.</para>
      <screen>
dbg_obj_print (vector (1, 2.34, 'A string', atof('3.14')))
</screen>
    </example>
    <example id="ex_vector_2"><title>Pretty-print function for vectors</title>
      <para>The following function gets a heterogeneous vector of strings, nubers and other vectors and returns a string that is an SQL expression that will return a copy of a given vector.</para>
      <screen><![CDATA[create procedure DUMP_VEC_IMPL (inout _vec any, inout _ses any)
{
  declare _len, _ctr integer;
  if (193 <> __tag (_vec))
    {
      if (isstring (_vec))
        http (WS.WS.STR_SQL_APOS (_vec), _ses);
      else
        http (cast (_vec as varchar), _ses);
      return;
    }
  _len := length (_vec);
  _ctr := 0;
  http ('\nvector (', _ses);
  while (_ctr < _len)
    {
      if (_ctr > 0)
        http (', ', _ses);
      DUMP_VEC_IMPL (_vec[_ctr], _ses);
      _ctr := _ctr+1;
    }
  http (')', _ses);
}

create function DUMP_VEC (in _vec any)
{
  declare _ses any;
  _ses := string_output();
  DUMP_VEC_IMPL (_vec, _ses);
  return string_output_string (_ses);
}

select DUMP_VEC (vector ('abc', 1, vector (3.1415), vector ()));
callret
VARCHAR
_______________________________________________________________________________

vector ('abc', 1, 
vector (3.1415), 
vector ())

1 Rows.
]]></screen>
    </example>
  </refsect1>
    <refsect1 id="seealso_vector"><title>See Also</title>
    <para>
      <link linkend="fn_aset"><function>aset</function></link>
      <link linkend="fn_aref"><function>aref</function></link>
      <link linkend="fn_vector_concat"><function>vector_concat</function></link>
    </para>
  </refsect1>
</refentry>
