Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucat.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 **********************************************************************
jpayne@69 5 * Copyright (c) 2003-2004, International Business Machines
jpayne@69 6 * Corporation and others. All Rights Reserved.
jpayne@69 7 **********************************************************************
jpayne@69 8 * Author: Alan Liu
jpayne@69 9 * Created: March 19 2003
jpayne@69 10 * Since: ICU 2.6
jpayne@69 11 **********************************************************************
jpayne@69 12 */
jpayne@69 13 #ifndef UCAT_H
jpayne@69 14 #define UCAT_H
jpayne@69 15
jpayne@69 16 #include "unicode/utypes.h"
jpayne@69 17 #include "unicode/ures.h"
jpayne@69 18
jpayne@69 19 /**
jpayne@69 20 * \file
jpayne@69 21 * \brief C API: Message Catalog Wrappers
jpayne@69 22 *
jpayne@69 23 * This C API provides look-alike functions that deliberately resemble
jpayne@69 24 * the POSIX catopen, catclose, and catgets functions. The underlying
jpayne@69 25 * implementation is in terms of ICU resource bundles, rather than
jpayne@69 26 * POSIX message catalogs.
jpayne@69 27 *
jpayne@69 28 * The ICU resource bundles obey standard ICU inheritance policies.
jpayne@69 29 * To facilitate this, sets and messages are flattened into one tier.
jpayne@69 30 * This is done by creating resource bundle keys of the form
jpayne@69 31 * <set_num>%<msg_num> where set_num is the set number and msg_num is
jpayne@69 32 * the message number, formatted as decimal strings.
jpayne@69 33 *
jpayne@69 34 * Example: Consider a message catalog containing two sets:
jpayne@69 35 *
jpayne@69 36 * Set 1: Message 4 = "Good morning."
jpayne@69 37 * Message 5 = "Good afternoon."
jpayne@69 38 * Message 7 = "Good evening."
jpayne@69 39 * Message 8 = "Good night."
jpayne@69 40 * Set 4: Message 14 = "Please "
jpayne@69 41 * Message 19 = "Thank you."
jpayne@69 42 * Message 20 = "Sincerely,"
jpayne@69 43 *
jpayne@69 44 * The ICU resource bundle source file would, assuming it is named
jpayne@69 45 * "greet.txt", would look like this:
jpayne@69 46 *
jpayne@69 47 * greet
jpayne@69 48 * {
jpayne@69 49 * 1%4 { "Good morning." }
jpayne@69 50 * 1%5 { "Good afternoon." }
jpayne@69 51 * 1%7 { "Good evening." }
jpayne@69 52 * 1%8 { "Good night." }
jpayne@69 53 *
jpayne@69 54 * 4%14 { "Please " }
jpayne@69 55 * 4%19 { "Thank you." }
jpayne@69 56 * 4%20 { "Sincerely," }
jpayne@69 57 * }
jpayne@69 58 *
jpayne@69 59 * The catgets function is commonly used in combination with functions
jpayne@69 60 * like printf and strftime. ICU components like message format can
jpayne@69 61 * be used instead, although they use a different format syntax.
jpayne@69 62 * There is an ICU package, icuio, that provides some of
jpayne@69 63 * the POSIX-style formatting API.
jpayne@69 64 */
jpayne@69 65
jpayne@69 66 U_CDECL_BEGIN
jpayne@69 67
jpayne@69 68 /**
jpayne@69 69 * An ICU message catalog descriptor, analogous to nl_catd.
jpayne@69 70 *
jpayne@69 71 * @stable ICU 2.6
jpayne@69 72 */
jpayne@69 73 typedef UResourceBundle* u_nl_catd;
jpayne@69 74
jpayne@69 75 /**
jpayne@69 76 * Open and return an ICU message catalog descriptor. The descriptor
jpayne@69 77 * may be passed to u_catgets() to retrieve localized strings.
jpayne@69 78 *
jpayne@69 79 * @param name string containing the full path pointing to the
jpayne@69 80 * directory where the resources reside followed by the package name
jpayne@69 81 * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
jpayne@69 82 * If NULL, ICU default data files will be used.
jpayne@69 83 *
jpayne@69 84 * Unlike POSIX, environment variables are not interpolated within the
jpayne@69 85 * name.
jpayne@69 86 *
jpayne@69 87 * @param locale the locale for which we want to open the resource. If
jpayne@69 88 * NULL, the default ICU locale will be used (see uloc_getDefault). If
jpayne@69 89 * strlen(locale) == 0, the root locale will be used.
jpayne@69 90 *
jpayne@69 91 * @param ec input/output error code. Upon output,
jpayne@69 92 * U_USING_FALLBACK_WARNING indicates that a fallback locale was
jpayne@69 93 * used. For example, 'de_CH' was requested, but nothing was found
jpayne@69 94 * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the
jpayne@69 95 * default locale data or root locale data was used; neither the
jpayne@69 96 * requested locale nor any of its fallback locales were found.
jpayne@69 97 *
jpayne@69 98 * @return a message catalog descriptor that may be passed to
jpayne@69 99 * u_catgets(). If the ec parameter indicates success, then the caller
jpayne@69 100 * is responsible for calling u_catclose() to close the message
jpayne@69 101 * catalog. If the ec parameter indicates failure, then NULL will be
jpayne@69 102 * returned.
jpayne@69 103 *
jpayne@69 104 * @stable ICU 2.6
jpayne@69 105 */
jpayne@69 106 U_STABLE u_nl_catd U_EXPORT2
jpayne@69 107 u_catopen(const char* name, const char* locale, UErrorCode* ec);
jpayne@69 108
jpayne@69 109 /**
jpayne@69 110 * Close an ICU message catalog, given its descriptor.
jpayne@69 111 *
jpayne@69 112 * @param catd a message catalog descriptor to be closed. May be NULL,
jpayne@69 113 * in which case no action is taken.
jpayne@69 114 *
jpayne@69 115 * @stable ICU 2.6
jpayne@69 116 */
jpayne@69 117 U_STABLE void U_EXPORT2
jpayne@69 118 u_catclose(u_nl_catd catd);
jpayne@69 119
jpayne@69 120 /**
jpayne@69 121 * Retrieve a localized string from an ICU message catalog.
jpayne@69 122 *
jpayne@69 123 * @param catd a message catalog descriptor returned by u_catopen.
jpayne@69 124 *
jpayne@69 125 * @param set_num the message catalog set number. Sets need not be
jpayne@69 126 * numbered consecutively.
jpayne@69 127 *
jpayne@69 128 * @param msg_num the message catalog message number within the
jpayne@69 129 * set. Messages need not be numbered consecutively.
jpayne@69 130 *
jpayne@69 131 * @param s the default string. This is returned if the string
jpayne@69 132 * specified by the set_num and msg_num is not found. It must be
jpayne@69 133 * zero-terminated.
jpayne@69 134 *
jpayne@69 135 * @param len fill-in parameter to receive the length of the result.
jpayne@69 136 * May be NULL, in which case it is ignored.
jpayne@69 137 *
jpayne@69 138 * @param ec input/output error code. May be U_USING_FALLBACK_WARNING
jpayne@69 139 * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that
jpayne@69 140 * the set_num/msg_num tuple does not specify a valid message string
jpayne@69 141 * in this catalog.
jpayne@69 142 *
jpayne@69 143 * @return a pointer to a zero-terminated UChar array which lives in
jpayne@69 144 * an internal buffer area, typically a memory mapped/DLL file. The
jpayne@69 145 * caller must NOT delete this pointer. If the call is unsuccessful
jpayne@69 146 * for any reason, then s is returned. This includes the situation in
jpayne@69 147 * which ec indicates a failing error code upon entry to this
jpayne@69 148 * function.
jpayne@69 149 *
jpayne@69 150 * @stable ICU 2.6
jpayne@69 151 */
jpayne@69 152 U_STABLE const UChar* U_EXPORT2
jpayne@69 153 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,
jpayne@69 154 const UChar* s,
jpayne@69 155 int32_t* len, UErrorCode* ec);
jpayne@69 156
jpayne@69 157 U_CDECL_END
jpayne@69 158
jpayne@69 159 #endif /*UCAT_H*/
jpayne@69 160 /*eof*/