******************************************************************************
*
* CHANGES.TXT - Changes in TLX from 4.2 to 5.0 to 5.01
*
* Last updated: 07-Mar-1995
*
* Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
*
******************************************************************************


Directory structure
-------------------

	The directory structure has been changed slightly since version 4.2,
	which itself marked a departure from the previous organization. The
	directories that make up TLX 5.0 are organized as follows:

		TLX50			- base, contains info
		TLX50\TLX		- base, contains .h files
		TLX50\TLX\SOLVE 	- .h files for searching & CSP
		TLX50\TLX\TEMPLATE	- template source files
		TLX50\SRC		- source files
		TLX50\LIB		- compiled library files
		TLX50\LIB\BC		- Borland libraries
		TLX50\LIB\IBM		- IBM libraries
		TLX50\LIB\SC		- Symantec libraries
		TLX50\LIB\WC		- Watcom libraries
		TLX50\DOC		- contains documentation files
		TLX50\SAMPLES		- sample programs
		TLX50\SAMPLES\AC3	- sample AC-3 CSP program
		TLX50\SAMPLES\AC6	- sample AC-6 CSP program
		TLX50\SAMPLES\BB	- sample branch & bound program
		TLX50\TOOLS		- various tools to support TLX
		TLX50\TOOLS\OS2 	- ditto, OS/2 versions
		TLX50\TOOLS\NT	 	- ditto, Windows NT versions

	Not all compiler-specific directories may appear in your distribution.

	As before, these changes are primarily intended to avoid name clashes
	with similar files from other providers. To use this new directory
	structure, set up your compiler's INCLUDE path to contain the
	TLX50 base directory (including drive letter, if appropriate).
	For example:

		SET INCLUDE=C:\TLX50;C:\WATCOMC\INCLUDE

	Alternatively, you may use the corresponding setting from within the
	compiler's IDE, or give it as a parameter on the command line:

		BCC /IC:\TLX50;C:\BC4\INCLUDE myfile.cpp

	The changes in the directory structure influence the way you should
	refer to TLX header and template source files. Write #include
	directives that refer to TLX header files in your own source code
	as follows:

		#include <tlx\arrays.h> 		(header file)
		#include <tlx\template\array.cpp>	(template source file)

	In combination with the earlier guidelines about your compiler's
	INCLUDE setting, this should produce the desired effect.

	NOTE:	the above conventions differ slightly on UNIX platforms
		(where a forward slash '/' is used to separate path
		components), and on Macintosh platforms, where there is
		no direct support for subdirectory specifications. For
		these platforms, conversion tools will be provided
		that adapt the #include directives to the respective
		platform conventions.


Naming changes from 4.x to 5.0
------------------------------

	All member function names have been changed, mostly to have them
	start with a capital letter. Some others have been changed for
	consistency among classes, and/or for more clarity as to the
	operation they perform.

	To automatically change TLX 4.2 names to their 5.0 counterparts,
	we have provided a tool called TLX5UP. This tool is located in
	TLX50/TOOLS (sorry - only an MS-DOS version currently). Use it
	as follows:

		TLX5UP filename(s)...

	For filename(s)..., enter the names of one or more of your .h or
	.cpp files that you wish to convert. Wildcards are allowed, so
	the following is an easy way to convert all your 4.2 files to
	5.0 conventions:

		TLX5UP *.H *.CPP

	To see a list of all changes, type TLX5UP without arguments. You
	may need to pipe its output through MORE or a similar utility, or
	redirect it to another file, because of the length of the list.
	Excerpts of TLX5UP output without arguments:

(1)	    ASSERT		      -> TLX_ASSERT
	    ASSERT_NULL 	      -> TLX_ASSERT_NULL
	    ASSERT_PTR		      -> TLX_ASSERT_PTR
	    BENDIAN		      -> _BENDIAN
	    BREAKPOINT		      -> TLX_DEBUGBREAK
	    ...
