/****** localisation.library/OpenCountryTable ****************************

    NAME
	OpenTerritory -- open a territory table

    SYNOPSIS
	territory = OpenTerritory(name)
	D0                        A0

    FUNCTION
	This function returns a pointer to a territory table that was
	previously loaded in memory. If the territory table is not already
	there it will be loaded in from disk. First the directory from
	which the process was launched is searched, then the locale:
	directory.

    INPUTS
	name		a pointer to a null terminated string

    RESULTS
	territory	a territory table pointer

    SEE ALSO
	CloseTerritory, locale/locale.h


/*************************************************************************

    NAME
	OpenLanguage -- open a language table

    SYSNOPSIS
        langauge = OpenLanguage(name)
        D0                      A0

    FUNCTION
	This function returns a pointer to a language table, if that table
	has already been loaded in memory. If not, the directory from
	which the calling process was launched is searched, then the
	locale: directory.

    INPUT
	name		a pointer to a null terminated string

    RESULTS
	language	a language table pointer

    SEE ALSO
	CloseLanguage, locale/locale.h


/*************************************************************************

    NAME
	CloseTerritory -- close a territory table

    SYNOPSIS
	CloseTerritory(territory)
	               A0
	void CloseTerritory(struct territory *)

    FUNCTION
	This function informs the system that access to the given territory
	table has concluded. If the open count of the territory table
	reaches zero, it is removed from memory unless its PERMANENT flag
	is set.

    INPUTS
	territory		a territory table pointer

    SEE ALSO
	OpenTerritory, locale/locale.h


/*************************************************************************

    NAME
	CloseLanguage -- close a language table

    SYNOPSIS
	CloseLanguage(language)
	               A0
	void CloseLanguage(struct language *)

    FUNCTION
	This function informs the system that access to the given language
	table has concluded. If the open count of the language table
	reaches zero, it is removed from memory unless its PERMANENT flag
	is set.

    INPUTS
	language	a language table pointer

    SEE ALSO
	OpenLanguage, locale/locale.h

/*************************************************************************

    NAME
	DefaultTerritory -- return the default territory for system func.

    SYNOPSIS
	territory = DefaultTerritory()

	struct Territory DefaultTerritory(void)

    FUNCTION
	Returns the default territory used in DOS functions such as
	DateToStr() and StrToDate(). The name of the territory file can
	be determined from the territory->Node.ln_Name field.

    RESULTS
	territory	a territory table pointer

    SEE ALSO
	locale/locale.h


/*************************************************************************

    NAME
	DefaultLanguage -- return the default territory for system functions

    SYNOPSIS
	language = DefaultLanguage()

	struct Language DefaultLanguage(void)

    FUNCTION
	Returns the default language used in DOS functions such as
	DateToStr() and StrToDate(). The name of the language directory,
	and thus the langauge itself, can be determined from the
	language->Node.ln_Name field.

    RESULTS
	language	a language table pointer

    SEE ALSO
	locale/locale.h


/*************************************************************************

    NAME
	CatOpen -- open a message catalogue

    SYNOPSIS
	catalogue = CatOpen(name)
	D0                  A0

    FUNCTION
	This function returns a pointer to the named catalogue. If it is
        not already in memory it will first search the directory from
	which the translation was loaded, and finally the locale:
	directory.

	If the name string contains a ":" character, the locale directory
	is not searched anymore.

    INPUTS
	name		a pointer to a null terminated string specifying a
			catalogue.

    RESULTS
	catalogue	a pointer to a message catalogue

    SEE ALSO
	CatClose(), CatGets(), locale/locale.h


/*************************************************************************

    NAME
	CatGets -- get a message from a message catalogue

    SYNOPSIS
	message = CatGets(catalogue,set,msgNum,defaultString)
	D0                A0    D0  D1     A1
	char *TranslateMsg(struct Catalogue *,int,int,char *);

    FUNCTION
	This function returns a pointer to the message corresponding to the
	given table and message number. Should the table be a NULL, this
	function will return the default string given.

    INPUTS
	table		a translation table
        set		a set number, not implmented. Use 1 as set number.
	msgNum		a message number

    RESULTS
	message		a pointer to a null terminated string

    SEE ALSO
	CatOpen(), CatClose(), locale/locale.h

/*************************************************************************

    NAME
	CatClose -- close a message catalogue

    SYNOPSIS
	CatClose(catalogue)
	         A0
	void CatClose(struct Translation *);

    FUNCTION
	This function informs the localisation library that access to the
	given catalogue has been concluded. If the open count of the
	catalogue reaches zero, it is removed from memory, unless it's
	PERMANENT flag is set.

    INPUTS
	catalogue	a pointer to a translation table

    SEE ALSO
	CatOpen(), CatGets(), locale/locale.h

/*************************************************************************

    NAME
	StrColl -- compare two strings according to collation information

    SYNOPSIS
	result = StrCmp(string1,string2,language)
        D0              A0      A1      A2
	int StrCmp(char *, char *, struct Language *)

    FUNCTION
	Compares string1 to string2 according to the collation information
	provided in the language table and returns an integer greater than,
	equal to, or less than zero, accordingly as the string pointed to
	by string1 is greater than, equal to, or less than the string
	pointed to by string2.

    INPUTS
	string1		a pointer to a null terminated string
	string2		a pointer to a null terminated string
	language	a pointer to a language table

    RESULTS
	result		relationship between string1 and string2

    SEE ALSO
	locale/locale.h

/*************************************************************************

    NAME
	StrXFrm -- transform string according to collation information

    SYNOPSIS
	length = StrXFrm(string1,string2,size,language)
	D0               A0      A1      D0   A2

    FUNCTION
	This function transforms the string pointed to by string2 and
	places the resulting string into the array pointed to by string1.
	The transformation is such that if the strcmp function is applied
	to two transformed strings, it returns a value corresponding to
	the result returned by the StrColl() function applied to the two
	original strings. No more than 'size' characters are placed into
	the array pointed to by string1, including the terminating NULL
	character. If 'size' is zero, string1 is permitted to be a NULL
	pointer.

    INPUTS
	string1		a pointer to a null terminated string
	string2		a pointer to a null terminated string
	size		maximum numer of characters to be put in string1
	language	a pointer to a language table

    RESULTS
	length		length of the transformed string. If 'length' is
			greater than 'size', then string1[] is undetermined.

    SEE ALSO
	StrColl(), locale/locale.h

/*************************************************************************

   NAME
	RawDoFmt -- format data into a character stream.

   SYNOPSIS
	RawDoFmt(FormatString, DataStream, PutChProc, PutChData);
                 a0            a1          a2         a3

	void RawDoFmt(STRPTR,APTR,void (*)(),APTR);

   FUNCTION
	perform "C"-language-like formatting of a data stream, outputting
	the result a character at a time.  Where % formatting commands are
	found in the FormatString, they will be replaced with the
	corresponding element in the DataStream.  %% must be used in the
	string if a % is desired in the output.

	Under V36, RawDoFmt() returns a pointer to the end of the DataStream
	(The next argument that would have been processed).  This allows
	multiple formatting passes to be made using the same data.

   INPUTS
	FormatString - a "C"-language-like NULL terminated format string,
	with the following supported % options:

	 %[order$][flags][width.limit][length]type

	order  - argument number to use for this entry, followed by a "$".
	flags  - only one allowed. '-' specifies left justification.
	width  - field width.  If the first character is a '0', the
		 field will be padded with leading 0's.
	  .    - must follow the field width, if specified
	limit  - maximum number of characters to output from a string.
		 (only valid for %s).
	length - size of input data defaults to WORD for types d, x,
		 and c, 'l' changes this to long (32-bit).
	type   - supported types are:
			b - BSTR, data is 32-bit BPTR to byte count followed
			    by a byte string, or NULL terminated byte string.
			    A NULL BPTR is treated as an empty string.
			    (Added in V36 exec)
			d - decimal
			x - hexadecimal
			s - string, a 32-bit pointer to a NULL terminated
			    byte string.  In V36, a NULL pointer is treated
			    as an empty string
			c - character

	DataStream - a stream of data that is interpreted according to
		 the format string.  Often this is a pointer into
		 the task's stack.
	PutChProc  - the procedure to call with each character to be
		 output, called as:

	PutChProc(Char,  PutChData);
		  D0-0:8 A3

		the procedure is called with a NULL Char at the end of
		the format string.

	PutChData - a value that is passed through to the PutChProc
		procedure.  This is untouched by RawDoFmt, and may be
		modified by the PutChProc.

   EXAMPLE
	;
	; Simple version of the C "sprintf" function.  Assumes C-style
	; stack-based function conventions.
	;
	;   long eyecount;
	;   eyecount=2;
	;   sprintf(string,"%s have %ld eyes.","Fish",eyecount);
	;
	; would produce "Fish have 2 eyes." in the string buffer.
	;
		XDEF _sprintf
		XREF _AbsExecBase
		XREF _LVORawDoFmt
	_sprintf:	; ( ostring, format, {values} )
		movem.l a2/a3/a6,-(sp)

		move.l	4*4(sp),a3       ;Get the output string pointer
		move.l	5*4(sp),a0       ;Get the FormatString pointer
		lea.l	6*4(sp),a1       ;Get the pointer to the DataStream
		lea.l	stuffChar(pc),a2
		move.l	_AbsExecBase,a6
		jsr	_LVORawDoFmt(a6)

		movem.l (sp)+,a2/a3/a6
		rts

	;------ PutChProc function used by RawDoFmt -----------
	stuffChar:
		move.b	d0,(a3)+        ;Put data to output string
		rts

   WARNING
	This Amiga ROM function formats word values in the data stream.  If
	your compiler defaults to longs, you must add an "l" to your
	% specifications.  This can get strange for characters, which might
	look like "%lc".

   SEE ALSO
	Documentation on the C language "printf" call in any C language
	reference book.


******* dos.library/DateToStr ************
*
*   NAME
*	DateToStr -- Converts a DateStamp to a string
*
*   SYNOPSIS
*	error = DateToStr(country,datetime)
*	D0                A0      D1
*	BOOL DateToStr(struct DateTime *)
*
*   FUNCTION
*	StamptoStr converts an AmigaDOS DateStamp to a human
*	readable ASCII string as requested by your settings in the
*	DateTime structure.
*
*   INPUTS
*	country - a pointer to a country table; used only with FORMAT_LOC.
*
*	DateTime - a pointer to an initialized DateTime structure.
*
*	The DateTime structure should be initialized as follows:
*
*	dat_Stamp - a copy of the datestamp you wish to convert to
*		  ascii.
*
*	dat_Format - a format	byte which specifies the format	of the
*		  dat_StrDate.	This can be any	of the following
*		  (note: If value used is something other than those
*		  below, the default of	FORMAT_DOS is used):
*
*		  FORMAT_DOS:	  AmigaDOS format (dd-mmm-yy).
*
*		  FORMAT_INT:	  International	format (yy-mmm-dd).
*
*		  FORMAT_USA:	  American format (mm-dd-yy).
*
*		  FORMAT_CDN:	  Canadian format (dd-mm-yy).
*
*		  FORMAT_DEF:	  The default format is used. If the localisation
*				  library has not been opened yet FORMAT_DOS is
*				  is used. Otherwise the default country table is
*				  used.
*
*		  FORMAT_LOC:	  The country table specified is used for determining
*				  the format, otherwise the country input is ignored.
*
*	dat_Flags - a	flags byte.  The only flag which affects this
*		  function is:
*
*		  DTB_SUBST:	  If set, a string such	as Today,
*				  Monday, etc.,	will be	used instead
*				  of the dat_Format specification if
*				  possible.
*		  DTB_FUTURE:	  Ignored by this function.
*
*	dat_StrDay - pointer to a buffer to receive the day of the
*		  week string.	(Monday, Tuesday, etc.). If null, this
*		  string will not be generated.
*
*	dat_StrDate -	pointer	to a buffer to receive the date
*		  string, in the format	requested by dat_Format,
*		  subject to possible modifications by DTB_SUBST.  If
*		  null,	this string will not be	generated.
*
*	dat_StrTime -	pointer	to a buffer to receive the time	of day
*		  string. If NULL, this	will not be generated.
*
*   RESULT
*	error	- a non-zero return indicates that the DateStamp was
*		  invalid, and could not be converted.	Zero indicates
*		  that everything went according to plan.
*
*   SEE ALSO
*	StrtoDate(), libraries/datetime.h
*


******* dos.library/StrToDate ************
*
*   NAME
*	StrToDate -- Converts a string to a DateStamp
*
*   SYNOPSIS
*	error = StrToDate(country,datetime)
*	D0                A0      D1
*
*	BOOL StrToDate( struct DateTime * )
*
*   FUNCTION
*	Converts a human readable ASCII string into an AmigaDOS
*	DateStamp.
*
*   INPUTS
*	DateTime - a pointer to an initialized DateTime structure.
*
*	The DateTime structure should	be initialized as follows:
*
*	dat_Stamp  - ignored on input.
*
*	dat_Format - a format	byte which specifies the format	of the
*		dat_StrDat.  This can	be any of the following	(note:
*		If value used	is something other than	those below,
*		the default of FORMAT_DOS is used):
*
*		FORMAT_DOS:	  AmigaDOS format (dd-mmm-yy).
*
*		FORMAT_INT:	  International	format (yy-mmm-dd).
*
*		FORMAT_USA:	  American format (mm-dd-yy).
*
*		FORMAT_CDN:	  Canadian format (dd-mm-yy).
*
*		FORMAT_DEF:	  The default format is used. If the localisation
*				  library has not been opened yet FORMAT_DOS is
*				  is used. Otherwise the default country table is
*				  used.
*
*		FORMAT_LOC:	  The country table specified is used for determining
*				  the format, otherwise the country input is ignored.
*
*	dat_Flags - a flags byte.  The only flag which affects this
*		function is:
*
*		DTB_SUBST:	  ignored by this function
*
*		DTB_FUTURE:	  If set, indicates that strings such
*				  as (stored in	dat_StrDate) "Monday"
*				  refer	to "next" monday. Otherwise,
*				  if clear, strings like "Monday"
*				  refer	to "last" monday.
*
*	dat_StrDay - ignored bythis function.
*
*	dat_StrDate -	pointer	to valid string	representing the date.
*		  This can be a	"DTB_SUBST" style string such as
*		  "Today" "Tomorrow" "Monday", or it may be a string
*		  as specified by the dat_Format byte.	This will be
*		  converted to the ds_Days portion of the DateStamp.
*		  If this pointer is NULL, DateStamp->ds_Days will not
*		  be affected.
*
*	dat_StrTime -	Pointer	to a buffer which contains the time in
*		  the ASCII format hh:mm:ss.  This will	be converted
*		  to the ds_Minutes and	ds_Ticks portions of the
*		  DateStamp.  If this pointer is NULL, ds_Minutes and
*		  ds_Ticks will	be unchanged.
*
*   RESULT
*	error	- a non-zero return indicates that a conversion	could
*		not be performed. A Zero return indicates that the
*		DateTime.dat_Stamp variable contains the converted
*		values.
*
*   SEE ALSO
*	DateToStr(), libraries/datetime.h
*