|  | @@ -19,7 +19,7 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <P>
 | 
	
		
			
				|  |  |  <SMALL>
 | 
	
		
			
				|  |  | -Copyright © 2015–2016 Lua.org, PUC-Rio.
 | 
	
		
			
				|  |  | +Copyright © 2015–2017 Lua.org, PUC-Rio.
 | 
	
		
			
				|  |  |  Freely available under the terms of the
 | 
	
		
			
				|  |  |  <a href="http://www.lua.org/license.html">Lua license</a>.
 | 
	
		
			
				|  |  |  </SMALL>
 | 
	
	
		
			
				|  | @@ -35,7 +35,7 @@ Freely available under the terms of the
 | 
	
		
			
				|  |  |  <!-- ====================================================================== -->
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | -<!-- $Id: manual.of,v 1.162 2016/05/30 15:57:03 roberto Exp $ -->
 | 
	
		
			
				|  |  | +<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ -->
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -216,7 +216,7 @@ an associated value <b>nil</b>.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Tables are the sole data-structuring mechanism in Lua;
 | 
	
		
			
				|  |  | -they can be used to represent ordinary arrays, sequences,
 | 
	
		
			
				|  |  | +they can be used to represent ordinary arrays, lists,
 | 
	
		
			
				|  |  |  symbol tables, sets, records, graphs, trees, etc.
 | 
	
		
			
				|  |  |  To represent records, Lua uses the field name as an index.
 | 
	
		
			
				|  |  |  The language supports this representation by
 | 
	
	
		
			
				|  | @@ -226,13 +226,6 @@ There are several convenient ways to create tables in Lua
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -We use the term <em>sequence</em> to denote a table where
 | 
	
		
			
				|  |  | -the set of all positive numeric keys is equal to {1..<em>n</em>}
 | 
	
		
			
				|  |  | -for some non-negative integer <em>n</em>,
 | 
	
		
			
				|  |  | -which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>).
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -<p>
 | 
	
		
			
				|  |  |  Like indices,
 | 
	
		
			
				|  |  |  the values of table fields can be of any type.
 | 
	
		
			
				|  |  |  In particular,
 | 
	
	
		
			
				|  | @@ -378,6 +371,9 @@ so, an error inside the message handler
 | 
	
		
			
				|  |  |  will call the message handler again.
 | 
	
		
			
				|  |  |  If this loop goes on for too long,
 | 
	
		
			
				|  |  |  Lua breaks it and returns an appropriate message.
 | 
	
		
			
				|  |  | +(The message handler is called only for regular runtime errors.
 | 
	
		
			
				|  |  | +It is not called for memory-allocation errors
 | 
	
		
			
				|  |  | +nor for errors while running finalizers.)
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -873,7 +869,7 @@ before the change takes effect.
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Only objects that have an explicit construction
 | 
	
		
			
				|  |  |  are removed from weak tables.
 | 
	
		
			
				|  |  | -Values, such as numbers and light C functions,
 | 
	
		
			
				|  |  | +Values, such as numbers and light C functions,
 | 
	
		
			
				|  |  |  are not subject to garbage collection,
 | 
	
		
			
				|  |  |  and therefore are not removed from weak tables
 | 
	
		
			
				|  |  |  (unless their associated values are collected).
 | 
	
	
		
			
				|  | @@ -1084,7 +1080,7 @@ Lua is a case-sensitive language:
 | 
	
		
			
				|  |  |  <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
 | 
	
		
			
				|  |  |  are two different, valid names.
 | 
	
		
			
				|  |  |  As a convention,
 | 
	
		
			
				|  |  | -programs should avoid creating 
 | 
	
		
			
				|  |  | +programs should avoid creating
 | 
	
		
			
				|  |  |  names that start with an underscore followed by
 | 
	
		
			
				|  |  |  one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -1101,7 +1097,7 @@ The following strings denote other tokens:
 | 
	
		
			
				|  |  |  </pre>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -<em>Literal strings</em>
 | 
	
		
			
				|  |  | +A <em>short literal string</em>
 | 
	
		
			
				|  |  |  can be delimited by matching single or double quotes,
 | 
	
		
			
				|  |  |  and can contain the following C-like escape sequences:
 | 
	
		
			
				|  |  |  '<code>\a</code>' (bell),
 | 
	
	
		
			
				|  | @@ -1114,7 +1110,7 @@ and can contain the following C-like escape sequences:
 | 
	
		
			
				|  |  |  '<code>\\</code>' (backslash),
 | 
	
		
			
				|  |  |  '<code>\"</code>' (quotation mark [double quote]),
 | 
	
		
			
				|  |  |  and '<code>\'</code>' (apostrophe [single quote]).
 | 
	
		
			
				|  |  | -A backslash followed by a real newline
 | 
	
		
			
				|  |  | +A backslash followed by a line break
 | 
	
		
			
				|  |  |  results in a newline in the string.
 | 
	
		
			
				|  |  |  The escape sequence '<code>\z</code>' skips the following span
 | 
	
		
			
				|  |  |  of white-space characters,
 | 
	
	
		
			
				|  | @@ -1122,13 +1118,13 @@ including line breaks;
 | 
	
		
			
				|  |  |  it is particularly useful to break and indent a long literal string
 | 
	
		
			
				|  |  |  into multiple lines without adding the newlines and spaces
 | 
	
		
			
				|  |  |  into the string contents.
 | 
	
		
			
				|  |  | +A short literal string cannot contain unescaped line breaks
 | 
	
		
			
				|  |  | +nor escapes not forming a valid escape sequence.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Strings in Lua can contain any 8-bit value, including embedded zeros,
 | 
	
		
			
				|  |  | -which can be specified as '<code>\0</code>'.
 | 
	
		
			
				|  |  | -More generally,
 | 
	
		
			
				|  |  | -we can specify any byte in a literal string by its numeric value.
 | 
	
		
			
				|  |  | +We can specify any byte in a short literal string by its numeric value
 | 
	
		
			
				|  |  | +(including embedded zeros).
 | 
	
		
			
				|  |  |  This can be done
 | 
	
		
			
				|  |  |  with the escape sequence <code>\x<em>XX</em></code>,
 | 
	
		
			
				|  |  |  where <em>XX</em> is a sequence of exactly two hexadecimal digits,
 | 
	
	
		
			
				|  | @@ -1172,17 +1168,6 @@ is converted to a simple newline.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Any byte in a literal string not
 | 
	
		
			
				|  |  | -explicitly affected by the previous rules represents itself.
 | 
	
		
			
				|  |  | -However, Lua opens files for parsing in text mode,
 | 
	
		
			
				|  |  | -and the system file functions may have problems with
 | 
	
		
			
				|  |  | -some control characters.
 | 
	
		
			
				|  |  | -So, it is safer to represent
 | 
	
		
			
				|  |  | -non-text data as a quoted literal with
 | 
	
		
			
				|  |  | -explicit escape sequences for the non-text characters.
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -<p>
 | 
	
		
			
				|  |  |  For convenience,
 | 
	
		
			
				|  |  |  when the opening long bracket is immediately followed by a newline,
 | 
	
		
			
				|  |  |  the newline is not included in the string.
 | 
	
	
		
			
				|  | @@ -1203,6 +1188,17 @@ the five literal strings below denote the same string:
 | 
	
		
			
				|  |  |  </pre>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | +Any byte in a literal string not
 | 
	
		
			
				|  |  | +explicitly affected by the previous rules represents itself.
 | 
	
		
			
				|  |  | +However, Lua opens files for parsing in text mode,
 | 
	
		
			
				|  |  | +and the system file functions may have problems with
 | 
	
		
			
				|  |  | +some control characters.
 | 
	
		
			
				|  |  | +So, it is safer to represent
 | 
	
		
			
				|  |  | +non-text data as a quoted literal with
 | 
	
		
			
				|  |  | +explicit escape sequences for the non-text characters.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  |  A <em>numeric constant</em> (or <em>numeral</em>)
 | 
	
		
			
				|  |  |  can be written with an optional fractional part
 | 
	
		
			
				|  |  |  and an optional decimal exponent,
 | 
	
	
		
			
				|  | @@ -1212,7 +1208,7 @@ which start with <code>0x</code> or <code>0X</code>.
 | 
	
		
			
				|  |  |  Hexadecimal constants also accept an optional fractional part
 | 
	
		
			
				|  |  |  plus an optional binary exponent,
 | 
	
		
			
				|  |  |  marked by a letter '<code>p</code>' or '<code>P</code>'.
 | 
	
		
			
				|  |  | -A numeric constant with a radix point or an exponent 
 | 
	
		
			
				|  |  | +A numeric constant with a radix point or an exponent
 | 
	
		
			
				|  |  |  denotes a float;
 | 
	
		
			
				|  |  |  otherwise,
 | 
	
		
			
				|  |  |  if its value fits in an integer,
 | 
	
	
		
			
				|  | @@ -1897,7 +1893,7 @@ so that it works for non-integer exponents too.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Floor division (<code>//</code>) is a division 
 | 
	
		
			
				|  |  | +Floor division (<code>//</code>) is a division
 | 
	
		
			
				|  |  |  that rounds the quotient towards minus infinity,
 | 
	
		
			
				|  |  |  that is, the floor of the division of its operands.
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -1959,7 +1955,7 @@ this is called the <em>usual rule</em>.
 | 
	
		
			
				|  |  |  The C API also converts both integers to floats and
 | 
	
		
			
				|  |  |  floats to integers, as needed.
 | 
	
		
			
				|  |  |  Moreover, string concatenation accepts numbers as arguments,
 | 
	
		
			
				|  |  | -besides strings. 
 | 
	
		
			
				|  |  | +besides strings.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
	
		
			
				|  | @@ -1997,7 +1993,7 @@ is converted to the type (float or integer) required by the context
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -All conversions from strings to numbers 
 | 
	
		
			
				|  |  | +All conversions from strings to numbers
 | 
	
		
			
				|  |  |  accept both a dot and the current locale mark
 | 
	
		
			
				|  |  |  as the radix character.
 | 
	
		
			
				|  |  |  (The Lua lexer, however, accepts only a dot.)
 | 
	
	
		
			
				|  | @@ -2140,37 +2136,66 @@ Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&s
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  The length operator is denoted by the unary prefix operator <code>#</code>.
 | 
	
		
			
				|  |  | -The length of a string is its number of bytes
 | 
	
		
			
				|  |  | -(that is, the usual meaning of string length when each
 | 
	
		
			
				|  |  | -character is one byte).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -A program can modify the behavior of the length operator for
 | 
	
		
			
				|  |  | -any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
 | 
	
		
			
				|  |  | +The length of a string is its number of bytes
 | 
	
		
			
				|  |  | +(that is, the usual meaning of string length when each
 | 
	
		
			
				|  |  | +character is one byte).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Unless a <code>__len</code> metamethod is given,
 | 
	
		
			
				|  |  | -the length of a table <code>t</code> is only defined if the
 | 
	
		
			
				|  |  | -table is a <em>sequence</em>,
 | 
	
		
			
				|  |  | -that is,
 | 
	
		
			
				|  |  | -the set of its positive numeric keys is equal to <em>{1..n}</em>
 | 
	
		
			
				|  |  | -for some non-negative integer <em>n</em>.
 | 
	
		
			
				|  |  | -In that case, <em>n</em> is its length.
 | 
	
		
			
				|  |  | -Note that a table like
 | 
	
		
			
				|  |  | +The length operator applied on a table
 | 
	
		
			
				|  |  | +returns a border in that table.
 | 
	
		
			
				|  |  | +A <em>border</em> in a table <code>t</code> is any natural number
 | 
	
		
			
				|  |  | +that satisfies the following condition:
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <pre>
 | 
	
		
			
				|  |  | -     {10, 20, nil, 40}
 | 
	
		
			
				|  |  | +     (border == 0 or t[border] ~= nil) and t[border + 1] == nil
 | 
	
		
			
				|  |  |  </pre><p>
 | 
	
		
			
				|  |  | -is not a sequence, because it has the key <code>4</code>
 | 
	
		
			
				|  |  | -but does not have the key <code>3</code>.
 | 
	
		
			
				|  |  | -(So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal
 | 
	
		
			
				|  |  | -to the set of positive numeric keys of that table.)
 | 
	
		
			
				|  |  | -Note, however, that non-numeric keys do not interfere
 | 
	
		
			
				|  |  | +In words,
 | 
	
		
			
				|  |  | +a border is any (natural) index in a table
 | 
	
		
			
				|  |  | +where a non-nil value is followed by a nil value
 | 
	
		
			
				|  |  | +(or zero, when index 1 is nil).
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +A table with exactly one border is called a <em>sequence</em>.
 | 
	
		
			
				|  |  | +For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
 | 
	
		
			
				|  |  | +as it has only one border (5).
 | 
	
		
			
				|  |  | +The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
 | 
	
		
			
				|  |  | +and therefore it is not a sequence.
 | 
	
		
			
				|  |  | +The table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
 | 
	
		
			
				|  |  | +has three borders (0, 3, and 6),
 | 
	
		
			
				|  |  | +so it is not a sequence, too.
 | 
	
		
			
				|  |  | +The table <code>{}</code> is a sequence with border 0.
 | 
	
		
			
				|  |  | +Note that non-natural keys do not interfere
 | 
	
		
			
				|  |  |  with whether a table is a sequence.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +When <code>t</code> is a sequence,
 | 
	
		
			
				|  |  | +<code>#t</code> returns its only border,
 | 
	
		
			
				|  |  | +which corresponds to the intuitive notion of the length of the sequence.
 | 
	
		
			
				|  |  | +When <code>t</code> is not a sequence,
 | 
	
		
			
				|  |  | +<code>#t</code> can return any of its borders.
 | 
	
		
			
				|  |  | +(The exact one depends on details of
 | 
	
		
			
				|  |  | +the internal representation of the table,
 | 
	
		
			
				|  |  | +which in turn can depend on how the table was populated and
 | 
	
		
			
				|  |  | +the memory addresses of its non-numeric keys.)
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +The computation of the length of a table
 | 
	
		
			
				|  |  | +has a guaranteed worst time of <em>O(log n)</em>,
 | 
	
		
			
				|  |  | +where <em>n</em> is the largest natural key in the table.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +A program can modify the behavior of the length operator for
 | 
	
		
			
				|  |  | +any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -2585,6 +2610,28 @@ However, you can change this behavior by compiling Lua
 | 
	
		
			
				|  |  |  with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +The Lua library is fully reentrant:
 | 
	
		
			
				|  |  | +it has no global variables.
 | 
	
		
			
				|  |  | +It keeps all information it needs in a dynamic structure,
 | 
	
		
			
				|  |  | +called the <em>Lua state</em>.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +Each Lua state has one or more threads,
 | 
	
		
			
				|  |  | +which correspond to independent, cooperative lines of execution.
 | 
	
		
			
				|  |  | +The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
 | 
	
		
			
				|  |  | +(Indirectly, through the thread, it also refers to the
 | 
	
		
			
				|  |  | +Lua state associated to the thread.)
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +A pointer to a thread must be passed as the first argument to
 | 
	
		
			
				|  |  | +every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
 | 
	
		
			
				|  |  | +which creates a Lua state from scratch and returns a pointer
 | 
	
		
			
				|  |  | +to the <em>main thread</em> in the new state.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <h2>4.1 – <a name="4.1">The Stack</a></h2>
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -2592,6 +2639,8 @@ with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a>
 | 
	
		
			
				|  |  |  Lua uses a <em>virtual stack</em> to pass values to and from C.
 | 
	
		
			
				|  |  |  Each element in this stack represents a Lua value
 | 
	
		
			
				|  |  |  (<b>nil</b>, number, string, etc.).
 | 
	
		
			
				|  |  | +Functions in the API can access this stack through the
 | 
	
		
			
				|  |  | +Lua state parameter that they receive.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
	
		
			
				|  | @@ -2599,7 +2648,8 @@ Whenever Lua calls C, the called function gets a new stack,
 | 
	
		
			
				|  |  |  which is independent of previous stacks and of stacks of
 | 
	
		
			
				|  |  |  C functions that are still active.
 | 
	
		
			
				|  |  |  This stack initially contains any arguments to the C function
 | 
	
		
			
				|  |  | -and it is where the C function pushes its results
 | 
	
		
			
				|  |  | +and it is where the C function can store temporary
 | 
	
		
			
				|  |  | +Lua values and must push its results
 | 
	
		
			
				|  |  |  to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -2791,8 +2841,7 @@ Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
 | 
	
		
			
				|  |  |  (Lua will use exceptions if you compile it as C++;
 | 
	
		
			
				|  |  |  search for <code>LUAI_THROW</code> in the source code for details.)
 | 
	
		
			
				|  |  |  When Lua faces any error
 | 
	
		
			
				|  |  | -(such as a memory allocation error, type errors, syntax errors,
 | 
	
		
			
				|  |  | -and runtime errors)
 | 
	
		
			
				|  |  | +(such as a memory allocation error or a type error)
 | 
	
		
			
				|  |  |  it <em>raises</em> an error;
 | 
	
		
			
				|  |  |  that is, it does a long jump.
 | 
	
		
			
				|  |  |  A <em>protected environment</em> uses <code>setjmp</code>
 | 
	
	
		
			
				|  | @@ -2801,6 +2850,17 @@ any error jumps to the most recent active recovery point.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | +Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +Most functions in the API can raise an error,
 | 
	
		
			
				|  |  | +for instance due to a memory allocation error.
 | 
	
		
			
				|  |  | +The documentation for each function indicates whether
 | 
	
		
			
				|  |  | +it can raise errors.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  |  If an error happens outside any protected environment,
 | 
	
		
			
				|  |  |  Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
 | 
	
		
			
				|  |  |  and then calls <code>abort</code>,
 | 
	
	
		
			
				|  | @@ -2811,6 +2871,23 @@ never returning
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | +The panic function,
 | 
	
		
			
				|  |  | +as its name implies,
 | 
	
		
			
				|  |  | +is a mechanism of last resort.
 | 
	
		
			
				|  |  | +Programs should avoid it.
 | 
	
		
			
				|  |  | +As a general rule,
 | 
	
		
			
				|  |  | +when a C function is called by Lua with a Lua state,
 | 
	
		
			
				|  |  | +it can do whatever it wants on that Lua state,
 | 
	
		
			
				|  |  | +as it should be already protected.
 | 
	
		
			
				|  |  | +However,
 | 
	
		
			
				|  |  | +when C code operates on other Lua states
 | 
	
		
			
				|  |  | +(e.g., a Lua parameter to the function,
 | 
	
		
			
				|  |  | +a Lua state stored in the registry, or
 | 
	
		
			
				|  |  | +the result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
 | 
	
		
			
				|  |  | +it should use them only in API calls that cannot raise errors.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  |  The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
 | 
	
		
			
				|  |  |  in particular, the error object is at the top of the stack.
 | 
	
		
			
				|  |  |  However, there is no guarantee about stack space.
 | 
	
	
		
			
				|  | @@ -2818,17 +2895,6 @@ To push anything on the stack,
 | 
	
		
			
				|  |  |  the panic function must first check the available space (see <a href="#4.2">§4.2</a>).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | -<p>
 | 
	
		
			
				|  |  | -Most functions in the API can raise an error,
 | 
	
		
			
				|  |  | -for instance due to a memory allocation error.
 | 
	
		
			
				|  |  | -The documentation for each function indicates whether
 | 
	
		
			
				|  |  | -it can raise errors.
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -<p>
 | 
	
		
			
				|  |  | -Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -2836,7 +2902,7 @@ Inside a C function you can raise an error by calling <a href="#lua_error">
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
 | 
	
		
			
				|  |  | -Therefore, if a C function <code>foo</code> calls an API function
 | 
	
		
			
				|  |  | +Therefore, if a C function <code>foo</code> calls an API function
 | 
	
		
			
				|  |  |  and this API function yields
 | 
	
		
			
				|  |  |  (directly or indirectly by calling another function that yields),
 | 
	
		
			
				|  |  |  Lua cannot return to <code>foo</code> any more,
 | 
	
	
		
			
				|  | @@ -2854,7 +2920,7 @@ All those functions receive a <em>continuation function</em>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  We need to set some terminology to explain continuations.
 | 
	
		
			
				|  |  | -We have a C function called from Lua which we will call
 | 
	
		
			
				|  |  | +We have a C function called from Lua which we will call
 | 
	
		
			
				|  |  |  the <em>original function</em>.
 | 
	
		
			
				|  |  |  This original function then calls one of those three functions in the C API,
 | 
	
		
			
				|  |  |  which we will call the <em>callee function</em>,
 | 
	
	
		
			
				|  | @@ -3169,7 +3235,7 @@ when the function is called.
 | 
	
		
			
				|  |  |  The function results are pushed onto the stack when the function returns.
 | 
	
		
			
				|  |  |  The number of results is adjusted to <code>nresults</code>,
 | 
	
		
			
				|  |  |  unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
 | 
	
		
			
				|  |  | -In this case, all results from the function are pushed.
 | 
	
		
			
				|  |  | +In this case, all results from the function are pushed;
 | 
	
		
			
				|  |  |  Lua takes care that the returned values fit into the stack space,
 | 
	
		
			
				|  |  |  but it does not ensure any extra space in the stack.
 | 
	
		
			
				|  |  |  The function results are pushed onto the stack in direct order
 | 
	
	
		
			
				|  | @@ -3655,7 +3721,7 @@ in particular, 0 means an empty stack.
 | 
	
		
			
				|  |  |  <pre>int lua_getuservalue (lua_State *L, int index);</pre>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Pushes onto the stack the Lua value associated with the userdata
 | 
	
		
			
				|  |  | +Pushes onto the stack the Lua value associated with the full userdata
 | 
	
		
			
				|  |  |  at the given index.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -3998,7 +4064,8 @@ Creates a new thread running in a new, independent state.
 | 
	
		
			
				|  |  |  Returns <code>NULL</code> if it cannot create the thread or the state
 | 
	
		
			
				|  |  |  (due to lack of memory).
 | 
	
		
			
				|  |  |  The argument <code>f</code> is the allocator function;
 | 
	
		
			
				|  |  | -Lua does all memory allocation for this state through this function.
 | 
	
		
			
				|  |  | +Lua does all memory allocation for this state
 | 
	
		
			
				|  |  | +through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
 | 
	
		
			
				|  |  |  The second argument, <code>ud</code>, is an opaque pointer that Lua
 | 
	
		
			
				|  |  |  passes to the allocator in every call.
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -4202,7 +4269,9 @@ error while running the message handler.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
 | 
	
		
			
				|  |  |  error while running a <code>__gc</code> metamethod.
 | 
	
		
			
				|  |  | -(This error typically has no relation with the function being called.)
 | 
	
		
			
				|  |  | +For such errors, Lua does not call the message handler
 | 
	
		
			
				|  |  | +(as this kind of error typically has no relation
 | 
	
		
			
				|  |  | +with the function being called).
 | 
	
		
			
				|  |  |  </li>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  </ul>
 | 
	
	
		
			
				|  | @@ -4278,7 +4347,7 @@ The maximum value for <code>n</code> is 255.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  When <code>n</code> is zero,
 | 
	
		
			
				|  |  | -this function creates a <em>light C function</em>,
 | 
	
		
			
				|  |  | +this function creates a <em>light C function</em>,
 | 
	
		
			
				|  |  |  which is just a pointer to the C function.
 | 
	
		
			
				|  |  |  In that case, it never raises a memory error.
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -4292,7 +4361,7 @@ In that case, it never raises a memory error.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Pushes a C function onto the stack.
 | 
	
		
			
				|  |  | -This function receives a pointer to a C function
 | 
	
		
			
				|  |  | +This function receives a pointer to a C function
 | 
	
		
			
				|  |  |  and pushes onto the stack a Lua value of type <code>function</code> that,
 | 
	
		
			
				|  |  |  when called, invokes the corresponding C function.
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -4667,7 +4736,7 @@ The reader function may return pieces of any size greater than zero.
 | 
	
		
			
				|  |  |  <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Sets the C function <code>f</code> as the new value of global <code>name</code>.
 | 
	
		
			
				|  |  | +Sets the C function <code>f</code> as the new value of global <code>name</code>.
 | 
	
		
			
				|  |  |  It is defined as a macro:
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <pre>
 | 
	
	
		
			
				|  | @@ -4888,7 +4957,7 @@ If <code>index</code> is 0, then all stack elements are removed.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Pops a value from the stack and sets it as
 | 
	
		
			
				|  |  | -the new value associated to the userdata at the given index.
 | 
	
		
			
				|  |  | +the new value associated to the full userdata at the given index.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -5302,7 +5371,7 @@ that will be passed as results to <a href="#lua_resume"><code>lua_resume</code><
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  When the coroutine is resumed again,
 | 
	
		
			
				|  |  |  Lua calls the given continuation function <code>k</code> to continue
 | 
	
		
			
				|  |  | -the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
 | 
	
		
			
				|  |  | +the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
 | 
	
		
			
				|  |  |  This continuation function receives the same stack
 | 
	
		
			
				|  |  |  from the previous function,
 | 
	
		
			
				|  |  |  with the <code>n</code> results removed and
 | 
	
	
		
			
				|  | @@ -6013,7 +6082,7 @@ If it is not, raises an error with a standard message (see <a href="#luaL_argerr
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Raises an error reporting a problem with argument <code>arg</code>
 | 
	
		
			
				|  |  | -of the C function that called it,
 | 
	
		
			
				|  |  | +of the C function that called it,
 | 
	
		
			
				|  |  |  using a standard message
 | 
	
		
			
				|  |  |  that includes <code>extramsg</code> as a comment:
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -6534,7 +6603,8 @@ The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
 | 
	
		
			
				|  |  |  but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
 | 
	
		
			
				|  |  | -if it cannot open/read the file or the file has a wrong mode.
 | 
	
		
			
				|  |  | +for file-related errors
 | 
	
		
			
				|  |  | +(e.g., it cannot open or read the file).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
	
		
			
				|  | @@ -6727,6 +6797,11 @@ If the result is <code>NULL</code>
 | 
	
		
			
				|  |  |  its length is considered zero.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | +<p>
 | 
	
		
			
				|  |  | +This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
 | 
	
		
			
				|  |  | +so all conversions and caveats of that function apply here.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -7674,7 +7749,7 @@ Returns true when the running coroutine can yield.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  A running coroutine is yieldable if it is not the main thread and
 | 
	
		
			
				|  |  | -it is not inside a non-yieldable C function.
 | 
	
		
			
				|  |  | +it is not inside a non-yieldable C function.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -7876,8 +7951,8 @@ The path used by <a href="#pdf-require"><code>require</code></a> to search for a
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
 | 
	
		
			
				|  |  |  it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
 | 
	
		
			
				|  |  | -using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
 | 
	
		
			
				|  |  | -or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
 | 
	
		
			
				|  |  | +using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>,
 | 
	
		
			
				|  |  | +or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
 | 
	
		
			
				|  |  |  or a default path defined in <code>luaconf.h</code>.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -8434,7 +8509,7 @@ its default value is 1 and can be negative.
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
 | 
	
		
			
				|  |  |  packed (that is, serialized in binary form)
 | 
	
		
			
				|  |  | -according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 
 | 
	
		
			
				|  |  | +according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -8485,7 +8560,8 @@ If <code>j</code> is absent, then it is assumed to be equal to -1
 | 
	
		
			
				|  |  |  In particular,
 | 
	
		
			
				|  |  |  the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
 | 
	
		
			
				|  |  |  with length <code>j</code>,
 | 
	
		
			
				|  |  | -and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
 | 
	
		
			
				|  |  | +and <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
 | 
	
		
			
				|  |  | +returns a suffix of <code>s</code>
 | 
	
		
			
				|  |  |  with length <code>i</code>.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -8902,7 +8978,7 @@ Returns the number of UTF-8 characters in string <code>s</code>
 | 
	
		
			
				|  |  |  that start between positions <code>i</code> and <code>j</code> (both inclusive).
 | 
	
		
			
				|  |  |  The default for <code>i</code> is 1 and for <code>j</code> is -1.
 | 
	
		
			
				|  |  |  If it finds any invalid byte sequence,
 | 
	
		
			
				|  |  | -returns a false value plus the position of the first invalid byte. 
 | 
	
		
			
				|  |  | +returns a false value plus the position of the first invalid byte.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -8946,8 +9022,7 @@ It provides all its functions inside the table <a name="pdf-table"><code>table</
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Remember that, whenever an operation needs the length of a table,
 | 
	
		
			
				|  |  | -the table must be a proper sequence
 | 
	
		
			
				|  |  | -or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>).
 | 
	
		
			
				|  |  | +all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>).
 | 
	
		
			
				|  |  |  All functions ignore non-numeric keys
 | 
	
		
			
				|  |  |  in the tables given as arguments.
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -9063,9 +9138,8 @@ Otherwise, no valid sort may be possible.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -The sort algorithm is not stable;
 | 
	
		
			
				|  |  | -that is, elements not comparable by the given order
 | 
	
		
			
				|  |  | -(e.g., equal elements)
 | 
	
		
			
				|  |  | +The sort algorithm is not stable:
 | 
	
		
			
				|  |  | +elements considered equal by the given order
 | 
	
		
			
				|  |  |  may have their relative positions changed by the sort.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -9401,7 +9475,7 @@ or <b>nil</b> if <code>x</code> is not a number.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Returns a boolean,
 | 
	
		
			
				|  |  | -true if integer <code>m</code> is below integer <code>n</code> when
 | 
	
		
			
				|  |  | +true if and only if integer <code>m</code> is below integer <code>n</code> when
 | 
	
		
			
				|  |  |  they are compared as unsigned integers.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -9987,6 +10061,7 @@ Deletes the file (or empty directory, on POSIX systems)
 | 
	
		
			
				|  |  |  with the given name.
 | 
	
		
			
				|  |  |  If this function fails, it returns <b>nil</b>,
 | 
	
		
			
				|  |  |  plus a string describing the error and the error code.
 | 
	
		
			
				|  |  | +Otherwise, it returns true.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -9996,9 +10071,10 @@ plus a string describing the error and the error code.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -Renames file or directory named <code>oldname</code> to <code>newname</code>.
 | 
	
		
			
				|  |  | +Renames the file or directory named <code>oldname</code> to <code>newname</code>.
 | 
	
		
			
				|  |  |  If this function fails, it returns <b>nil</b>,
 | 
	
		
			
				|  |  |  plus a string describing the error and the error code.
 | 
	
		
			
				|  |  | +Otherwise, it returns true.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -10291,7 +10367,7 @@ represent variables with no known names
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  Returns the Lua value associated to <code>u</code>.
 | 
	
		
			
				|  |  | -If <code>u</code> is not a userdata,
 | 
	
		
			
				|  |  | +If <code>u</code> is not a full userdata,
 | 
	
		
			
				|  |  |  returns <b>nil</b>.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
	
		
			
				|  | @@ -10490,7 +10566,7 @@ and as <code>lua -</code> otherwise.
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  | -When called without option <code>-E</code>, 
 | 
	
		
			
				|  |  | +When called without option <code>-E</code>,
 | 
	
		
			
				|  |  |  the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
 | 
	
		
			
				|  |  |  (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
 | 
	
		
			
				|  |  |  before running any argument.
 | 
	
	
		
			
				|  | @@ -10582,7 +10658,7 @@ its value is used as the secondary prompt
 | 
	
		
			
				|  |  |  <p>
 | 
	
		
			
				|  |  |  In case of unprotected errors in the script,
 | 
	
		
			
				|  |  |  the interpreter reports the error to the standard error stream.
 | 
	
		
			
				|  |  | -If the error object is not a string but 
 | 
	
		
			
				|  |  | +If the error object is not a string but
 | 
	
		
			
				|  |  |  has a metamethod <code>__tostring</code>,
 | 
	
		
			
				|  |  |  the interpreter calls this metamethod to produce the final message.
 | 
	
		
			
				|  |  |  Otherwise, the interpreter converts the error object to a string
 | 
	
	
		
			
				|  | @@ -10897,13 +10973,12 @@ and LiteralString, see <a href="#3.1">§3.1</a>.)
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  | -
 | 
	
		
			
				|  |  |  <P CLASS="footer">
 | 
	
		
			
				|  |  |  Last update:
 | 
	
		
			
				|  |  | -Mon May 30 13:11:08 BRT 2016
 | 
	
		
			
				|  |  | +Mon Jan  9 13:30:53 BRST 2017
 | 
	
		
			
				|  |  |  </P>
 | 
	
		
			
				|  |  |  <!--
 | 
	
		
			
				|  |  | -Last change: revised for Lua 5.3.3
 | 
	
		
			
				|  |  | +Last change: revised for Lua 5.3.4
 | 
	
		
			
				|  |  |  -->
 | 
	
		
			
				|  |  |  
 | 
	
		
			
				|  |  |  </body></html>
 |