(2)	    TLHandle		      -> Obsolete_TLHandle
	    ...
	    ulong		      -> tULong
	    ushort		      -> tUShort
(3)	    ASSERT(		      -> TLX_ASSERT(
	    ASSERT_NULL(	      -> TLX_ASSERT_NULL(
	    ...
	    vector(		      -> StorageVector(
	    version(		      -> Version(
	    watch(		      -> WatchVars(

	Notes:

	(1) On each line, the left column indicates the old 4.2 name, while
	    on the right the new 5.0 name is shown.

	(2) If names have been dropped altogether, they will be replaced by
	    their original name with an 'Obsolete_' prefix. If you try to
	    compile this name, you will get a compilation error and should
	    consult the TLX 5.0 documentation to see by which new facility
	    the old one has been replaced.

	(3) Partly through the list, a new sublist is started. Names in this
	    sublist end in '('; this is a parsing convenience to distinguish
	    function names from others.


Naming changes from 5.0 to 5.01
-------------------------------

	Minor changes with respect to names of simple types (tInt32 etc.)
	As with the 4.x -> 5.0 naming changes, an update tool is provided,
	called TLX501UP. It will perform updates from 5.00 to 5.01 *only*,
	so you'll need to use TLX5UP first if you're coming from TLX 4.x.

	Use of the tool is identical to TLX5UP. In particular, a complete 
	list of changes may be obtained by running TLX501UP without arguments.


Use of exceptions and runtime type information
----------------------------------------------

	Starting with this version of TLX, the library source code uses C++
	exceptions to report problems. All error return values from functions
	have been removed; if a function returns, it can be assumed to be
	successful (or at least, it operated without error).

	Because not all C++ compilers currently support exceptions, we have
	introduced a migration path. This is actually very simple, because TLX
	will only throw exceptions; it will never catch them. Thus, the only
	exception construct that needs to be emulated for backward
	compatibility is the 'throw' expression. This is accomplished by means
	of a new THROW macro. If the C++ compiler supports exceptions, this
	macro reverts to an ordinary 'throw'; if not, a special function
	'_TlxThrow()' is called to notify the user and perhaps terminate the
	program.

	In addition, an exception hierarchy is introduced that starts with the
	base class TLException. All exceptions thrown in TLX code, with the
	exception (no pun intended) of the ANSI/ISO C++ standard exceptions
	xmsg, xalloc, etc. are derived from TLException. (In fact, the
	_TlxThrow() emulation function only accepts TLException-derived
	classes.)

	Refer to the header file EXCEPT.H for more information regarding
	exceptions.

	A similar story holds for runtime type information (RTTI). The file
	RTTI.H contains a few macros that expand to the new-style typecasts
	(including dynamic_cast<>) on C++ compilers that support them, or use
	old-style casts on compilers that do not. You should be aware,
	however, that the semantics of an old-style typecast are different
	from the new-style ones (in particular in the case of dynamic_cast<>,
	which performs both runtime type checking and allows casts from
	virtual bases to derived classes), and that therefore programs may
	behave differently. You are advised to switch to an RTTI-supporting
	C++ compiler as soon as possible.

	There is also marginal emulation support for the new typeid()
	operator.

	Refer to the header file RTTI.H for more information regarding
	these items.


Constraint satisfaction and backtrack search
--------------------------------------------

	This area has been largely redesigned. While it implements the same
	algorithms as before, the details are quite different. Consult Tarma
	Software Research if you need help with these changes and/or a white
	paper describing the new implementation.


Link version checks
-------------------

	In order to reduce the chance that you compile your source code
	against one version of the TLX header files (say, debug) while
	linking to another (retail), we have introduced link-time checks
	in the library. Refer to COMPILE.TXT for more information concerning
	these checks.


Other changes
-------------

	The other changes include numerous smaller modifications and/or
	corrections to existing classes, a new (and hopefully improved)
	formatting style for both source code and comments, and the
	introduction of several new classes. However, this process is not
	finished as of this release, so expect more changes (which will
	generally be downward compatible).
