From 43bee39b29806103dea35816e3e8f2842a525c12 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Wed, 16 Jul 2014 14:51:02 -0600
Subject: [PATCH] stored-procedures.xml uuid package
---
doc/user/stored-procedures.xml | 141 ++++++++++++++++++++++++++++-----
1 file changed, 119 insertions(+), 22 deletions(-)
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index c50ad8fd4f..cd1ece8e8b 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -508,53 +508,150 @@ Password is not valid
<section xml:id="sp-box-uuid">
<title>Package <code>uuid</code></title>
+
+<para>
+ A "UUID" is a
+ <link xlink:href="https://en.wikipedia.org/wiki/Universally_unique_identifier">Universally unique identifier</link>.
+ If an application requires that a value be unique only within a single computer or
+ on a single database, then a simple counter is better than a UUID, because getting
+ a UUID is time-consuming (it requires a
+ <link xlink:href="https://en.wikipedia.org/wiki/Syscall">syscall</link>).
+ For clusters of computers, or widely distributed applications, UUIDs are better.
+</para>
+<para>
+ The functions that can return a UUID are: <code>uuid()</code>, <code>uuid.bin()</code>, <code>uuid.str()</code>.
+ The functions that can convert between different types of UUID are: <code>:bin()</code>, <code>:str()</code>, <code>uuid.fromstr()</code>, <code>uuid.frombin()</code>.
+ The function that can determine whether a UUID is an all-zero value is: <code>:isnil()</code>.
+</para>
+
<variablelist xml:id="x-uuid" xreflabel="x-uuid">
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua">uuid()</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Returns: a UUID with type = cdata.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<emphasis role="lua">uuid.bin()</emphasis>
</term>
<listitem>
<para>
- Returns: a 128-bit (16-byte) unique id in binary form.
+ Returns: a UUID with type = 16-byte binary string.
</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua">uuid.str()</emphasis>
+ </term>
+ <listitem>
<para>
- Possible errors: The server tries to load the <emphasis>libuuid</emphasis> library
- when it starts. If the library is not available, which can happen if it was not
- found when the server was built from source, then uuid.bin() returns an error.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>uuid=require('uuid')</userinput>
----
-...
-tarantool> <userinput>uuid.bin() == uuid.bin() -- Comment: == means "are they equal?"</userinput>
----
- - false
-...
-</programlisting>
+ Returns: a UUID with type = 36-byte hexadecimal string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua"><replaceable>uuid_with_type_cdata</replaceable>:bin([<replaceable>byte-order</replaceable>])</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Parameters: byte-order can be 'l' (little-endian), 'b' (big-endian), 'h' (endianness depends on host) (default), or 'n' (endiannes depends on network).
+ </para>
+ <para>
+ Returns: UUID with type = 16-byte binary string converted from cdata input value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua"> <replaceable>uuid_with_type_cdata</replaceable>:str()</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Returns: UUID with type = 36-byte hexadecimal string converted from cdata input value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua"> uuid.fromstr(<replaceable>uuid_with_type_string</replaceable>)</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Returns: UUID with type = cdata converted from 36-byte hexadecimal string input value.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
- <emphasis role="lua">uuid.hex()</emphasis>
+ <emphasis role="lua">uuid.frombin(<replaceable>uuid_with_type_binary_string</replaceable>)</emphasis>
</term>
<listitem>
<para>
- Returns: a 32-byte hexadecimal conversion of a 128-bit
- unique id, as a string.
+ Returns: UUID with type = cdata converted from 16-byte binary string input value.
</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role="lua">:isnil(<replaceable>uuid_with_type_cdata</replaceable>)</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Returns: true if the value is all zero, otherwise false.
+ The all-zero UUID value can be expressed as <code>uuid.NULL</code>, or as
+ uuid.fromstr('00000000-0000-0000-0000-000000000000').
+ The comparison with an all-zero value can also be expressed as
+ <replaceable>uuid_with_type_cdata</replaceable> == uuid.NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+<para>
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
-tarantool> <userinput>uuid=require('uuid')</userinput>
+tarantool> <userinput>uuid = require('uuid')</userinput>
+---
+...
+tarantool> <userinput>uuid(), uuid.bin(), uuid.str()</userinput>
---
+- 16ffedc8-cbae-4f93-a05e-349f3ab70baa
+- !!binary FvG+Vy1MfUC6kIyeM81DYw==
+- 67c999d2-5dce-4e58-be16-ac1bcb93160f
...
-tarantool> <userinput>uuid.hex()</userinput>
+tarantool> <userinput>uu = uuid()</userinput>
---
- - b8eadcb078b54bed8fa8425d129b10e8
+...
+tarantool> <userinput>#uu:bin(), #uu:str(), type(uu), uu:isnil()</userinput>
+---
+- 16
+- 36
+- cdata
+- false
...
</programlisting>
- </listitem>
- </varlistentry>
-</variablelist>
+</para>
+<para>
+ Possible errors: The server tries to load the <emphasis>libuuid</emphasis> library
+ when it starts. If the library is not available, which can happen if it was not
+ found when the server was built from source, then require('uuid') returns an error.
+</para>
+
</section>
<section xml:id="sp-box-cjson">
--
GitLab