# Agena Changelog

## New in version 2.2.6

September 8th, 2014- `stats.chauvenet` can now check specifically for lower or upper outliers by passing the option `outlier='lower'` or `outlier='upper'`, respectively.
- `bags.remove` caused segmentation faults. This has been fixed. Moreover, all `bags` functions implemented in C have been internally changed.
- The (undocumented) metamethods for `+`, `-`, and `*` did not work if the `bags` package has not been invoked with the `with` function or the `import/alias` statement. This has been fixed.

### New in version 2.3.0 RC1 (September 8th, 2014)

- Numeric `for` loops now support the `downto' keyword so that you can count down without using an obligatory negative `by` step size. In the `downto' context, the `by' step size should always be positive. `from' start and `to' stop values are obligatory when using the `downto' keyword.
- The metamethods '__finite', '__entier', and '__sqrt' are no longer supported. Instead, three new metathods for operations on structures have been added: '__union' for union operations, '__intersect' to determine intersections, and '__minus' for differences. Thus, the `bags` package now also supports these three operations.
- The `\` integer division operator did not support its metamethod and used the one for float divison (`/` operator) instead. This has been fixed.
- The new function `stats.gini` determines the Gini coefficient, a measure of (in-)equality.
- The new function `stats.zscore` returns a function computing the z-score (standard score) of a sample - the number of standard deviations the sample is above or below the mean of a distribution.
- `stats.sorted` now by default uses the Introsort algorithm instead of Quicksort. This can speed up computation time thrice in ill-conditioned situations (where Quicksort would need O(n^2) operations), while not sacrificing performance in ordinary situations. Actually, Introsort uses Quicksort by default and then automatically switches to Heapsort if the recursion depth reaches 2*log(n, 2), where n is the number of elements in a structure.
- You may override this logic by passing the new option 'quicksort' which solely uses the traditional recursive Quicksort method to sort numbers. Also, `stats.sorted` now also can use the Heapsort algorithm exclusively if the new option 'heapsort' is being passed, and a non-recursive Quicksort algorithm devised by Niklaus Wirth with the new option 'nrquicksort'.
- The new function `stats.meanmed` returns both the arithmetic mean and the median of a distribution, or alternatively the quotient of the mean and the median, speeding up computation times when these values are needed by around 20 percent.
- Improved the error message of the `size` operator.

### New in version 2.1.1 (January 6th, 2014)

- New functions and patches:
- `try/catch`: explicit specification of an error variable right after the `catch` token is now optional. If no error variable is given, then the error message is automatically stored to the local `lasterror` variable, and the `then` keyword must be left out:
- > try
- > error('oops !')
- > catch
- > print(lasterror)
- > yrt;
- oops !
- The `try/catch` statement sometimes did not work in procedures (unassigned error variable). This has been fixed.
- The new `net.wget` function downloads HTML pages from the Web.
- Tuned `skycrane.counter` by 10 %. The function now optionally applies the Kahan-Ozawa instead of the original Kahan summation algorithm if the new third argument is the string 'ozawa'. The corresponding C sources have been modified to prevent compiler optimisation, which could cancel the optimisations, as well.
- `argerror` now prints the user-defined type name of a value received in its error message. If a value does not have a user-defined type, then its basic type is issued.
- The new 'a' option to `debug.getinfo` returns the number of arguments expected by a procedure, thanks to Rob Hoelz' LuaPowerPatch.
- Improved `index out-of-range` error message for strings.
- Modified the `stats.agn`, `linalg.agn`, `library.agn`, and `ansi.agn` files with respect to their error handling.

### New in version 2.1.0 (December 30th, 2013)

- For a new kind of error handling, the new `try/catch` statement has been introduced. It has been invented and written by Hu Qiwei for Lua 5.1 back in 2008.
- In general, any statements where an exception might be expected can be put into a `try` clause. If an error is issued, generated by an explicit call to the `error` function or to any other expression, function, or statement, control immediately jumps to the corresponding `catch` clause if present or to the end of the `try/yrt` statement if no `catch` clause has been given, ignoring any other subsequent statements in the `try` clause.
- The `protect/lasterror` error dealing facilities are still and will always be supported. The new control statement also works with the `break`, `skip`, `redo`, and `return` statements flawlessly.
- The new `redo` statement restarts the current iteration of a `for/to` and `for/in` loop from the beginning.
- The new `recip` operator returns the inverse of a number x. It is equivalent to the expression 1/x, but faster.
- The new `stats.ema` function computes the exponential moving average of a distribution. The new function `stats.gema` returns an iterator function returning the respective exponential moving average of a distribution.
- `*%`, `+%`, and `-%` returned `undefined` instead of a correct result if their right operand had been zero. This has been fixed.
- Fixed an error message in `net.survey`.
- Improved error messages for out-of-range indexing of pairs and strings.
- In the ANSI, Solaris, and DOS versions, the `int` operator has been tuned.
- The new C API function `agn_arraytoseq` converts a numeric array into a sequence and pushes this new sequence on top of the stack.
- Updated the manual.

### New in version 2.1.0 RC (December 19th, 2013)

- The new `redo` statement restarts the current iteration of a `for/to` and `for/in` loop from the beginning. Example:
- > flag := true; > for j in [10, 11, 12] do > print('before', j, flag); > if flag and j = 11 then > clear flag; > print(' -->', j, flag, 'jump back') > redo > fi; > print('after', j, flag) > until j > 12; before 10 true after 10 true before 11 true --> 11 false jump back before 11 false after 11 false before 12 false after 12 false
- The new `recip` operator returns the inverse of a number x. It is equivalent to the expression 1/x, but faster.
- The new `stats.ema` function computes the exponential moving average of a distribution. The new function `stats.gema` returns an iterator function returning the respective exponential moving average of a distribution. For its usage, please have a look into the src/stats.c source file, C functions *ema.
- `*%`, `+%`, and `-%` returned `undefined` instead of a correct result if their right operand had been zero. This has been fixed.
- Fixed an error message in `net.survey`.
- The new C API function `agn_arraytoseq` converts a numeric array into a sequence and pushes this new sequence on top of the stack.

### New in version 2.0.0 (December 2nd, 2013)

- New statements and functions:
- Agena 2.0 is downward-compatible to Agena 1.12, except that the tokens `import`, `alias`, `until`, and `onsuccess` are now keywords and can no longer be used as variables. Currently, there are Solaris, Debian (x86, PowerPC, Raspberry Pi), Windows, Mac, and DOS installers available for 2.0, including an updated Primer and Reference that explains all new features in detail.
- The new loop variants `for/as` and `for/until` check a condition at the end of the current iteration and either commence the next iteration or leave the loop. This works with both `for/to`, as well as `for/in` loops. In effect, both variants execute a loop at least once until the given condition is being checked.
- Examples:
- > for i to 5 do
- > print(i)
- > as i < 3
- > for i in [1, 2, 3, 4, 5] do
- > print(i)
- > until i >= 3
- The new `do/until` loop iterates until a certain condition is met:
- > c := 0;
- > do
- > inc c;
- > print(c)
- > until c >= 3
- In numeric `for` loops, the `to` clause may not be given any longer. Instead, when leaving out the `to` clause, the loop iterates until the largest number representable on your platform, in C HUGE_VAL, has been reached:
- > for i do
- > print(i)
- > od
- The new `onsuccess` clause in `if` and `case` statements executes a chunk if at least one of the conditions is true. Examples:
- > flag := false;
- > if 1 = 0 then
- > print(0)
- > elif 1 = 1 then
- > print(1)
- > onsuccess
- > flag := true
- > else
- > print(-1)
- > fi;
- > print(flag);
- true
- > flag := false;
- > if 1 = 0 then
- > print(0)
- > elif 1 = 0 then
- > print(1)
- > onsuccess
- > flag := true
- > else
- > print(-1)
- > fi;
- > print(flag);
- false
- > flag := false;
- > a := 2;
- > case a
- > of 1 then
- > print(1)
- > of 2 then
- > print(2)
- > onsuccess
- > flag := true
- > else
- > print(-1)
- > esac;
- > print(flag);
- true
- The new `import` statement allows to import one or more libraries without putting their names into quotes, e.g. "import calc, stats" is equivalent to "readlib('calc', 'stats')".
- The `alias` option to the `import` statement assigns one or more short names to the library functions initialised, e.g. "import calc alias xpdiff" is equivalent to "with('calc', 'xpdiff')", and "import calc alias" is equivalent to "with('calc')".
- The new `..` operator allows to index tables even if its left-hand side operand evaluates to `null`. In this case, `null` is returned and no `attempt to index field ... (a null value)` error is issued. It is similar to the `getentry` function but is three times faster. Examples:
- > create table a;
- > a.b:
- null
- > a.b.c:
- Error in stdin, at line 1:
- attempt to index field `b` (a null value)
- > a..b..c:
- null
- > create table a;
- > a[1]:
- null
- > a[1][2]:
- Error in stdin, at line 1:
- attempt to index field `?` (a null value)
- > a..[1]..[2]:
- null
- The new function `drem` evaluates the remainder of an integer division x/y, but contrary to `irem`, rounds the internal quotient x/y to the nearest integer instead of towards zero.
- The new function `skycrane.todate` returns the current date and time as a formatted string.
- The new function `io.truncate` truncates a file at the current file position.
- The new function `io.move` changes the file position a given number of characters to the left or right.
- The new function `io.filesize` returns the size of a file.
- `readlib` now accepts strings as its arguments, only. Numbers are not allowed any longer.
- If the last argument to `with` is the Boolean `false`, then the function does not write assigned short names to the console (stdout).
- `strings.fields` now also accepts a sequence of index numbers. It does not, however, accept the index `0` any longer.
- The Raspberry Pi Wheezy Debian installer now includes the `gdi` graphics package.
- The `change.log` file is now correctly displayed in Windows.

### New in version 2.0.0 RC3 (November 19th, 2013)

- The new loop variants `for/as` and `for/until` check a condition at the end of the current iteration and either commence the next iteration or leave the loop. This works with both for/to, as well as for/in loops.

### New in version 2.0.0 RC2 (November 16th, 2013)

- The new loop variants `for/as` and `for/until` check a condition at the end of the current iteration and and either commence the next iteration or leave a loop. This works with both for/to, as well as for/in loops.

### New in version 2.0.0 RC1 (November 15th, 2013)

- The new `import` statement allows to import one or more libraries without putting their names into quotes, e.g. "import calc, stats" is equivalent to "readlib('calc', 'stats')".
- The `alias` option to the `import` statement assigns one or more short names to the library functions initialised, e.g. "import calc alias xpdiff" is equivalent to "with('calc', 'xpdiff')", and "import calc alias" is equivalent to "with('calc')".
- The new `..` operator allows to index tables even if its left-hand side operand evaluates to `null`. In this case, `null` is returned and no `attempt to index field ... (a null value)` error is issued. It is similar to the `getentry` function but is three times faster.