Commits

Andrew Dunstan committed 9494f2c

add docco

  • Participants
  • Parent commits c59eb78
  • Branches jsonng

Comments (0)

Files changed (2)

File doc/src/sgml/func.sgml

        <entry><literal>row_to_json(row(1,'foo'))</literal></entry>
        <entry><literal>{"f1":1,"f2":"foo"}</literal></entry>
       </row>
+      <row>
+       <entry>
+         <indexterm>
+          <primary>to_json</primary>
+         </indexterm>
+         <literal>to_json(anyelement)</literal>
+       </entry>
+       <entry>
+         Returns the value as JSON. If the data type is not builtin, and there
+         is a cast from the type to json, the cast function will be used to
+         perform the conversion. Otherwise, for any value other than a number,
+         a boolean or NULL, the text representation will be used, escaped and
+         quoted so that it is legal JSON.
+       </entry>
+       <entry><literal>to_json('Fred said "Hi."'</literal></entry>
+       <entry><literal>"Fred said \"Hi.\""</literal></entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
 
+  <note>
+    <para>
+      The <xref linkend="hstore"> extension has a cast from hstore to 
+      json, so that converted hstore values are represented as json objects, 
+      not as string values.
+    </para>
+  </note>
+
+  <para>
+    See also <xref linkend="functions-aggregate"> about the aggregate
+    function <function>json_agg</function> which aggregates record 
+    values as json efficiently.
+  </para>
+
  </sect1>
 
  <sect1 id="functions-sequence">
      <row>
       <entry>
        <indexterm>
+        <primary>json_agg</primary>
+       </indexterm>
+       <function>json_agg(<replaceable class="parameter">record</replaceable>)</function>
+      </entry>
+      <entry>
+       <type>record</type>
+      </entry>
+      <entry>
+       <type>json</type>
+      </entry>
+      <entry>aggregates records as a json array of objects</entry>
+     </row>
+
+     <row>
+      <entry>
+       <indexterm>
         <primary>max</primary>
        </indexterm>
        <function>max(<replaceable class="parameter">expression</replaceable>)</function>
 
   <para>
    The aggregate functions <function>array_agg</function>,
+   <function>json_agg</function>,
    <function>string_agg</function>,
    and <function>xmlagg</function>, as well as similar user-defined
    aggregate functions, produce meaningfully different result values

File doc/src/sgml/hstore.sgml

      </row>
 
      <row>
+      <entry><function>hstore_to_json(hstore)</function></entry>
+      <entry><type>json</type></entry>
+      <entry>get <type>hstore</type> as a json value</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><type>json</type></entry>
+      <entry>get <type>hstore</type> as a json value, but attempting to distinguish numerical and boolean values so they are unquoted in the json</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": 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><type>hstore</type></entry>
       <entry>extract a subset of an <type>hstore</></entry>
 
   <note>
    <para>
+     The function <function>hstore_to_json</function> is used when an <type>hstore</type>
+     value is cast to <type>json</type>.
+   </para>
+  </note>
+
+  <note>
+   <para>
     The function <function>populate_record</function> is actually declared
     with <type>anyelement</>, not <type>record</>, as its first argument,
     but it will reject non-record types with a run-time error.