CloseCatalog
SYNOPSIS
CloseCatalog(catalog)
void CloseCatalog(struct Catalog *);
DESCRIPTION
Conclude access to a message catalog, and decrement the use count.
If this use count is 0, the catalog can be expunged when the
system memory is running low
INPUTS
catalog - the message catalog to close, note that NULL is
a valid catalog
RESULT
The catalog is closed, and should no longer be used by the
application
SEE ALSO
CloseLocale
SYNOPSIS
CloseLocale(locale)
void CloseLocale(struct Locale *);
DESCRIPTION
Finish accessing a Locale
INPUTS
locale - An opened locale. Note that NULL is a valid
parameter here, and will simply be ignored
RESULT
The locale is released back to the system
SEE ALSO
ConvToLower
SYNOPSIS
ConvToLower(locale, character)
ULONG ConvToLower(struct Locale *, ULONG);
DESCRIPTION
This function determine if the character supplied is upper case,
and if it is, the character will be converted to lower case.
Otherwise, the original character will be returned
INPUTS
locale - The Locale to use for this conversion.
character - The character to convert to lower case
RESULT
The possibly converted character
NOTES
This function requires a full 32-bit character in order to
support future multi-byte character sets.
ConvToUpper
SYNOPSIS
ConvToUpper(locale, character)
ULONG ConvToUpper(struct Locale *, ULONG);
DESCRIPTION
ConvToUpper() will determine if a character is a lower case
character and if so convert it to the upper case equivalent.
Otherwise it will return the original character
INPUTS
locale - The Locale to use for this conversion.
character - The character to convert
RESULT
The possibly converted character
NOTES
This function requires a full 32-bit character in order to support
future multi-byte character sets.
SEE ALSO
ConvertUCS4ToUTF8
DESCRIPTION
Convert UCS-4 string to UTF-8 string. The length parameter specifies
how many code points should be converted. If specified as -1 then
entire string is converted. Native byte order is assumed.
Conversion always stops on a NULL character which is also converted.
The destination string is guaranteed to be NULL terminated
INPUTS
widestring - UCS-4 string to be converted
string - the destination for UTF-8 string, or NULL to measure
buffer space
length - number of code points to convert
RESULT
Number of UTF-8 octets without terminating NULL
NOTE
Illegal code points are converted to question marks.
SEE ALSO
ConvertUTF8ToUCS4
DESCRIPTION
Convert UTF-8 string to UCS-4 string using native byte order.
The length parameter specifies how many code points should be
converted. If specified as -1 then entire string is converted.
Conversion always stops on a NULL character which is also converted.
The destination string is guaranteed to be NULL terminated
INPUTS
string - UTF-8 string to be converted
widestring - the destination for UCS-4 string, or NULL to measure
buffer space
length - number of code points to convert
RESULT
Number of UCS-4 code points without terminating NULL
NOTE
Illegal UTF-8 sequences are converted to question marks.
SEE ALSO
FormatDate
SYNOPSIS
FormatDate(locale, formatString, date, hook)
VOID FormatDate(struct Locale*, STRPTR, struct DateStamp *, struct Hook*);
DESCRIPTION
Generate a date string based on a template. The bytes generated are sent
to a user specified callback function
INPUTS
locale -- the locale to use when formatting the string
formatString -- the formatting template string; this is much like the
printf() formatting style, i.e. a % followed by a
formatting command. The following commands exist:
%a -- abbreviated weekday name
%A -- weekday name
%b -- abbreviated month name
%B -- month name
%c -- the same as "%a %b %d %H:%M:%S %Y"
%C -- the same as "%a %b %e %T %Y"
%d -- day number with leading zeros
%D -- the same as "%m/%d/%y"
%e -- day number with leading spaces
%F -- the same as "%Y-%m-%d"
%h -- abbreviated month name
%H -- hour using 24 hour style with leading zeros
%I -- hour using 12 hour style with leading zeros
%j -- julian date
%m -- month number with leading zeros
%M -- the number of minutes with leading zeros
%n -- linefeed
%p -- AM or PM string
%P -- am or pm string
%q -- hour using 24 hour style
%Q -- hour using 12 hour style
%r -- the same as "%I:%M:%S %p"
%R -- the same as "%H:%M"
%S -- the number of seconds with leading zeros
%t -- tab
%T -- the same as "%H:%M:%S"
%U -- the week number, taking Sunday as the first day
of the week
%w -- the weekday number
%W -- the week number, taking Monday as the first day
of the week
%x -- the same as "%m/%d/%y"
%X -- the same as "%H:%M:%S"
%y -- the year using two digits with leading zeros
%Y -- the year using four digits with leading zeros
If the template parameter is NULL, a single null byte
is sent to the callback function.
date -- the current date
hook -- callback function; this is called for every character
generated with the following arguments:
* pointer to hook structure
* character
* pointer to locale
SEE ALSO
FormatString
SYNOPSIS
FormatString(locale, fmtTemplate, dataStream, putCharFunc)
APTR FormatString(struct Locale *, STRPTR, APTR, struct Hook *);
GetCatalogStr
SYNOPSIS
GetCatalogStr(catalog, stringNum, )
STRPTR GetCatalogStr(struct Catalog *, ULONG, CONST);
DESCRIPTION
This function will return the string specified by the
stringNum from the given message catalog, or the defaultString
if the string could not be found.
If the catalog == NULL, then the defaultString will also be
returned
INPUTS
catalog - Message catalog to search. May be NULL.
stringNum - ID of the string to find.
defaultString - String to return in case catalog is NULL or
string could not be found
RESULT
A pointer to a READ ONLY NULL terminated string. This string
pointer is valid as long as the catalog remains open
SEE ALSO
GetLocaleStr
SYNOPSIS
GetLocaleStr(locale, stringNum)
STRPTR GetLocaleStr(struct Locale *, ULONG);
DESCRIPTION
This function will return a system standard string from
the current Locale
INPUTS
locale - The current locale.
stringNum - The number of the string to get a pointer to.
See the include file <libraries/locale.h>
for a list of possible values
RESULT
A pointer to a NULL-terminated string, or NULL if the string
requested was unknown. The returned string is READ-ONLY and
is valid only as long as the Locale remains open
IsUnicode
DESCRIPTION
Check if buffer contains Unicode
INPUTS
buffer - buffer to examine
length - size of buffer in bytes
RESULT
result - does buffer contain Unicode or not, possible return values are
UNICODE_INVALID - the buffer does not contain Unicode
UNICODE_UTF8 - the buffer is UTF-8 string
UNICODE_16_BE - the buffer is UCS-2/UTF-16 string in
big endian byte order
UNICODE_16_LE - the buffer is UCS-2/UTF-16 string in
little endian byte order
UNICODE_32_BE - the buffer is UCS-4/UTF-32 string in
big endian byte order
UNICODE_32_LE - the buffer is UCS-4/UTF-32 string in
little endian byte order
NOTES
While UCS-2 encoding is similar to UTF-16 they are not the same.
UCS-2 is a fixed length encoding with 65536 possible code points
which is not enough to support all Unicode characters. UTF-16 is
fully compatible to UCS-2 but permits full Unicode repertoide by
implementing so called surrogate pairs where two 16-bit words are
used to encode missing code points.
Applications which implement 16-bit Unicode should always support
UTF-16. UCS-4 and UTF-32, however, are nearly identical.
OpenCatalogA
SYNOPSIS
OpenCatalogA(locale, name, tags)
struct Catalog * OpenCatalogA(struct Locale*, STRPTR, struct TagItem *);
DESCRIPTION
Open a catalog for translated strings
INPUTS
locale - desired language for the catalog or NULL to use
user defined default.
name - catalog name to open
tags - optional taglist
OC_BuiltInStrings (V52.4 / MorphOS 3.10)
Pointer to built-in strings. When translation is not available
built-in string is used. This allows using NULL string argument
with GetCatalogStr
OpenLocale
SYNOPSIS
OpenLocale(name)
struct Locale * OpenLocale(STRPTR);
DESCRIPTION
This function will open for use a named locale. A locale is a
data structure that contains many different parameters that
an application needs in order to localise itself. Using this
information an application can dynamically adapt to the user's
environment.
Locales are created using the Locale Preferences Editor. If
you pass a NULL instead of a name, then you will receive the
current default Locale. This is the normal procedure
INPUTS
name - The name of the locale you wish opened, or NULL
to open the current default locale. This will
be an IFF PREF file which contains both LCLE
and CTRY chunks
RESULT
A pointer to an initialised Locale structure, or NULL if none
could be opened. If NULL is returned you can use IoErr()
to find out what caused this error.
If you pass NULL, you will always succeed
SEE ALSO
ParseDate
DESCRIPTION
This function will convert a stream of characters into an AmigaDOS
DateStamp structure. It will obtain its characters from the
getCharFunc callback hook, and the given formatting template will
be used to direct the parse
INPUTS
locale - the locale to use for the formatting
date - where to put the converted date. If this is NULL,
then this function can be used to verify a date
string.
fmtTemplate - the date template used to direct the parse of the
data. The following FormatDate() formatting
controls can be used:
%a %A %b %B %d %e %h %H %I %m %M %p %S %y %Y
See FormatDate() autodoc for more information.
getCharFunc - A callback Hook which is used to read the data
from a stream. The hook is called with:
A0 - address of the Hook structure
A2 - locale pointer
A1 - NULL
BTW: The AmigaOS autodocs which state that A1
gets locale pointer and A2 NULL are wrong!!
The read character should be returned in D0. Note
that this is a 32 bit character not an 8 bit
character. Return a NULL character if you reach the
end of the stream
RESULT
TRUE - If the parse could be performed.
FALSE - If the format of the data did not match the formatting
string
NOTES
This has a few differences from the implementation in locale.library
v38. In particular:
- %p does not have to be at the end of the line.
- %d and %e are not effectively the same, ie %d requires a leading
zero, but %e can not handle leading 0's.
BUGS
%d, %e probably needs some work.
SEE ALSO
RexxHost
SYNOPSIS
RexxHost(rxmsg)
ULONG RexxHost(struct RexxMsg *);
DESCRIPTION
locale.library rexxhost interface (located at offset -30), provides the
following Locale functions to ARexx scripts:
OpenCatalog(CATALOGNAME/A,BUILTINLANGUAGE/A,VERSION/N/A)
CloseCatalog(CATALOG/N/A)
GetCatalogStr(CATALOG/N/A,STRINGNUM/N/A,DEFAULTSTR/A)
GetLocaleStr(STRINGNUM/N/A) (V50)
ConvToLower(CHARACTER/A)
ConvToUpper(CHARACTER/A)
StrnCmp(STRING1/A,STRING2/A,TYPE/N/A)
IsXXXX(CHARACTER/A
EXAMPLE
if ~show('L', 'locale.library') then
do
call addlib('locale.library', 0, -30, 50)
end
catalog = OpenCatalog('myapp.catalog', 'english', 0)
say GetCatalogStr(catalog, 1, 'default')
call CloseCatalog(catalog)
say GetLocaleStr(50
StrConvert
SYNOPSIS
StrConvert(locale, string, buffer, bufferSize, type)
ULONG StrConvert(struct Locale *, STRPTR, APTR, ULONG, ULONG);
DESCRIPTION
This function will transform the string given and place the
result in the supplied buffers, copying at most bufferSize
bytes.
The transformation is such that if the C strcmp() function
was called on two strings transformed by this function then
the result will be the same as calling the Locale StrnCmp()
function on the two strings
INPUTS
locale - the Locale to use for the transformation.
string - the string to be transformed
buffer - the destination for the transformed string.
This buffer may need to be larger than the
untransformed string.
bufferSize - the maximum number of bytes to place in
buffer.
type - how to transform the string. See the
StrnCmp() function for possible values
RESULT
Length of the number of BYTES placed in the buffer by
the transformation process minus 1 (for NULL termination
SEE ALSO
StrnCmp
SYNOPSIS
StrnCmp(locale, string, string, length, type)
LONG StrnCmp(struct Locale *, STRPTR, STRPTR, LONG, ULONG);
DESCRIPTION
StrnCmp() will compare two strings, up to a maximum length
of length using a specific kind of collation information
according to the locale.
The result will be less than zero, zero, or greater than zero
depending upon whether the string string1 is less than, equal
to, or greater than the string pointed to string2
INPUTS
locale - Which locale to use for this comparison.
string1 - NULL terminated string.
string2 - NULL terminated string.
length - Maximum length of string to compare.
type - How to compare the strings, values are:
SC_ASCII
Perform a simple ASCII case-insensitive comparison.
This is the fastest comparison, but considers that
accented characters are different to non-accented
characters.
SC_COLLATE1
This sorts using the "primary sorting order". This
means that characters such as 'e' and 'é' will be
considered the same. This method also ignores
case.
SC_COLLATE2
This will sort using both the primary and secondary
sorting order. This is the slowest sorting method
and should be used when presenting data to a user.
The first pass is the same as SC_COLLATE1, meaning
that two strings such as "role" and "rôle" would
be sorted identically. The second pass will
compare the diacritical marks
RESULT
The relationship between the two strings.
< 0 means string1 < string2
= 0 means string1 == string2
> 0 means string1 > string2
SEE ALSO
UCS4_ConvToLower
DESCRIPTION
This function determine if the character supplied is upper case,
and if it is, the character will be converted to lower case.
Otherwise, the original character will be returned
INPUTS
ucharacter - the character to convert to lower case in the native
byter order
RESULT
result - the possibly converted character
SEE ALSO
UCS4_ConvToUpper
DESCRIPTION
This function determine if the character supplied is lower case,
and if it is, the character will be converted to upper case.
Otherwise, the original character will be returned
INPUTS
ucharacter - the character to convert to upper case in the native
byter order
RESULT
result - the possibly converted character
SEE ALSO
UCS4_FormatString
DESCRIPTION
Generate a date string based on a template. The bytes generated are sent
to a user specified callback function
INPUTS
locale -- the locale to use when formatting the string
formatString -- the formatting template string; this is much like the
printf() formatting style, i.e. a % followed by a
formatting command
NOTES
This functions supports big and little endian strings with byte
order mark. When there is no byte order mark the native byte order
is assumed. Output is always in the native byte order.
SEE ALSO
UCS4_GetCatalogStr
DESCRIPTION
This function will return the string specified by the
stringNum from the given message catalog, or the defaultString
if the string could not be found.
If the catalog == NULL, then the defaultString will also be returned
INPUTS
catalog - Message catalog to search. May be NULL.
stringNum - ID of the string to find.
defaultString - String to return in case catalog is NULL or string
could not be found
RESULT
A pointer to a READ ONLY NULL terminated wide string. This string
pointer is valid as long as the catalog remains open
NOTES
In the catalogs strings are always in the native byte order but
implementation does not pay attention to the default strings.
SEE ALSO
UCS4_GetLocaleStr
DESCRIPTION
This function will return a system standard unicode string from
the current Locale
INPUTS
locale - The current locale.
stringNum - The number of the string to get a pointer to.
See the include file <libraries/locale.h>
for a list of possible values
RESULT
A pointer to a NULL-terminated wide string, or NULL if the string
requested was unknown. The returned string is READ-ONLY and
is valid only as long as the Locale remains open.
Unicode characters in the returned strings are always in the native
byte order
NOTES
If the current locale does not support unicode this function returns
English strings.
SEE ALSO
UCS4_IsXXXX
DESCRIPTION
These functions allow you to find out whether a character
matches a certain type according.
The functions available are:
UCS4_IsAlNum() - is this an alphanumeric character
UCS4_IsAlpha() - is this an alphabet character
UCS4_IsCntrl() - is this a control character
UCS4_IsDigit() - is this a decimal digit character
UCS4_IsGraph() - is this a graphical character
UCS4_IsLower() - is this a lowercase character
UCS4_IsPrint() - is this a printable character
UCS4_IsPunct() - is this a punctuation character
UCS4_IsSpace() - is this a whitespace character
UCS4_IsUpper() - is this an uppercase character
UCS4_IsXDigit() - is this a hexadecimal digit
INPUTS
ucharacter - the character to test in the native byte order
RESULT
state - An indication of whether the character matches the type
SEE ALSO
UCS4_Normalize
DESCRIPTION
Normalize Unicode string. Two normalization types are supported:
UCS4_NFD - Normalization Form Canonical Decomposition
UCS4_NFKD - Normalization Form Compatibility Decomposition
INPUTS
string - Unicode string (UCS-4) to normalize
buffer - buffer to contain normalized Unicode string (UCS-4)
length - buffer length in characters
type - normalization type
UCS4_StrnCmp
DESCRIPTION
UCS4_StrnCmp() will compare two wide character strings, up to
a maximum length of length using a specific kind of collation
information according to the locale.
The result will be less than zero, zero, or greater than zero
depending upon whether the string string1 is less than, equal
to, or greater than the string pointed to string2.
Input strings are UCS-4 strings in the native byte order
INPUTS
locale - Which locale to use for this comparison.
string1 - NULL terminated UCS-4 string using the native byte order.
string2 - NULL terminated UCS-4 string using the native byte order.
length - Maximum length of string to compare.
type - How to compare the strings, must be 0 for time being
RESULT
The relationship between the two strings.
< 0 means string1 < string2
= 0 means string1 == string2
> 0 means string1 > string2
SEE ALSO
UTF8_CheckEncoding
DESCRIPTION
Check if string is valid UTF-8 or not
INPUTS
string - NULL terminated string
length - the maximum number of bytes to examine or -1 to examine all
characters until a NULL is encountered
RESULT
result - is string valid UTF-8 or not
< 0 string is not valid UTF-8
= 0 string is ASCII but also valid UTF-8
> 0 string is valid UTF-8
UTF8_Decode
DESCRIPTION
Transcode multibyte UTF-8 sequence to UCS-4 code point. Function
reads octets from the input string and places corresponding UCS-4
code point into the supplied storage space. Function guaranteed to
not process data beyond terminating NULL byte.
If transcoding failed this function places an ASCII question mark
into the supplied buffer. This can only occur if the input string
did not contain UTF-8 (synchronisation error).
Transcoding itself is done without boundary checking. Therefore it
is under application writer's responsibility to check for overlong
forms or code points which are illegal in UCS-4. Illegal code points
are for example byte order marks (BOM) and surrogate pairs. Overlong
forms, while mostly harmless, can cause premature truncation of your
strings. See the second example code below if you wish to protect
your code against these errors
INPUTS
string - UTF-8 sequence
ucs4 - pointer to a UCS-4 storage space
RESULT
octets - number of octets (bytes) in the current UTF-8 sequence.
This can be used as an offset to the next UTF-8 sequence.
If the return code is 0 then the first byte of the input
string was a NULL byte and U+0000 was placed into the
storage space
EXAMPLE
// Convert UTF-8 string to UCS-4
VOID QuickUTF8toUCS4(CONST_STRPTR s, WSTRPTR ucs4)
{
ULONG octets;
do
{
octets = UTF8_Decode(s, ucs4);
s += octets;
ucs4++;
}
while (octets);
}
// Convert UTF-8 string to UCS-4 but replace illegal or impossible
// code points by replacement character.
//
VOID CompleteUTF8toUCS4(CONST_STRPTR s, WSTRPTR ucs4)
{
ULONG octets;
do
{
octets = UTF8_Decode(s, ucs4);
s += octets;
switch (octets)
{
case 0:
case 1: // Always OK
break;
case 2: // Valid range is 0x80...0x7ff
if (*ucs4 < 0x80)
*ucs4 = '?';
break;
case 3: // Valid range is 0x800...0xffff
if (*ucs4 < 0x800)
*ucs4 = '?';
// Code points U+D800 - U+DFFF may never appear in UTF-8
if (*ucs4 >= 0xd800 && *ucs4 <= 0xdfff)
*ucs4 = '?';
// Code points U+FFFE and U+FFFF are legal but should be removed
if (*ucs4 == 0xfffe || *ucs4 == 0xffff)
*ucs4 = '?';
break;
case 4: // Valid range is 0x10000...0x10ffff
if (*ucs4 < 0x10000 || *ucs4 > 0x10ffff)
*ucs4 = '?';
break;
}
ucs4++;
}
while (octets
SEE ALSO
UTF8_Encode
DESCRIPTION
Convert UCS-4 code point to multibyte UTF-8 sequence. Up to four
bytes are produced
INPUTS
ucs4 - UCS-4 code point
string - UTF-8 storage space
RESULT
octets - number of octets in the current UTF-8 sequence. Returns
zero on a NULL code point and UTF-8 storage space contains
NULL byte respectively
EXAMPLE
VOID UCS4toUTF8(STRPTR s, CONST_WSTRPTR ucs4)
{
ULONG octets;
do
{
octets = UTF8_Encode(*ucs4, s);
s += octets;
ucs4++;
}
while (octets
SEE ALSO
UTF8_EncodingLength
DESCRIPTION
Get UTF-8 encoding length for UCS-4 code point
INPUTS
ucharacter - the UCS-4/UTF-32 character to get encoding length from
RESULT
octets - If not NULL character this is number of octets (bytes) in
the correspoding UTF-8 sequence.
If NULL character this function returns zero
SEE ALSO
VSNPrintf
DESCRIPTION
Format a string using the locale's formatting conventions
INPUTS
locale - the locale to use for the formatting or NULL if the current
locale should be used.
buffer - the buffer to place result into
bufferlength - the size of the buffer
template - a C-language-like format string with the following % options:
%[arg_pos$][flags][width][.limit][length]type
arg_pos - an optional index to parameter list, starting from 1
$ - must follow the arg_pos value, if specified
flags -
- (minus) the output is left justified
+ (plus)
(space) a blank should be left before a positive number.
' (apostrophe) for decimal conversion the output is grouped with grouping
characters using the locale's formatting conventions.
width - a minimum field width
. -
limit - maximum number of characters (%b and %s) or precision (%f)
length - size of input data, defaults to 32-bit decimals, 64-bit float and 8-bit strings
l - for strings and characters, input is WCHAR or CONST_WSTRPTR, conversion
is to UTF-8
ll - for decimals 'll' changes size to 64-bit
type - supported types are:
b - BSTR
d,D - signed decimal
u,U - unsigned decimal
p - pointer
x - hexadecimal with hex digits in lowercase
X - hexadecimal with hex digits in uppercase
s - string
c - character
f - double to decimal notation
F - double to decimal notation
args - arguments for the format string
RESULT
length - Number of characters which would be generated for the given input,
excluding the trailing null
WARNING
This function is incompatible with old RawDoFmt() and FormatString() but almost
compatible with NewRawDoFmt().
SEE ALSO