home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / devcon / milan_1991 / devcon91.2 / locale / development / autodocs / locale.doc
Text File  |  1992-09-01  |  32KB  |  937 lines
  1. TABLE OF CONTENTS
  2.  
  3. locale.library/--rexxhost--
  4. locale.library/--structures--
  5. locale.library/CloseCatalog
  6. locale.library/CloseLocale
  7. locale.library/ConvToLower
  8. locale.library/ConvToUpper
  9. locale.library/FormatDate
  10. locale.library/FormatString
  11. locale.library/GetCatalogStr
  12. locale.library/GetLocaleStr
  13. locale.library/IsXXXX
  14. locale.library/OpenCatalog
  15. locale.library/OpenLocale
  16. locale.library/ParseDate
  17. locale.library/StrConvert
  18. locale.library/StrnCmp
  19. locale.library/--rexxhost--                       locale.library/--rexxhost--
  20.  
  21.    HOST INTERFACE
  22.     locale.library provides an ARexx function host interface that enables
  23.     ARexx programs to take advantage of system localization. The
  24.     functions provided by the interface are directly related to the
  25.     functions described herein, with the differences mostly being
  26.     in the way they are called.
  27.  
  28.     The function host library vector is located at offset -30 from the
  29.     library. This is the value you provide to ARexx in the AddLib()
  30.     function call.
  31.  
  32.    FUNCTIONS
  33.     CloseCatalog (CATALOG/N/A)
  34.     ConvToLower (CHARACTER/A)
  35.     ConvToUpper (CHARACTER/A)
  36.     GetCatalogStr (CATALOG/A,STRING/N/A,DEFAULT/A)
  37.     IsAlNum (CHARACTER/A)
  38.     IsAlpha (CHARACTER/A)
  39.     IsCntrl (CHARACTER/A)
  40.     IsDigit (CHARACTER/A)
  41.     IsGraph (CHARACTER/A)
  42.     IsLower (CHARACTER/A)
  43.     IsPrint (CHARACTER/A)
  44.     IsPunct (CHARACTER/A)
  45.     IsSpace (CHARACTER/A)
  46.     IsUpper (CHARACTER/A)
  47.     IsXDigit (CHARACTER/A)
  48.     OpenCatalog (NAME/A,BUILTIN/A,VERSION/N/A)
  49.     Strncmp (STRING1/A,STRING2/A,TYPE/N/A)
  50.  
  51.    EXAMPLE
  52.     /* localetest.rexx */
  53.  
  54.     /* Make sure locale is loaded as a function host */
  55.     IF ~SHOW(L,'locale.library') THEN DO
  56.       CALL ADDLIB('locale.library',0,-30)
  57.     END;
  58.  
  59.     say ConvToLower("A");
  60.     say ConvToUpper("b");
  61.     say IsAlpha("1");
  62.  
  63.     catalog = OpenCatalog("workbench.catalog","english",0);
  64.     say GetCatalogStr(catalog,34,"default");
  65.     say CloseCatalog(catalog);
  66.     say StrnCmp("test","test",2);
  67.  
  68. locale.library/--structures--                   locale.library/--structures--
  69.  
  70.     The Locale structure is the main public structure provided by
  71.     locale.library. The structure is defined in <libraries/locale.h>
  72.     and consists of the following fields:
  73.  
  74.     STRPTR loc_LocaleName
  75.         Locale's name.
  76.  
  77.     STRPTR loc_LanguageName
  78.         The language of the driver bound to this locale.
  79.  
  80.     STRPTR loc_PrefLanguages[10]
  81.         The ordered list of preferred languages for this locale.
  82.  
  83.     ULONG loc_Flags
  84.         Locale flags. Currently always 0.
  85.  
  86.     ULONG loc_CodeSet
  87.         Specifies the code set required by this locale. Currently, this
  88.         value is always 0.
  89.  
  90.     ULONG loc_CountryCode
  91.         The international country code.
  92.  
  93.     ULONG loc_TelephoneCode
  94.         The international telephone code for the country.
  95.  
  96.     LONG loc_GMTOffset
  97.         The offset in minutes of the current location from GMT.
  98.  
  99.     UBYTE loc_MeasuringSystem
  100.         The measuring system being used.
  101.  
  102.     STRPTR loc_DateTimeFormat
  103.         The date and time format string, ready to pass to FormatDate()
  104.  
  105.     STRPTR loc_DateFormat
  106.         The date format string.
  107.  
  108.     STRPTR loc_TimeFormat
  109.         The time format string.
  110.  
  111.     STRPTR loc_ShortDateTimeFormat
  112.         The short date and time format string, ready to pass to
  113.         FormatDate()
  114.  
  115.     STRPTR loc_ShortDateFormat
  116.         The short date format string.
  117.  
  118.     STRPTR loc_ShortTimeFormat
  119.         The short time format string.
  120.  
  121.     STRPTR loc_DecimalPoint
  122.         The decimal point character used to format non-monetary quantities.
  123.  
  124.     STRPTR loc_GroupSeparator
  125.         The characters used to separate groups of digits before the
  126.         decimal-point character in formatted non-monetary quantities.
  127.  
  128.     STRPTR loc_FracGroupSeparator
  129.         The characters used to separate groups of digits after the
  130.         decimal-point character in formatted non-monetary quantities.
  131.  
  132.     STRPTR loc_Grouping
  133.         A string whose elements indicate the size of each group of digits
  134.         before the decimal-point character in formatted non-monetary
  135.         quantities.
  136.  
  137.     STRPTR loc_FracGrouping
  138.         A string whose elements indicate the size of each group of digits
  139.         after the decimal-point character in formatted non-monetary
  140.         quantities.
  141.  
  142.     STRPTR loc_MonDecimalPoint
  143.         The decimal-point used to format monetary quantities.
  144.  
  145.     STRPTR loc_MonGroupSeparator
  146.         The separator for groups of digits before the decimal-point in
  147.         monetary quantities.
  148.  
  149.     STRPTR loc_MonFracGroupSeparator
  150.         The separator for groups of digits after the decimal-point in
  151.         monetary quantities.
  152.  
  153.     STRPTR loc_MonGrouping
  154.         A string whose elements indicate the size of each group of digits
  155.         before the decimal-point character in monetary quantities.
  156.  
  157.     STRPTR loc_MonFracGrouping
  158.         A string whose elements indicate the size of each group of digits
  159.         after the decimal-point character in monetary quantities.
  160.  
  161.     UBYTE loc_MonFracDigits
  162.         The number of fractional digits (those after the decimal-point)
  163.         to be displayed in a formatted monetary quantity.
  164.  
  165.     UBYTE loc_MonIntFracDigits
  166.         The number of fractional digits (those after the decimal-point)
  167.         to be displayed in an internationally formatted monetary quantity.
  168.  
  169.     STRPTR loc_MonCS
  170.         The local currency symbol applicable to the current locale.
  171.  
  172.     STRPTR loc_MonSmallCS
  173.         The currency symbol for small amounts.
  174.  
  175.     STRPTR loc_MonIntCS
  176.         The international currency symbol applicable to the current
  177.         locale. The first three characters contain the alphabetic
  178.         international currency symbol in accordance with those specified
  179.         in ISO 4217 Codes for the Representation of Currency and Funds.
  180.         The fourth character (immediately preceding the NULL) is the
  181.         character used to separate the international currency symbol from
  182.         the monetary quantity.
  183.  
  184.     STRPTR loc_MonPositiveSign
  185.         The string used to indicate a non-negative monetary quantity.
  186.  
  187.     UBYTE loc_MonPositiveSpaceSep
  188.         Specifies the number of spaces separating the currency symbol from
  189.         the non-negative monetary quantity.
  190.  
  191.     UBYTE loc_MonPositiveSignPos
  192.         Set to a value indicating the positioning of loc_MonPositiveSign
  193.         for a non-negative monetary quantity.
  194.  
  195.     UBYTE loc_MonPositiveCSPos
  196.         Set to 1 or 0 if loc_MonCS respectively precedes or succeeds
  197.         the value for a non-negative monetary quantity.
  198.  
  199.     STRPTR loc_MonNegativeSign
  200.         The string used to indicate a negative monetary quantity.
  201.  
  202.     UBYTE loc_MonNegativeSpaceSep
  203.         Specifies the number of spaces separating the currency symbol from
  204.         the negative monetary quantity.
  205.  
  206.     UBYTE loc_MonNegativeSignPos
  207.         Set to a value indicating the positioning of loc_MonNegativeSign
  208.         for a negative monetary quantity.
  209.  
  210.     UBYTE loc_MonNegativeCSPos
  211.         Set to 1 or 0 if loc_MonCS respectively precedes or succeeds
  212.         the value for a negative monetary quantity.
  213.  
  214.  
  215.     The grouping tables pointed to by loc_Grouping, loc_FracGrounping,
  216.     loc_MonGrouping, and loc_MonFracGrouping contain a stream of bytes
  217.     with the following values:
  218.  
  219.         255        No further grouping is to be performed.
  220.  
  221.         0        The previous element is to be repeatedly used for the
  222.             remainder of the digits.
  223.  
  224.         1..254    The integer value is the number of digits that comprise
  225.             the current group. The next element is examined to
  226.             determine the size of the next group of digits before
  227.             the current group.
  228.  
  229.     The values of loc_MonPositiveSignPos and loc_MonNegativeSignPos are
  230.     interpreted according to the following:
  231.  
  232.         0        Parentheses surround the quantity and currency symbol
  233.  
  234.         1        The sign string precedes the quantity and
  235.             currency symbol
  236.  
  237.         2        The sign string succeeds the quantity and
  238.             currency symbol
  239.  
  240.         3        The sign string immediately precedes the
  241.             currency symbol
  242.  
  243.         4        The sign string immediately succeeds the
  244.             currency symbol.
  245.  
  246. locale.library/CloseCatalog                       locale.library/CloseCatalog
  247.  
  248.    NAME
  249.     CloseCatalog -- close a message catalog. (V38)
  250.  
  251.    SYNOPSIS
  252.     CloseCatalog(catalog);
  253.                  A0
  254.  
  255.     VOID CloseCatalog(struct Catalog *);
  256.  
  257.    FUNCTION
  258.     Concludes access to a message catalog. The usage count of the
  259.     catalog is decremented. When this count reaches 0, the catalog
  260.     can be expunged from system memory whenever a memory panic occurs.
  261.  
  262.    INPUTS
  263.     catalog - the message catalog to close. A NULL catalog is a valid
  264.           parameter and is simply ignored.
  265.  
  266.    SEE ALSO
  267.     OpenCatalog(), GetCatalogStr()
  268.  
  269. locale.library/CloseLocale                         locale.library/CloseLocale
  270.  
  271.    NAME
  272.     CloseLocale -- close a locale. (V38)
  273.  
  274.    SYNOPSIS
  275.     CloseLocale(locale);
  276.                 A0
  277.  
  278.     VOID CloseLocale(struct Locale *);
  279.  
  280.    FUNCTION
  281.     Concludes access to a locale.
  282.  
  283.    INPUTS
  284.     locale - an opened locale. A NULL locale is a valid
  285.          parameter and is simply ignored.
  286.  
  287.    SEE ALSO
  288.     OpenLocale(), <libraries/locale.h>
  289.  
  290. locale.library/ConvToLower                         locale.library/ConvToLower
  291.  
  292.    NAME
  293.     ConvToLower -- convert a character to lower case. (V38)
  294.  
  295.    SYNOPSIS
  296.     char = ConvToLower(locale,character);
  297.     D0               A0     D0
  298.  
  299.     ULONG ConvToLower(struct Locale *,ULONG);
  300.  
  301.    FUNCTION
  302.     This function tests if the character specified is upper case. If it is
  303.     then the lower case version of that character is returned, and if it
  304.     isn't then the original character is returned.
  305.  
  306.    INPUTS
  307.     locale - the locale to use for the conversion
  308.     character - the character to convert
  309.  
  310.    RESULTS
  311.     char - a (possibly) converted character
  312.  
  313.    NOTE
  314.     This function requires a full 32-bit character be passed-in in order
  315.     to support multi-byte character sets.
  316.  
  317. locale.library/ConvToUpper                         locale.library/ConvToUpper
  318.  
  319.    NAME
  320.     ConvToUpper -- convert a character to upper case. (V38)
  321.  
  322.    SYNOPSIS
  323.     char = ConvToUpper(locale,character);
  324.     D0               A0     D0
  325.  
  326.     ULONG ConvToUpper(struct Locale *,ULONG);
  327.  
  328.    FUNCTION
  329.     This function tests if the character specified is lower case. If it is
  330.     then the upper case version of that character is returned, and if it
  331.     isn't then the original character is returned.
  332.  
  333.    INPUTS
  334.     locale - the locale to use for the conversion
  335.     character - the character to convert
  336.  
  337.    RESULTS
  338.     char - a (possibly) converted character
  339.  
  340.    NOTE
  341.     This function requires a full 32-bit character be passed-in in order
  342.     to support multi-byte character sets.
  343.  
  344. locale.library/FormatDate                           locale.library/FormatDate
  345.  
  346.    NAME
  347.     FormatDate -- generate a date string based on a date formatting
  348.               template. (V38)
  349.  
  350.    SYNOPSIS
  351.     FormatDate(locale,string,date,putCharFunc);
  352.                A0     A1     A2   A3
  353.  
  354.     VOID FormatDate(struct Locale *,STRPTR,struct DateStamp *,
  355.                     struct Hook *);
  356.  
  357.    FUNCTION
  358.     This function processes a formatting template and generates
  359.     a stream of bytes that's sent one character at a time to the
  360.     putCharFunc callback hook.
  361.  
  362.    INPUTS
  363.     locale - the locale to use for the formatting
  364.     string - the NULL-terminated template describing the desired format
  365.          for the date. This is constructed just like C-language
  366.          printf() statements, except that different formatting codes
  367.              are used. Just like in C, formatting codes start with a
  368.              % followed by the formatting command. The following
  369.          commands are accepted by this function:
  370.  
  371.                  %a - abbreviated weekday name
  372.                  %A - weekday name
  373.                  %b - abbreviated month name
  374.                  %B - month name
  375.                  %c - same as "%a %b %d %H:%M:%S %Y"
  376.                  %C - same as "%a %b %e %T %Z %Y"
  377.                  %d - day number with leading 0s
  378.                  %D - same as "%m/%d/%y"
  379.                  %e - day number with leading spaces
  380.                  %h - abbreviated month name
  381.                  %H - hour using 24-hour style
  382.                  %I - hour using 12-hour style
  383.                  %j - julian date
  384.                  %m - month number with leading 0s
  385.                  %M - the number of minutes with leading 0s
  386.                  %n - insert a linefeed
  387.                  %p - AM or PM strings
  388.                  %r - same as "%I:%M:%S %p"
  389.                  %R - same as "%H:%M"
  390.                  %S - number of seconds with leadings 0s
  391.                  %t - insert a tab character
  392.                  %T - same as "%H:%M:%S"
  393.                  %U - week number, taking Sunday as first day of week
  394.                  %w - weekday number
  395.                  %W - week number, taking Monday as first day of week
  396.                  %x - same as "%m/%d/%y"
  397.                  %X - same as "%H:%M:%S"
  398.                  %y - year using two digits with leading 0s
  399.                  %Y - year using four digits with leading 0s
  400.  
  401.              If the template parameter is NULL, a single NULL byte
  402.          is sent to putCharFunc.
  403.     date - the date to format into a string
  404.     putCharFunc - a callback hook invoked for every character generated,
  405.               including for the terminating NULL character. The hook
  406.               is called with:
  407.  
  408.              A0 - address of Hook structure
  409.             A1 - character for hook to process (not a pointer!)
  410.                     A2 - locale pointer
  411.  
  412.    SEE ALSO
  413.     ParseDate(), <libraries/locale.h>, <dos/dos.h>
  414.  
  415. locale.library/FormatString                       locale.library/FormatString
  416.  
  417.    NAME
  418.     FormatString -- format data into a character stream. (V38)
  419.  
  420.    SYNOPSIS
  421.     next = FormatString(locale,string,dataStream,putCharFunc);
  422.     D0                  A0     A1     A2         A3
  423.  
  424.     APTR FormatString(struct LocaleBase *,STRPTR,APTR,struct Hook *);
  425.  
  426.    FUNCTION
  427.     This function performs C-language-like formatting of a data stream,
  428.     outputting the result a character at a time. Where % formatting
  429.     commands are found in the string, they are replaced with the
  430.     corresponding elements in 'dataStream'. %% must be used in the
  431.     string if a % is desired in the output.
  432.  
  433.     An extension to the standard C-language printf() conventions used
  434.     by FormatString() is argument position specification. Specifying the
  435.     argument position lets the order of the % commands change while the
  436.     arguments provided remain the same. Using the C printf() call as an
  437.     example:
  438.         printf("%d eyes, %d feet and %d ears",eyes,feet,ears);
  439.         printf("%3$d ears, %1$d eyes and %2$d feet",eyes,feet,ears);
  440.     These two statements would produce the following output:
  441.         "2 eyes, 3 feet and 4 ears" for the first
  442.             "4 ears, 2 eyes and 3 feet" for the second
  443.  
  444.     The argument positioning feature lets you change the format string
  445.     being processed while keeping the data stream the same. This is
  446.     an invaluable tool when translating strings to different languages.
  447.  
  448.    INPUTS
  449.     locale - the locale to use for the formatting
  450.     string - a C-language-like NULL-terminated format string,
  451.          with the following supported % options:
  452.  
  453.       %[arg_pos$][flags][width][.limit][length]type
  454.  
  455.       arg_pos - ordinal position of the argument for this command within
  456.             the array of arguments pointed to by 'dataStream'
  457.         $     - must follow the arg_pos value, if specified
  458.       flags   - only one allowed. '-' specifies left justification.
  459.       width   - field width. If the first character is a '0', the
  460.                 field is padded with leading 0s.
  461.         .     - must precede the field width value, if specified
  462.       limit   - maximum number of characters to output from a string.
  463.                 (only valid for %s or %b).
  464.       length  - size of input data defaults to word (16-bit) for types c,
  465.             d, u and x, 'l' changes this to long (32-bit).
  466.       type    - supported types are:
  467.                       b - BSTR, data is 32-bit BPTR to byte count followed
  468.                           by a byte string. A NULL BPTR is treated as an
  469.                   empty string.
  470.                       d - signed decimal
  471.               D - signed decimal using the locale's formatting
  472.                   conventions
  473.               u - unsigned decimal
  474.               U - unsigned decimal using the locale's formatting
  475.                   conventions
  476.                       x - hexadecimal
  477.                       s - string, a 32-bit pointer to a NULL-terminated
  478.                           byte string. A NULL pointer is treated
  479.                           as an empty string.
  480.                       c - character
  481.  
  482.              If the string parameter is NULL, the function returns without
  483.          outputting anything.
  484.     dataStream - a stream of data that is interpreted according to
  485.              the format string. Often this is a pointer into
  486.              the task's stack.
  487.     putCharFunc - a callback hook invoked for every character generated,
  488.               including for the terminating NULL character. The hook
  489.               is called with:
  490.  
  491.              A0 - address of Hook structure
  492.             A1 - character for hook to process (not a pointer!)
  493.                     A2 - locale pointer
  494.  
  495.              the function is called with a NULL char at the end of
  496.              the format string.
  497.  
  498.    RESULTS
  499.     next - A pointer to beyond the last data element used in 'dataStream'
  500.            (the next argument that would have been processed).
  501.            This allows multiple formatting passes to be made using the
  502.            same data.
  503.  
  504.    WARNING
  505.     This function formats word values in the data stream. If your compiler
  506.     defaults to longs, you must add an "l" to your specifications. This
  507.     can get strange for characters, which might look like "%lc".
  508.  
  509.    SEE ALSO
  510.     exec.library/RawDoFmt()
  511.  
  512. locale.library/GetCatalogStr                     locale.library/GetCatalogStr
  513.  
  514.    NAME
  515.     GetCatalogStr -- get a string from a message catalog. (V38)
  516.  
  517.    SYNOPSIS
  518.     string = GetCatalogStr(catalog,stringNum,defaultString);
  519.     D0                     A0      D0        A1
  520.  
  521.     STRPTR GetCatalogStr(struct Catalog *,LONG,STRPTR);
  522.  
  523.    FUNCTION
  524.     This function returns a specific string within a message catalog.
  525.     If the catalog parameter is NULL, or the requested message does not
  526.     exist, then defaultString is returned.
  527.  
  528.    INPUTS
  529.     catalog - a message catalog as obtained from OpenCatalog(), or NULL
  530.     stringNum - a message number within the catalog
  531.     defaultString - string to return in case "catalog" is NULL or
  532.                     "stringNum" can't be found
  533.  
  534.    RESULTS
  535.     string - a pointer to a NULL-terminated string. The returned string
  536.          is READ-ONLY, do NOT modify! This string pointer is valid
  537.          only as long as the catalog remains open.
  538.  
  539.    SEE ALSO
  540.     OpenCatalog(), CloseCatalog()
  541.  
  542. locale.library/GetLocaleStr                       locale.library/GetLocaleStr
  543.  
  544.    NAME
  545.     GetLocaleStr -- get a standard string from a locale. (V38)
  546.  
  547.    SYNOPSIS
  548.     string = GetLocaleStr(locale,stringNum);
  549.     D0                    A0     D0
  550.  
  551.     STRPTR GetLocaleStr(struct Locale *,ULONG);
  552.  
  553.    FUNCTION
  554.     This function returns a specific string associated with the given
  555.     locale.
  556.  
  557.    INPUTS
  558.     locale - a valid locale
  559.     stringNum - the number of the string to get a pointer to. See the
  560.             constants defined in <libraries/locale.h> for the
  561.             possible values.
  562.  
  563.    RESULTS
  564.     string - a pointer to a NULL-terminated string, or NULL if the
  565.          requested string number was out of bounds. The returned
  566.          string is READ-ONLY, do NOT modify! This string pointer
  567.          is valid only as long as the locale remains open.
  568.  
  569.    SEE ALSO
  570.     OpenLocale(), CloseLocale(), <libraries/locale.h>
  571.  
  572. locale.library/IsXXXX                                   locale.library/IsXXXX
  573.  
  574.    NAME
  575.     IsXXXX -- determine whether a character is of a certain type. (V38)
  576.  
  577.    SYNOPSIS
  578.     state = IsXXXX(locale,character);
  579.     D0           A0     D0
  580.  
  581.     BOOL IsXXXX(struct Locale *,ULONG);
  582.  
  583.    FUNCTION
  584.     These functions determine whether the character specified is of a
  585.     certain type, according to the supplied locale.
  586.  
  587.     IsAlNum() - test if alphanumeric character
  588.     IsAlpha() - test if alphabetical character
  589.     IsCntrl() - test if control character
  590.     IsDigit() - test if decimal digit character
  591.     IsGraph() - test if visible character
  592.     IsLower() - test if lower case character
  593.     IsPrint() - test if blank
  594.     IsPunct() - test if punctuation character
  595.     IsSpace() - test if white space character
  596.     IsUpper() - test if upper case character
  597.     IsXDigit() - test if hexadecimal digit
  598.  
  599.    INPUTS
  600.     locale - the locale to use for the test
  601.     character - the character to test
  602.  
  603.    RESULTS
  604.     state - TRUE if the character is of the required type, FALSE otherwise
  605.  
  606.    NOTE
  607.     These functions require full 32-bit characters be passed-in in order
  608.     to support multi-byte character sets.
  609.  
  610. locale.library/OpenCatalog                         locale.library/OpenCatalog
  611.  
  612.    NAME
  613.     OpenCatalogA -- open a message catalog. (V38)
  614.     OpenCatalog -- varargs stub for OpenCatalogA(). (V38)
  615.  
  616.    SYNOPSIS
  617.     catalog = OpenCatalogA(locale,name,tagList);
  618.     D0                     A0     A1   A2
  619.  
  620.     struct Catalog *OpenCatalogA(struct Locale *,STRPTR,struct TagItem *);
  621.  
  622.     catalog = OpenCatalog(locale,name,firstTag, ...);
  623.  
  624.     struct Catalog *OpenCatalog(struct Locale *,STRPTR,Tag, ...);
  625.  
  626.    FUNCTION
  627.     This function opens a message catalog. Catalogs contain all the
  628.     text strings that an application uses. These strings can easily
  629.     be replaced by strings in a different language, which causes the
  630.     application to magically start operating in that new language.
  631.  
  632.     Catalogs originally come from disk files. This function searches for
  633.     them in the following places:
  634.  
  635.         PROGDIR:Catalogs/languageName/name
  636.         LOCALE:Catalogs/languageName/name
  637.  
  638.     where languageName is the name of the language associated with the
  639.     locale parameter. So assuming an application called WizPaint:
  640.  
  641.         catalog = OpenCatalog(NULL,
  642.                       "WizPaint.catalog",
  643.                       OC_BuiltInLanguage,"english",
  644.                       TAG_DONE);
  645.  
  646.     Passing NULL as first parameter to OpenCatalog() indicates you
  647.     wish to use the system's default locale. Assuming the default locale
  648.     specifies "deutsch" as language, OpenCatalog() tries to open the
  649.     catalog as:
  650.  
  651.         PROGDIR:Catalogs/deutsch/WizPaint.catalog
  652.  
  653.     and if that file is not found, then OpenCatalog() tries to open it
  654.     as:
  655.  
  656.         LOCALE:Catalogs/deutsch/WizPaint.catalog
  657.  
  658.        PROGDIR: is not always checked before LOCALE: is. If the volume which
  659.     PROGDIR: is assigned to is NOT currently mounted, and if the one
  660.     which LOCALE: is assigned to IS mounted, then LOCALE: is checked
  661.     first, followed by PROGDIR: if needed. This is done in order to
  662.     minimize the number of disk swaps on floppy systems.
  663.  
  664.     The OC_BuiltInLanguage tag specifies the language of the strings
  665.     that are built into the application. If the language of the
  666.     built-in strings matches that of the locale, then no catalog
  667.     need be loaded from disk and the built-in strings can be used
  668.     directly.
  669.  
  670.     locale.library caches text catalogs in order to minimize disk
  671.     access. As such, OpenCatalog() may or may not cause disk access.
  672.     This fact should be taken into consideration. Unused catalogs are
  673.     automatically flushed from the system when there is not enough
  674.     memory. When there is disk access, it is possible a DOS requester
  675.     may be opened asking for a volume to be inserted. You can avoid this
  676.     requester opening by setting your process' pr_WindowPtr field to -1.
  677.  
  678.    INPUTS
  679.     locale - the locale for which the catalog should be opened, or NULL.
  680.          When NULL, then the system's default locale is used. This
  681.          should generally be NULL
  682.     name - the NULL-terminated name of the catalog to open, typically
  683.            the application name with a ".catalog" extension
  684.     tagList - pointer to an array of tags providing optional extra
  685.           parameters, or NULL
  686.  
  687.    TAGS
  688.     OC_BuiltInLanguage (STRPTR) - language of built-in strings of the
  689.                       application. That is, this tag identifies
  690.                       the language used for the "defaultString"
  691.                       parameter used in the GetCatalogStr()
  692.                       function. Default is "english".
  693.  
  694.     OC_BuiltInCodeSet (ULONG) - code set of built-in strings. Default is 0.
  695.                     THIS TAG SHOULD ALWAYS BE SET TO 0 FOR NOW.
  696.  
  697.     OC_Language (STRPTR) - language explicitly requested for the catalog.
  698.                    A catalog of this language will be returned if
  699.                    possible, otherwise a catalog in one of the
  700.                    user's preferred languages. This tag should
  701.                    normally not be provided as it overrides the
  702.                    user's preferences.
  703.  
  704.     OC_Version (UWORD) - catalog version number required. Default is 0
  705.                  which means to accept any version of the catalog
  706.                  that is found. Note that if a version is
  707.                  specified, the catalog's version much match it
  708.                  exactly. This is different from version numbers
  709.                  used by OpenLibrary().
  710.  
  711.    RESULTS
  712.     catalog - a message catalog to use with GetCatalogStr() or NULL.
  713.           A NULL result does not necessarily indicate an error.
  714.           If OpenCatalog() determines that the built-in strings of
  715.           the application can be used instead of an external catalog
  716.           from disk, then NULL is returned. To determine whether
  717.           a NULL result actually indicates an error, look at the
  718.           return value of dos.library/IoErr(). 0 means no error.
  719.  
  720.           GetCatalogStr() interprets a NULL catalog as meaning to use
  721.           the built-in strings.
  722.  
  723.    NOTE
  724.     In most cases, failing to open a catalog should not be considered a
  725.     fatal error, and the application should continue operating and
  726.     simply use the built-in set of strings instead of the disk-based
  727.     catalog. Note that GetCatalogStr() accepts a NULL catalog pointer for
  728.     this very reason.
  729.  
  730.     Also note that displaying an error message when a catalog fails to
  731.     open can be a meaningless endeavor as the message is likely in a
  732.     language the user does not understand.
  733.  
  734.    SEE ALSO
  735.     CloseCatalog(), GetCatalogStr()
  736.  
  737. locale.library/OpenLocale                           locale.library/OpenLocale
  738.  
  739.    NAME
  740.     OpenLocale -- open a locale. (V38)
  741.  
  742.    SYNOPSIS
  743.     locale = OpenLocale(name);
  744.     D0                  A0
  745.  
  746.     struct Locale *OpenLocale(STRPTR);
  747.  
  748.    FUNCTION
  749.     This function opens a named locale. Locales contain many parameters
  750.     that an application needs to consider when being integrated into
  751.     different languages, territories and customs. Using the information
  752.     stored in a locale instead of hard-coding it into an application,
  753.     lets the application dynamically adapt to the user's environment.
  754.  
  755.     Locales originally come from disk files. This function searches for
  756.     them as:
  757.  
  758.         name
  759.         SYS:Prefs/Presets/name
  760.  
  761.     Every locale specifies a language, and special language drivers
  762.     must be loaded from disk depending on which language is being used.
  763.     These files include for example:
  764.  
  765.         LOCALE:Languages/francais.language
  766.         LOCALE:Languages/dansk.language
  767.         LOCALE:Languages/italiano.language
  768.  
  769.    INPUTS
  770.     name - the NULL-terminated name of the locale to open, or NULL to open
  771.            the current default locale. This should generally be NULL.
  772.  
  773.    RESULTS
  774.     locale - a pointer to an initialized Locale structure, or NULL if the
  775.          locale could not be loaded. In the case of a NULL return, the
  776.          DOS IoErr() function can be called to obtain more information
  777.          on the failure.
  778.  
  779.          When passing a NULL name parameter to this function, you are
  780.          guaranteed a valid return.
  781.  
  782.    SEE ALSO
  783.     CloseLocale(), <libraries/locale.h>
  784.  
  785. locale.library/ParseDate                             locale.library/ParseDate
  786.  
  787.    NAME
  788.     ParseDate -- interpret a string according to the date formatting
  789.              template and convert it into a DateStamp. (V38)
  790.  
  791.    SYNOPSIS
  792.     state = ParseDate(locale,date,template,getCharFunc);
  793.     D0              A0     A1   A2       A3
  794.  
  795.     BOOL ParseDate(struct Locale *,struct DateStamp *,STRPTR,struct Hook *);
  796.  
  797.    FUNCTION
  798.     This function converts a stream of characters into an AmigaDOS
  799.     DateStamp structure. The characters are obtained from the
  800.     getCharFunc callback hook and the formatting template is used
  801.     to direct the parse.
  802.  
  803.    INPUTS
  804.     locale - the locale to use for the formatting
  805.     date - place to put the converted date, this may be NULL in which
  806.            case this routine can be used to simply validate a date
  807.     template - the date template describing the expected format of the
  808.            data. See FormatDate() above for a description of date
  809.            templates.
  810.     getCharFunc - a callback hook invoked whenever a character is required.
  811.               The hook should return the next character to process,
  812.               with a NULL character to indicate the end of the string.
  813.               The hook is called with:
  814.  
  815.              A0 - address of Hook structure
  816.                     A1 - locale pointer
  817.             A2 - NULL
  818.  
  819.                   The hook returns the character to process in D0. Note
  820.               that a complete 32-bit result is expected in D0, not
  821.               just 8 bits.
  822.  
  823.    RESULTS
  824.     state - TRUE if the parsing went OK, or FALSE if the input did not
  825.         match the template
  826.  
  827.    SEE ALSO
  828.     FormatDate(), <dos/dos.h>
  829.  
  830. locale.library/StrConvert                           locale.library/StrConvert
  831.  
  832.    NAME
  833.     StrConvert -- transform a string according to collation information.
  834.               (V38)
  835.  
  836.    SYNOPSIS
  837.     length = StrConvert(locale,string,buffer,bufferSize,type);
  838.     D0                  A0     A1     A2     D0         D1
  839.  
  840.     ULONG StrConvert(struct Locale *,STRPTR,APTR,ULONG,ULONG);
  841.  
  842.    FUNCTION
  843.     This function transforms the passed string and places the resulting
  844.     into the supplied buffer. No more than bufferSize bytes are copied
  845.     into the buffer.
  846.  
  847.     The transformation is such that if the C strcmp() function is applied
  848.     to two transformed strings, it returns a value corresponding to
  849.     the result returned by the StrnCmp() function applied to the two
  850.     original strings.
  851.  
  852.    INPUTS
  853.     locale - the locale to use for the transformation
  854.     string - NULL-terminated string to transform
  855.     buffer - buffer where to put the transformed string
  856.     bufferSize - maximum number of bytes to deposit in the buffer
  857.                  StrConvert() may require more storage than
  858.              the unconverted string does
  859.     type - describes how the transformation is to be performed. See
  860.            the documentation on StrnCmp() for more information on the
  861.            comparison types available
  862.  
  863.    RESULTS
  864.     length - length of the transformed string which is the number of bytes
  865.          deposited in the buffer minus 1 (since strings are NULL-
  866.          terminated)
  867.  
  868.    SEE ALSO
  869.     StrnCmp(), <libraries/locale.h>
  870.  
  871. locale.library/StrnCmp                                 locale.library/StrnCmp
  872.  
  873.    NAME
  874.     StrnCmp -- localized string comparison. (V38)
  875.  
  876.    SYNOPSIS
  877.     result = StrnCmp(locale,string1,string2,length,type);
  878.     D0               A0     A1      A2      D0     D1
  879.  
  880.     LONG StrnCmp(struct Locale *,STRPTR,STRPTR,LONG,ULONG);
  881.  
  882.    FUNCTION
  883.     Compares string1 to string2 according to the collation information
  884.     provided by the locale and returns an integer greater than,
  885.     equal to, or less than zero, accordingly as the string pointed to
  886.     by string1 is greater than, equal to, or less than the string
  887.     pointed to by string2.
  888.  
  889.     The length parameter specifies how many characters to compare, or if
  890.     the length is specified as -1 then the strings are compared until
  891.     a NULL is encountered.
  892.  
  893.     The type parameter dictates how the comparison is to be performed.
  894.  
  895.    INPUTS
  896.     locale - the locale to use for this comparison
  897.     string1    - NULL-terminated string
  898.     string2    - NULL-terminated string
  899.     length - the maximum number of characters to be compared, or -1 to
  900.          compare all characters until a NULL is encountered
  901.     type - describes how the comparison is to be performed. The following
  902.            values can be passed:
  903.          SC_ASCII causes an ASCII-based case-insensitive comparison
  904.          to be performed. SC_ASCII is the fastest of the comparison
  905.          types, but it uses ASCII ordering and considers accented
  906.          characters different than their non-accented counterparts.
  907.  
  908.          SC_COLLATE1 causes the characters to be compared using their
  909.          primary sorting order. This effectively produces a comparison
  910.          that ignores letter case and diacritical marks. That is,
  911.          letters such as "e" and "é" are treated as if they were both
  912.          "e".
  913.  
  914.          SC_COLLATE2 causes the characters to be compared using both
  915.          their primary and secondary sorting order. SC_COLLATE2 is
  916.          slower than SC_COLLATE1. This is the type of comparison to
  917.          use when sorting data to be presented to the user. It operates
  918.          in two passes. First it performs a comparison equivalent to
  919.          SC_COLLATE1. If both strings compare the same, then a second
  920.          pass is made using the secondary sorting order, which gives
  921.          finer resolution to the comparison. For example, SC_COLLATE1
  922.          would return the following strings as identical:
  923.             "père"  and  "pere"
  924.          since SC_COLLATE1 ignores diacritical marks. SC_COLLATE2
  925.          would make a second pass over the string comparing
  926.          diacritical marks instead of actual characters.
  927.  
  928.    RESULTS
  929.     result - relationship between string1 and string2
  930.             <0 means string1 < string2
  931.             =0 means string1 = string2
  932.             >0 means string1 > string2
  933.  
  934.    SEE ALSO
  935.     OpenLocale(), CloseLocale(), StrConvert()
  936.  
  937.