Trim trailing whitespace

[postgresql] / doc / src / sgml / hstore.sgml

diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 73c421d463febbfc2eec88ee1abb2e9dd50b71ab..db5d4409a6e585cf58cca7677e50b9e21d9c5a72 100644 (file)
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -233,7 +233,7 @@ key => NULL
 
     <tbody>
      <row>
-      <entry><function>hstore(record)</function></entry>
+      <entry><function>hstore(record)</function><indexterm><primary>hstore</primary></indexterm></entry>
       <entry><type>hstore</type></entry>
       <entry>construct an <type>hstore</> from a record or row</entry>
       <entry><literal>hstore(ROW(1,2))</literal></entry>
@@ -266,7 +266,7 @@ key =&gt; NULL
      </row>
 
      <row>
-      <entry><function>akeys(hstore)</function></entry>
+      <entry><function>akeys(hstore)</function><indexterm><primary>akeys</primary></indexterm></entry>
       <entry><type>text[]</type></entry>
       <entry>get <type>hstore</>'s keys as an array</entry>
       <entry><literal>akeys('a=&gt;1,b=&gt;2')</literal></entry>
@@ -274,7 +274,7 @@ key =&gt; NULL
      </row>
 
      <row>
-      <entry><function>skeys(hstore)</function></entry>
+      <entry><function>skeys(hstore)</function><indexterm><primary>skeys</primary></indexterm></entry>
       <entry><type>setof text</type></entry>
       <entry>get <type>hstore</>'s keys as a set</entry>
       <entry><literal>skeys('a=&gt;1,b=&gt;2')</literal></entry>
@@ -286,7 +286,7 @@ b
      </row>
 
      <row>
-      <entry><function>avals(hstore)</function></entry>
+      <entry><function>avals(hstore)</function><indexterm><primary>avals</primary></indexterm></entry>
       <entry><type>text[]</type></entry>
       <entry>get <type>hstore</>'s values as an array</entry>
       <entry><literal>avals('a=&gt;1,b=&gt;2')</literal></entry>
@@ -294,7 +294,7 @@ b
      </row>
 
      <row>
-      <entry><function>svals(hstore)</function></entry>
+      <entry><function>svals(hstore)</function><indexterm><primary>svals</primary></indexterm></entry>
       <entry><type>setof text</type></entry>
       <entry>get <type>hstore</>'s values as a set</entry>
       <entry><literal>svals('a=&gt;1,b=&gt;2')</literal></entry>
@@ -306,7 +306,7 @@ b
      </row>
 
      <row>
-      <entry><function>hstore_to_array(hstore)</function></entry>
+      <entry><function>hstore_to_array(hstore)</function><indexterm><primary>hstore_to_array</primary></indexterm></entry>
       <entry><type>text[]</type></entry>
       <entry>get <type>hstore</>'s keys and values as an array of alternating
        keys and values</entry>
@@ -315,7 +315,7 @@ b
      </row>
 
      <row>
-      <entry><function>hstore_to_matrix(hstore)</function></entry>
+      <entry><function>hstore_to_matrix(hstore)</function><indexterm><primary>hstore_to_matrix</primary></indexterm></entry>
       <entry><type>text[]</type></entry>
       <entry>get <type>hstore</>'s keys and values as a two-dimensional array</entry>
       <entry><literal>hstore_to_matrix('a=&gt;1,b=&gt;2')</literal></entry>
@@ -323,23 +323,41 @@ b
      </row>
 
      <row>
-      <entry><function>hstore_to_json(hstore)</function></entry>
+      <entry><function>hstore_to_json(hstore)</function><indexterm><primary>hstore_to_json</primary></indexterm></entry>
       <entry><type>json</type></entry>
