Synopsis

void CloseCatalog(
         struct Catalog * catalog );

Function

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

GetCatalogStr() OpenCatalogA()

Synopsis

void CloseLocale(
         struct Locale * locale );

Function

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

OpenLocale()

Synopsis

ULONG ConvToLower(
         const struct Locale * locale,
         ULONG character );

Function

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 or NULL for
              the system default locale.
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.

Synopsis

ULONG ConvToUpper(
         const struct Locale * locale,
         ULONG character );

Function

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 or NULL for
              the system default locale.
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

ConvToLower()

Synopsis

VOID FormatDate(
         const struct Locale    * locale,
         CONST_STRPTR formatString,
         const struct DateStamp * date,
         const struct Hook      * hook );

Function

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 or NULL
                  for the system default locale.
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 %Z %Y"
                  %d -- day number with leading zeros
                  %D -- the same as "%m/%d/%y"
                  %e -- day number with leading spaces
                  %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
                  %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

ParseDate() libraries/locale.h

Synopsis

APTR FormatString(
         const struct Locale * locale,
         CONST_STRPTR fmtTemplate,
         RAWARG dataStream,
         const struct Hook * putCharFunc );

Synopsis

CONST_STRPTR GetCatalogStr(
         const struct Catalog * catalog,
         ULONG stringNum,
         CONST_STRPTR defaultString );

Function

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

OpenCatalogA() CloseCatalog()

Synopsis

CONST_STRPTR GetLocaleStr(
         const struct Locale * locale,
         ULONG stringNum );

Function

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.

Synopsis

BOOL IsXXXX(
         const struct Locale * locale,
         ULONG character );

Function

These functions allow you to find out whether a character
matches a certain type according to the current Locale
settings.

The functions available are:

IsAlNum()  - is this an alphanumeric character
IsAlpha()  - is this an alphabet character
IsCntrl()  - is this a control character
IsDigit()  - is this a decimal digit character
IsGraph()  - is this a graphical character
IsLower()  - is this a lowercase character
IsPrint()  - is this a printable character
IsPunct()  - is this a punctuation character
IsSpace()  - is this a whitespace character
IsUpper()  - is this an uppercase character
IsXDigit() - is this a hexadecimal digit

Inputs

locale      - The Locale to use for this function or NULL
              for the system default locale.
character   - the character to test

Result

ind - An indication of whether the character matches the type.
    TRUE - if the character is of the required type,
    FALSE - otherwise

Notes

These functions require a 32-bit character to support future
multi-byte character sets.

Synopsis

struct Catalog * OpenCatalogA(
         const struct Locale  * locale,
         CONST_STRPTR name,
         const struct TagItem * tags );

struct Catalog * OpenCatalog(
         const struct Locale  * locale,
         CONST_STRPTR name,
         TAG tag, ... );

Synopsis

struct Locale * OpenLocale(
         CONST_STRPTR name );

Function

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 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

CloseLocale()

Synopsis

BOOL ParseDate(
         const struct Locale    * locale,
         struct DateStamp * date,
         CONST_STRPTR fmtTemplate,
         const struct Hook      * getCharFunc );

Function

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 or NULL for
                the system default locale.
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: leading spaces are
      allowed before %e, but not before %d.

Bugs

%p, %b, %A and probably others accept substrings and superstrings of
valid strings.

See also

FormatDate()

Synopsis

ULONG RexxHost(
         struct RexxMsg * rxmsg );

Function

locale.library rexxhost interface

Synopsis

ULONG StrConvert(
         const struct Locale * locale,
         CONST_STRPTR string,
         APTR buffer,
         ULONG bufferSize,
         ULONG type );

Function

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 or
                NULL for the system default locale.
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

LONG StrnCmp(
         const struct Locale * locale,
         CONST_STRPTR string1,
         CONST_STRPTR string2,
         LONG length,
         ULONG type );

Function

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 or
                NULL for the system default locale.
string1     -   NULL terminated string.
string2     -   NULL terminated string.
length      -   Maximum length of string to compare, or -1 to
    compare entire strings.
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

OpenLocale() CloseLocale() StrConvert()