/src/icu/source/common/unicode/locdspnm.h

Source (jump to first uncovered line)
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
******************************************************************************
* Copyright (C) 2010-2016, International Business Machines Corporation and
* others. All Rights Reserved.
******************************************************************************
*/

#ifndef LOCDSPNM_H
#define LOCDSPNM_H

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

/**
 * \file
 * \brief C++ API: Provides display names of Locale and its components.
 */

#if !UCONFIG_NO_FORMATTING

#include "unicode/locid.h"
#include "unicode/strenum.h"
#include "unicode/uscript.h"
#include "unicode/uldnames.h"
#include "unicode/udisplaycontext.h"

U_NAMESPACE_BEGIN

/**
 * Returns display names of Locales and components of Locales. For
 * more information on language, script, region, variant, key, and
 * values, see Locale.
 * @stable ICU 4.4
 */
class U_COMMON_API LocaleDisplayNames : public UObject {
public:
    /**
     * Destructor.
     * @stable ICU 4.4
     */
    virtual ~LocaleDisplayNames();

    /**
     * Convenience overload of
     * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
     * that specifies STANDARD dialect handling.
     * @param locale the display locale
     * @return a LocaleDisplayNames instance
     * @stable ICU 4.4
     */
    inline static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);

    /**
     * Returns an instance of LocaleDisplayNames that returns names
     * formatted for the provided locale, using the provided
     * dialectHandling.
     *
     * @param locale the display locale
     * @param dialectHandling how to select names for locales
     * @return a LocaleDisplayNames instance
     * @stable ICU 4.4
     */
    static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
                            UDialectHandling dialectHandling);

    /**
     * Returns an instance of LocaleDisplayNames that returns names formatted
     * for the provided locale, using the provided UDisplayContext settings.
     *
     * @param locale the display locale
     * @param contexts List of one or more context settings (e.g. for dialect
     *               handling, capitalization, etc.
     * @param length Number of items in the contexts list
     * @return a LocaleDisplayNames instance
     * @stable ICU 51
     */
    static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
                            UDisplayContext *contexts, int32_t length);

    // getters for state
    /**
     * Returns the locale used to determine the display names. This is
     * not necessarily the same locale passed to {@link #createInstance}.
     * @return the display locale
     * @stable ICU 4.4
     */
    virtual const Locale& getLocale() const = 0;

    /**
     * Returns the dialect handling used in the display names.
     * @return the dialect handling enum
     * @stable ICU 4.4
     */
    virtual UDialectHandling getDialectHandling() const = 0;

    /**
     * Returns the UDisplayContext value for the specified UDisplayContextType.
     * @param type the UDisplayContextType whose value to return
     * @return the UDisplayContext for the specified type.
     * @stable ICU 51
     */
    virtual UDisplayContext getContext(UDisplayContextType type) const = 0;

    // names for entire locales
    /**
     * Returns the display name of the provided locale.
     * @param locale the locale whose display name to return
     * @param result receives the locale's display name
     * @return the display name of the provided locale
     * @stable ICU 4.4
     */
    virtual UnicodeString& localeDisplayName(const Locale& locale,
                         UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided locale id.
     * @param localeId the id of the locale whose display name to return
     * @param result receives the locale's display name
     * @return the display name of the provided locale
     * @stable ICU 4.4
     */
    virtual UnicodeString& localeDisplayName(const char* localeId,
                         UnicodeString& result) const = 0;

    // names for components of a locale id
    /**
     * Returns the display name of the provided language code.
     * @param lang the language code
     * @param result receives the language code's display name
     * @return the display name of the provided language code
     * @stable ICU 4.4
     */
    virtual UnicodeString& languageDisplayName(const char* lang,
                           UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided script code.
     * @param script the script code
     * @param result receives the script code's display name
     * @return the display name of the provided script code
     * @stable ICU 4.4
     */
    virtual UnicodeString& scriptDisplayName(const char* script,
                         UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided script code.
     * @param scriptCode the script code number
     * @param result receives the script code's display name
     * @return the display name of the provided script code
     * @stable ICU 4.4
     */
    virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
                         UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided region code.
     * @param region the region code
     * @param result receives the region code's display name
     * @return the display name of the provided region code
     * @stable ICU 4.4
     */
    virtual UnicodeString& regionDisplayName(const char* region,
                         UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided variant.
     * @param variant the variant string
     * @param result receives the variant's display name
     * @return the display name of the provided variant
     * @stable ICU 4.4
     */
    virtual UnicodeString& variantDisplayName(const char* variant,
                          UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided locale key.
     * @param key the locale key name
     * @param result receives the locale key's display name
     * @return the display name of the provided locale key
     * @stable ICU 4.4
     */
    virtual UnicodeString& keyDisplayName(const char* key,
                      UnicodeString& result) const = 0;

    /**
     * Returns the display name of the provided value (used with the provided key).
     * @param key the locale key name
     * @param value the locale key's value
     * @param result receives the value's display name
     * @return the display name of the provided value
     * @stable ICU 4.4
     */
    virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
                           UnicodeString& result) const = 0;
};

inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
  return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
}

U_NAMESPACE_END

#endif

#endif /* U_SHOW_CPLUSPLUS_API */

#endif

Coverage Report

Created: 2025-01-28 06:38

Line	Count	Source (jump to first uncovered line)
1		// © 2016 and later: Unicode, Inc. and others.
2		// License & terms of use: http://www.unicode.org/copyright.html
3		/*
4		******************************************************************************
5		* Copyright (C) 2010-2016, International Business Machines Corporation and
6		* others. All Rights Reserved.
7		******************************************************************************
8		*/
9
10		#ifndef LOCDSPNM_H
11		#define LOCDSPNM_H
12
13		#include "unicode/utypes.h"
14
15		#if U_SHOW_CPLUSPLUS_API
16
17		/**
18		* \file
19		* \brief C++ API: Provides display names of Locale and its components.
20		*/
21
22		#if !UCONFIG_NO_FORMATTING
23
24		#include "unicode/locid.h"
25		#include "unicode/strenum.h"
26		#include "unicode/uscript.h"
27		#include "unicode/uldnames.h"
28		#include "unicode/udisplaycontext.h"
29
30		U_NAMESPACE_BEGIN
31
32		/**
33		* Returns display names of Locales and components of Locales. For
34		* more information on language, script, region, variant, key, and
35		* values, see Locale.
36		* @stable ICU 4.4
37		*/
38		class U_COMMON_API LocaleDisplayNames : public UObject {
39		public:
40		/**
41		* Destructor.
42		* @stable ICU 4.4
43		*/
44		virtual ~LocaleDisplayNames();
45
46		/**
47		* Convenience overload of
48		* {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
49		* that specifies STANDARD dialect handling.
50		* @param locale the display locale
51		* @return a LocaleDisplayNames instance
52		* @stable ICU 4.4
53		*/
54		inline static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
55
56		/**
57		* Returns an instance of LocaleDisplayNames that returns names
58		* formatted for the provided locale, using the provided
59		* dialectHandling.
60		*
61		* @param locale the display locale
62		* @param dialectHandling how to select names for locales
63		* @return a LocaleDisplayNames instance
64		* @stable ICU 4.4
65		*/
66		static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
67		UDialectHandling dialectHandling);
68
69		/**
70		* Returns an instance of LocaleDisplayNames that returns names formatted
71		* for the provided locale, using the provided UDisplayContext settings.
72		*
73		* @param locale the display locale
74		* @param contexts List of one or more context settings (e.g. for dialect
75		* handling, capitalization, etc.
76		* @param length Number of items in the contexts list
77		* @return a LocaleDisplayNames instance
78		* @stable ICU 51
79		*/
80		static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
81		UDisplayContext *contexts, int32_t length);
82
83		// getters for state
84		/**
85		* Returns the locale used to determine the display names. This is
86		* not necessarily the same locale passed to {@link #createInstance}.
87		* @return the display locale
88		* @stable ICU 4.4
89		*/
90		virtual const Locale& getLocale() const = 0;
91
92		/**
93		* Returns the dialect handling used in the display names.
94		* @return the dialect handling enum
95		* @stable ICU 4.4
96		*/
97		virtual UDialectHandling getDialectHandling() const = 0;
98
99		/**
100		* Returns the UDisplayContext value for the specified UDisplayContextType.
101		* @param type the UDisplayContextType whose value to return
102		* @return the UDisplayContext for the specified type.
103		* @stable ICU 51
104		*/
105		virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
106
107		// names for entire locales
108		/**
109		* Returns the display name of the provided locale.
110		* @param locale the locale whose display name to return
111		* @param result receives the locale's display name
112		* @return the display name of the provided locale
113		* @stable ICU 4.4
114		*/
115		virtual UnicodeString& localeDisplayName(const Locale& locale,
116		UnicodeString& result) const = 0;
117
118		/**
119		* Returns the display name of the provided locale id.
120		* @param localeId the id of the locale whose display name to return
121		* @param result receives the locale's display name
122		* @return the display name of the provided locale
123		* @stable ICU 4.4
124		*/
125		virtual UnicodeString& localeDisplayName(const char* localeId,
126		UnicodeString& result) const = 0;
127
128		// names for components of a locale id
129		/**
130		* Returns the display name of the provided language code.
131		* @param lang the language code
132		* @param result receives the language code's display name
133		* @return the display name of the provided language code
134		* @stable ICU 4.4
135		*/
136		virtual UnicodeString& languageDisplayName(const char* lang,
137		UnicodeString& result) const = 0;
138
139		/**
140		* Returns the display name of the provided script code.
141		* @param script the script code
142		* @param result receives the script code's display name
143		* @return the display name of the provided script code
144		* @stable ICU 4.4
145		*/
146		virtual UnicodeString& scriptDisplayName(const char* script,
147		UnicodeString& result) const = 0;
148
149		/**
150		* Returns the display name of the provided script code.
151		* @param scriptCode the script code number
152		* @param result receives the script code's display name
153		* @return the display name of the provided script code
154		* @stable ICU 4.4
155		*/
156		virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
157		UnicodeString& result) const = 0;
158
159		/**
160		* Returns the display name of the provided region code.
161		* @param region the region code
162		* @param result receives the region code's display name
163		* @return the display name of the provided region code
164		* @stable ICU 4.4
165		*/
166		virtual UnicodeString& regionDisplayName(const char* region,
167		UnicodeString& result) const = 0;
168
169		/**
170		* Returns the display name of the provided variant.
171		* @param variant the variant string
172		* @param result receives the variant's display name
173		* @return the display name of the provided variant
174		* @stable ICU 4.4
175		*/
176		virtual UnicodeString& variantDisplayName(const char* variant,
177		UnicodeString& result) const = 0;
178
179		/**
180		* Returns the display name of the provided locale key.
181		* @param key the locale key name
182		* @param result receives the locale key's display name
183		* @return the display name of the provided locale key
184		* @stable ICU 4.4
185		*/
186		virtual UnicodeString& keyDisplayName(const char* key,
187		UnicodeString& result) const = 0;
188
189		/**
190		* Returns the display name of the provided value (used with the provided key).
191		* @param key the locale key name
192		* @param value the locale key's value
193		* @param result receives the value's display name
194		* @return the display name of the provided value
195		* @stable ICU 4.4
196		*/
197		virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
198		UnicodeString& result) const = 0;
199		};
200
201	0	inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
202	0	return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
203	0	}
204
205		U_NAMESPACE_END
206
207		#endif
208
209		#endif /* U_SHOW_CPLUSPLUS_API */
210
211		#endif