-      <entry>get <type>hstore</type> as a <type>json</type> value</entry>
+      <entry>get <type>hstore</type> as a <type>json</type> value, converting
+       all non-null values to JSON strings</entry>
       <entry><literal>hstore_to_json('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>
       <entry><literal>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</literal></entry>
      </row>
 
      <row>
-      <entry><function>hstore_to_json_loose(hstore)</function></entry>
+      <entry><function>hstore_to_jsonb(hstore)</function><indexterm><primary>hstore_to_jsonb</primary></indexterm></entry>
+      <entry><type>jsonb</type></entry>
+      <entry>get <type>hstore</type> as a <type>jsonb</type> value, converting
+       all non-null values to JSON strings</entry>
+      <entry><literal>hstore_to_jsonb('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>
+      <entry><literal>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</literal></entry>
+     </row>
+
+     <row>
+      <entry><function>hstore_to_json_loose(hstore)</function><indexterm><primary>hstore_to_json_loose</primary></indexterm></entry>
       <entry><type>json</type></entry>
-      <entry>get <type>hstore</type> as a <type>json</type> value, but attempting to distinguish numerical and Boolean values so they are unquoted in the JSON</entry>
+      <entry>get <type>hstore</type> as a <type>json</type> value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON</entry>
       <entry><literal>hstore_to_json_loose('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>
       <entry><literal>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</literal></entry>
      </row>
 
      <row>
-      <entry><function>slice(hstore, text[])</function></entry>
+      <entry><function>hstore_to_jsonb_loose(hstore)</function><indexterm><primary>hstore_to_jsonb_loose</primary></indexterm></entry>
+      <entry><type>jsonb</type></entry>
+      <entry>get <type>hstore</type> as a <type>jsonb</type> value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON</entry>
+      <entry><literal>hstore_to_jsonb_loose('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>
+      <entry><literal>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</literal></entry>
+     </row>
+
+     <row>
+      <entry><function>slice(hstore, text[])</function><indexterm><primary>slice</primary></indexterm></entry>
       <entry><type>hstore</type></entry>
       <entry>extract a subset of an <type>hstore</></entry>
       <entry><literal>slice('a=&gt;1,b=&gt;2,c=&gt;3'::hstore, ARRAY['b','c','x'])</literal></entry>
@@ -347,7 +365,7 @@ b
      </row>
 
      <row>
-      <entry><function>each(hstore)</function></entry>
+      <entry><function>each(hstore)</function><indexterm><primary>each</primary></indexterm></entry>
       <entry><type>setof(key text, value text)</type></entry>
       <entry>get <type>hstore</>'s keys and values as a set</entry>
       <entry><literal>select * from each('a=&gt;1,b=&gt;2')</literal></entry>
@@ -361,7 +379,7 @@ b
      </row>
 
      <row>
-      <entry><function>exist(hstore,text)</function></entry>
+      <entry><function>exist(hstore,text)</function><indexterm><primary>exist</primary></indexterm></entry>
       <entry><type>boolean</type></entry>
       <entry>does <type>hstore</> contain key?</entry>
       <entry><literal>exist('a=&gt;1','a')</literal></entry>
@@ -369,7 +387,7 @@ b
      </row>
 
      <row>
-      <entry><function>defined(hstore,text)</function></entry>
+      <entry><function>defined(hstore,text)</function><indexterm><primary>defined</primary></indexterm></entry>
       <entry><type>boolean</type></entry>
       <entry>does <type>hstore</> contain non-<literal>NULL</> value for key?</entry>
       <entry><literal>defined('a=&gt;NULL','a')</literal></entry>
@@ -377,11 +395,11 @@ b
      </row>
 
      <row>
-      <entry><function>delete(hstore,text)</function></entry>
+      <entry><function>delete(hstore,text)</function><indexterm><primary>delete</primary></indexterm></entry>
       <entry><type>hstore</type></entry>
       <entry>delete pair with matching key</entry>
       <entry><literal>delete('a=&gt;1,b=&gt;2','b')</literal></entry>
-      <entry><literal>"a"=>"1"</literal></entry>
+      <entry><literal>"a"=&gt;"1"</literal></entry>
      </row>
 
      <row>
@@ -389,7 +407,7 @@ b
       <entry><type>hstore</type></entry>
       <entry>delete pairs with matching keys</entry>
       <entry><literal>delete('a=&gt;1,b=&gt;2,c=&gt;3',ARRAY['a','b'])</literal></entry>
-      <entry><literal>"c"=>"3"</literal></entry>
+      <entry><literal>"c"=&gt;"3"</literal></entry>
      </row>
 
      <row>
@@ -397,11 +415,11 @@ b
       <entry><type>hstore</type></entry>
       <entry>delete pairs matching those in the second argument</entry>
       <entry><literal>delete('a=&gt;1,b=&gt;2','a=&gt;4,b=&gt;2'::hstore)</literal></entry>
-      <entry><literal>"a"=>"1"</literal></entry>
+      <entry><literal>"a"=&gt;"1"</literal></entry>
      </row>
 
      <row>
-      <entry><function>populate_record(record,hstore)</function></entry>
+      <entry><function>populate_record(record,hstore)</function><indexterm><primary>populate_record</primary></indexterm></entry>
       <entry><type>record</type></entry>
       <entry>replace fields in <type>record</> with matching values from <type>hstore</></entry>
       <entry>see Examples section</entry>
@@ -414,8 +432,10 @@ b
 
   <note>
    <para>
-     The function <function>hstore_to_json</function> is used when an <type>hstore</type>
-     value is cast to <type>json</type>.
+     The function <function>hstore_to_json</function> is used when
+     an <type>hstore</type> value is cast to <type>json</type>.
+     Likewise, <function>hstore_to_jsonb</function> is used when
+     an <type>hstore</type> value is cast to <type>jsonb</type>.
    </para>
   </note>
 
@@ -596,6 +616,25 @@ ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
 
  </sect2>
 
+ <sect2>
+  <title>Transforms</title>
+
+  <para>
+   Additional extensions are available that implement transforms for
+   the <type>hstore</type> type for the languages PL/Perl and PL/Python.  The
+   extensions for PL/Perl are called <literal>hstore_plperl</literal>
+   and <literal>hstore_plperlu</literal>, for trusted and untrusted PL/Perl.
+   If you install these transforms and specify them when creating a
+   function, <type>hstore</type> values are mapped to Perl hashes.  The
+   extensions for PL/Python are
+   called <literal>hstore_plpythonu</literal>, <literal>hstore_plpython2u</literal>,
+   and <literal>hstore_plpython3u</literal>
+   (see <xref linkend="plpython-python23"> for the PL/Python naming
+   convention).  If you use them, <type>hstore</type> values are mapped to
+   Python dictionaries.
+  </para>
+ </sect2>
+
  <sect2>
   <title>Authors</title>