honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: api doc for i18n (#29289) 

PR Close #29289
This commit is contained in:
Judy Bogart 2019-02-27 12:40:52 -08:00 committed by Jason Aden
parent eb0e29b269
commit 333bfa0ffb
4 changed files with 339 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
packages/common/src/i18n/format_date.ts
View File

@ -46,17 +46,18 @@ enum TranslationType {
*
* Formats a date according to locale rules.
*
* Where:
* - `value` is a Date, a number (milliseconds since UTC epoch) or an ISO string
* (https://www.w3.org/TR/NOTE-datetime).
* - `format` indicates which date/time components to include. See {@link DatePipe} for more
* details.
* - `locale` is a `string` defining the locale to use.
* - `timezone` to be used for formatting. It understands UTC/GMT and the continental US time zone
* abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`).
* If not specified, host system settings are used.
* @param value The date to format, as a number (milliseconds since UTC epoch)
* or an [ISO date-time string](https://www.w3.org/TR/NOTE-datetime).
* @param format The date-time components to include. See `DatePipe` for details.
* @param locale A locale code for the locale format rules to use.
* @param timezone The time zone. A time zone offset from GMT (such as `'+0430'`),
* or a standard UTC/GMT or continental US time zone abbreviation.
* If not specified, uses host system settings.
*
* See {@link DatePipe} for more details.
* @returns The formatted date string.
*
* @see `DatePipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/

53
packages/common/src/i18n/format_number.ts
View File

@ -19,7 +19,7 @@ const CURRENCY_CHAR = '¤';
const PERCENT_CHAR = '%';
/**
* Transforms a number to a locale string based on a style and a format
* Transforms a number to a locale string based on a style and a format.
*/
function formatNumberToLocaleString(
value: number, pattern: ParsedNumberFormat, locale: string, groupSymbol: NumberSymbol,
@ -128,15 +128,21 @@ function formatNumberToLocaleString(
*
* Formats a number as currency using locale rules.
*
* Use `currency` to format a number as currency.
* @param value The number to format.
* @param locale A locale code for the locale format rules to use.
* @param currency A string containing the currency symbol or its name,
* such as "$" or "Canadian Dollar". Used in output string, but does not affect the operation
* of the function.
* @param currencyCode The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
* currency code to use in the result string, such as `USD` for the US dollar and `EUR` for the euro.
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* Where:
* - `value` is a number.
* - `locale` is a `string` defining the locale to use.
* - `currency` is the string that represents the currency, it can be its symbol or its name.
* - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such
* as `USD` for the US dollar and `EUR` for the euro.
* - `digitInfo` See {@link DecimalPipe} for more details.
* @returns The formatted currency value.
*
* @see `formatNumber()`
* @see `DecimalPipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -163,12 +169,18 @@ export function formatCurrency(
*
* Formats a number as a percentage according to locale rules.
*
* Where:
* - `value` is a number.
* - `locale` is a `string` defining the locale to use.
* - `digitInfo` See {@link DecimalPipe} for more details.
* @param value The number to format.
* @param locale A locale code for the locale format rules to use.
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* @returns The formatted percentage value.
*
* @see `formatNumber()`
* @see `DecimalPipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi
*
*/
export function formatPercent(value: number, locale: string, digitsInfo?: string): string {
const format = getLocaleNumberFormat(locale, NumberFormatStyle.Percent);
@ -183,13 +195,16 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string
* @ngModule CommonModule
* @description
*
* Formats a number as text. Group sizing and separator and other locale-specific
* configurations are based on the locale.
* Formats a number as text, with group sizing, separator, and other
* parameters based on the locale.
*
* Where:
* - `value` is a number.
* - `locale` is a `string` defining the locale to use.
* - `digitInfo` See {@link DecimalPipe} for more details.
* @param value The number to format.
* @param locale A locale code for the locale format rules to use.
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* @returns The formatted text string.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/

442
packages/common/src/i18n/locale_data_api.ts
View File

@ -11,8 +11,9 @@ import {LOCALE_DATA, LocaleDataIndex, ExtraLocaleDataIndex, CurrencyIndex} from
import {CURRENCIES_EN, CurrenciesSymbols} from './currencies';
/**
* The different format styles that can be used to represent numbers.
* Used by the function {@link getLocaleNumberFormat}.
* Format styles that can be used to represent numbers.
* @see `getLocaleNumberFormat()`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -23,7 +24,14 @@ export enum NumberFormatStyle {
Scientific
}
/** @publicApi */
/**
* Plurality cases used for translating plurals to different languages.
*
* @see `NgPlural`
* @see `NgPluralCase`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi */
export enum Plural {
Zero = 0,
One = 1,
@ -34,11 +42,11 @@ export enum Plural {
}
/**
* Some languages use two different forms of strings (standalone and format) depending on the
* context.
* Typically the standalone version is the nominative form of the word, and the format version is in
* the genitive.
* See [the CLDR website](http://cldr.unicode.org/translation/date-time) for more information.
* Context-dependant translation forms for strings.
* Typically the standalone version is for the nominative form of the word,
* and the format version is used for the genitive case.
* @see [CLDR website](http://cldr.unicode.org/translation/date-time#TOC-Stand-Alone-vs.-Format-Styles)
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -48,85 +56,143 @@ export enum FormStyle {
}
/**
* Multiple widths are available for translations: narrow (1 character), abbreviated (3 characters),
* wide (full length), and short (2 characters, only for days).
*
* For example the day `Sunday` will be:
* - Narrow: `S`
* - Short: `Su`
* - Abbreviated: `Sun`
* - Wide: `Sunday`
* String widths available for translations.
* The specific character widths are locale-specific.
* Examples are given for the word "Sunday" in English.
*
* @publicApi
*/
export enum TranslationWidth {
/** 1 character for `en-US`. For example: 'S' */
Narrow,
/** 3 characters for `en-US`. For example: 'Sun' */
Abbreviated,
/** Full length for `en-US`. For example: "Sunday" */
Wide,
/** 2 characters for `en-US`, For example: "Su" */
Short
}
/**
* Multiple widths are available for formats: short (minimal amount of data), medium (small amount
* of data), long (complete amount of data), full (complete amount of data and extra information).
*
* For example the date-time formats for the english locale will be:
* - `'short'`: `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`)
* - `'medium'`: `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`)
* - `'long'`: `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`)
* - `'full'`: `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`)
* String widths available for date-time formats.
* The specific character widths are locale-specific.
* Examples are given for `en-US`.
*
* @see `getLocaleDateFormat()`
* @see `getLocaleTimeFormat()``
* @see `getLocaleDateTimeFormat()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi
*/
export enum FormatWidth {
/**
* For `en-US`, 'M/d/yy, h:mm a'`
* (Example: `6/15/15, 9:03 AM`)
*/
Short,
/**
* For `en-US`, `'MMM d, y, h:mm:ss a'`
* (Example: `Jun 15, 2015, 9:03:01 AM`)
*/
Medium,
/**
* For `en-US`, `'MMMM d, y, h:mm:ss a z'`
* (Example: `June 15, 2015 at 9:03:01 AM GMT+1`)
*/
Long,
/**
* For `en-US`, `'EEEE, MMMM d, y, h:mm:ss a zzzz'`
* (Example: `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00`)
*/
Full
}
/**
* Number symbol that can be used to replace placeholders in number patterns.
* The placeholders are based on english values:
* Symbols that can be used to replace placeholders in number patterns.
* Examples are based on `en-US` values.
*
* | Name | Example for en-US | Meaning |
* |------------------------|-------------------|---------------------------------------------|
* | decimal | 2,345`.`67 | decimal separator |
* | group | 2`,`345.67 | grouping separator, typically for thousands |
* | plusSign | `+`23 | the plus sign used with numbers |
* | minusSign | `-`23 | the minus sign used with numbers |
* | percentSign | 23.4`%` | the percent sign (out of 100) |
* | perMille | 234`‰` | the permille sign (out of 1000) |
* | exponential | 1.2`E`3 | used in computers for 1.2×10³. |
* | superscriptingExponent | 1.2`×`103 | human-readable format of exponential |
* | infinity | `∞` | used in +∞ and -∞. |
* | nan | `NaN` | "not a number". |
* | timeSeparator | 10`:`52 | symbol used between time units |
* | currencyDecimal | $2,345`.`67 | decimal separator, fallback to "decimal" |
* | currencyGroup | $2`,`345.67 | grouping separator, fallback to "group" |
* @see `getLocaleNumberSymbol()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
export enum NumberSymbol {
/**
* Decimal separator.
* For `en-US`, the dot character.
* Example : 2,345`.`67
*/
Decimal,
/**
* Grouping separator, typically for thousands.
* For `en-US`, the comma character.
* Example: 2`,`345.67
*/
Group,
/**
* List-item separator.
* Example: "one, two, and three"
*/
List,
/**
* Sign for percentage (out of 100).
* Example: 23.4%
*/
PercentSign,
/**
* Sign for positive numbers.
* Example: +23
*/
PlusSign,
/**
* Sign for negative numbers.
* Example: -23
*/
MinusSign,
/**
* Computer notation for exponential value (n times a power of 10).
* Example: 1.2E3
*/
Exponential,
/**
* Human-readable format of exponential.
* Example: 1.2x103
*/
SuperscriptingExponent,
/**
* Sign for permille (out of 1000).
* Example: 23.4‰
*/
PerMille,
/**
* Infinity, can be used with plus and minus.
* Example: ∞, +∞, -∞
*/
Infinity,
/**
* Not a number.
* Example: NaN
*/
NaN,
/**
* Symbol used between time units.
* Example: 10:52
*/
TimeSeparator,
/**
* Decimal separator for currency values (fallback to `Decimal`).
* Example: $2,345.67
*/
CurrencyDecimal,
/**
* Group separator for currency values (fallback to `Group`).
* Example: $2,345.67
*/
CurrencyGroup
}
/**
* The value for each day of the week, based on the en-US locale
* The value for each day of the week, based on the `en-US` locale
*
* @publicApi
*/
@ -141,7 +207,11 @@ export enum WeekDay {
}
/**
* The locale id for the chosen locale (e.g `en-GB`).
* Retrieves the locale ID from the currently loaded locale.
* The loaded locale could be, for example, a global one rather than a regional one.
* @param locale A locale code, such as `fr-FR`.
* @returns The locale code. For example, `fr`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -150,7 +220,13 @@ export function getLocaleId(locale: string): string {
}
/**
* Periods of the day (e.g. `[AM, PM]` for en-US).
* Retrieves day period strings for the given locale.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized period strings. For example, `[AM, PM]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -165,7 +241,14 @@ export function getLocaleDayPeriods(
}
/**
* Days of the week for the Gregorian calendar (e.g. `[Sunday, Monday, ... Saturday]` for en-US).
* Retrieves days of the week for the given locale, using the Gregorian calendar.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized name strings.
* For example,`[Sunday, Monday, ... Saturday]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -179,7 +262,14 @@ export function getLocaleDayNames(
}
/**
* Months of the year for the Gregorian calendar (e.g. `[January, February, ...]` for en-US).
* Retrieves months of the year for the given locale, using the Gregorian calendar.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized name strings.
* For example, `[January, February, ...]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -193,7 +283,14 @@ export function getLocaleMonthNames(
}
/**
* Eras for the Gregorian calendar (e.g. AD/BC).
* Retrieves Gregorian-calendar eras for the given locale.
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized era strings.
* For example, `[AD, BC]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -204,8 +301,13 @@ export function getLocaleEraNames(locale: string, width: TranslationWidth): [str
}
/**
* First day of the week for this locale, based on english days (Sunday = 0, Monday = 1, ...).
* For example in french the value would be 1 because the first day of the week is Monday.
* Retrieves the first day of the week for the given locale.
*
* @param locale A locale code for the locale format rules to use.
* @returns A day index number, using the 0-based week-day index for `en-US`
* (Sunday = 0, Monday = 1, ...).
* For example, for `fr-FR`, returns 1 to indicate that the first day is Monday.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -215,9 +317,11 @@ export function getLocaleFirstDayOfWeek(locale: string): WeekDay {
}
/**
* Range of days in the week that represent the week-end for this locale, based on english days
* (Sunday = 0, Monday = 1, ...).
* For example in english the value would be [6,0] for Saturday to Sunday.
* Range of week days that are considered the week-end for the given locale.
*
* @param locale A locale code for the locale format rules to use.
* @returns The range of day values, `[startDay, endDay]`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -227,27 +331,13 @@ export function getLocaleWeekEndRange(locale: string): [WeekDay, WeekDay] {
}
/**
* Date format that depends on the locale.
* Retrieves a localized date-value formating string.
*
* There are four basic date formats:
* - `full` should contain long-weekday (EEEE), year (y), long-month (MMMM), day (d).
*
* For example, English uses `EEEE, MMMM d, y`, corresponding to a date like
* "Tuesday, September 14, 1999".
*
* - `long` should contain year, long-month, day.
*
* For example, `MMMM d, y`, corresponding to a date like "September 14, 1999".
*
* - `medium` should contain year, abbreviated-month (MMM), day.
*
* For example, `MMM d, y`, corresponding to a date like "Sep 14, 1999".
* For languages that do not use abbreviated months, use the numeric month (MM/M). For example,
* `y/MM/dd`, corresponding to a date like "1999/09/14".
*
* - `short` should contain year, numeric-month (MM/M), and day.
*
* For example, `M/d/yy`, corresponding to a date like "9/14/99".
* @param locale A locale code for the locale format rules to use.
* @param width The format type.
* @returns The localized formating string.
* @see `FormatWidth`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -257,23 +347,14 @@ export function getLocaleDateFormat(locale: string, width: FormatWidth): string
}
/**
* Time format that depends on the locale.
*
* The standard formats include four basic time formats:
* - `full` should contain hour (h/H), minute (mm), second (ss), and zone (zzzz).
* - `long` should contain hour, minute, second, and zone (z)
* - `medium` should contain hour, minute, second.
* - `short` should contain hour, minute.
*
* Note: The patterns depend on whether the main country using your language uses 12-hour time or
* not:
* - For 12-hour time, use a pattern like `hh:mm a` using h to mean a 12-hour clock cycle running
* 1 through 12 (midnight plus 1 minute is 12:01), or using K to mean a 12-hour clock cycle
* running 0 through 11 (midnight plus 1 minute is 0:01).
* - For 24-hour time, use a pattern like `HH:mm` using H to mean a 24-hour clock cycle running 0
* through 23 (midnight plus 1 minute is 0:01), or using k to mean a 24-hour clock cycle running
* 1 through 24 (midnight plus 1 minute is 24:01).
* Retrieves a localized time-value formatting string.
*
* @param locale A locale code for the locale format rules to use.
* @param width The format type.
* @returns The localized formatting string.
* @see `FormatWidth`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi
*/
export function getLocaleTimeFormat(locale: string, width: FormatWidth): string {
@ -282,27 +363,13 @@ export function getLocaleTimeFormat(locale: string, width: FormatWidth): string
}
/**
* Date-time format that depends on the locale.
* Retrieves a localized date-time formatting string.
*
* The date-time pattern shows how to combine separate patterns for date (represented by {1})
* and time (represented by {0}) into a single pattern. It usually doesn't need to be changed.
* What you want to pay attention to are:
* - possibly removing a space for languages that don't use it, such as many East Asian languages
* - possibly adding a comma, other punctuation, or a combining word
*
* For example:
* - English uses `{1} 'at' {0}` or `{1}, {0}` (depending on date style), while Japanese uses
* `{1}{0}`.
* - An English formatted date-time using the combining pattern `{1}, {0}` could be
* `Dec 10, 2010, 3:59:49 PM`. Notice the comma and space between the date portion and the time
* portion.
*
* There are four formats (`full`, `long`, `medium`, `short`); the determination of which to use
* is normally based on the date style. For example, if the date has a full month and weekday
* name, the full combining pattern will be used to combine that with a time. If the date has
* numeric month, the short version of the combining pattern will be used to combine that with a
* time. English uses `{1} 'at' {0}` for full and long styles, and `{1}, {0}` for medium and short
* styles.
* @param locale A locale code for the locale format rules to use.
* @param width The format type.
* @returns The localized formatting string.
* @see `FormatWidth`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -313,8 +380,12 @@ export function getLocaleDateTimeFormat(locale: string, width: FormatWidth): str
}
/**
* Number symbol that can be used to replace placeholders in number formats.
* See {@link NumberSymbol} for more information.
* Retrieves a localized number symbol that can be used to replace placeholders in number formats.
* @param locale The locale code.
* @param symbol The symbol to localize.
* @returns The character for the localized symbol.
* @see `NumberSymbol`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -332,17 +403,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str
}
/**
* Number format that depends on the locale.
* Retrieves a number format for a given locale.
*
* Numbers are formatted using patterns, like `#,###.00`. For example, the pattern `#,###.00`
* when used to format the number 12345.678 could result in "12'345,67". That would happen if the
* when used to format the number 12345.678 could result in "12'345,678". That would happen if the
* grouping separator for your language is an apostrophe, and the decimal separator is a comma.
*
* <b>Important:</b> The characters `.` `,` `0` `#` (and others below) are special placeholders;
* they stand for the decimal separator, and so on, and are NOT real characters.
* You must NOT "translate" the placeholders; for example, don't change `.` to `,` even though in
* <b>Important:</b> The characters `.` `,` `0` `#` (and others below) are special placeholders
* that stand for the decimal separator, and so on, and are NOT real characters.
* You must NOT "translate" the placeholders. For example, don't change `.` to `,` even though in
* your language the decimal point is written with a comma. The symbols should be replaced by the
* local equivalents, using the Number Symbols for your language.
* local equivalents, using the appropriate `NumberSymbol` for your language.
*
* Here are the special characters used in number patterns:
*
@ -352,13 +423,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str
* | , | Replaced by the "grouping" (thousands) separator. |
* | 0 | Replaced by a digit (or zero if there aren't enough digits). |
* | # | Replaced by a digit (or nothing if there aren't enough). |
* | ¤ | This will be replaced by a currency symbol, such as $ or USD. |
* | % | This marks a percent format. The % symbol may change position, but must be retained. |
* | E | This marks a scientific format. The E symbol may change position, but must be retained. |
* | ¤ | Replaced by a currency symbol, such as $ or USD. |
* | % | Marks a percent format. The % symbol may change position, but must be retained. |
* | E | Marks a scientific format. The E symbol may change position, but must be retained. |
* | ' | Special characters used as literal characters are quoted with ASCII single quotes. |
*
* You can find more information
* [on the CLDR website](http://cldr.unicode.org/translation/number-patterns)
* @param locale A locale code for the locale format rules to use.
* @param type The type of numeric value to be formatted (such as `Decimal` or `Currency`.)
* @returns The localized format string.
* @see `NumberFormatStyle`
* @see [CLDR website](http://cldr.unicode.org/translation/number-patterns)
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -368,9 +443,13 @@ export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle):
}
/**
* The symbol used to represent the currency for the main country using this locale (e.g. $ for
* the locale en-US).
* The symbol will be `null` if the main country cannot be determined.
* Retrieves the symbol used to represent the currency for the main country
* corresponding to a given locale. For example, '$' for `en-US`.
*
* @param locale A locale code for the locale format rules to use.
* @returns The localized symbol character,
* or `null` if the main country cannot be determined.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -380,9 +459,12 @@ export function getLocaleCurrencySymbol(locale: string): string|null {
}
/**
* The name of the currency for the main country using this locale (e.g. 'US Dollar' for the locale
* en-US).
* The name will be `null` if the main country cannot be determined.
* Retrieves the name of the currency for the main country corresponding
* to a given locale. For example, 'US Dollar' for `en-US`.
* @param locale A locale code for the locale format rules to use.
* @returns The currency name,
* or `null` if the main country cannot be determined.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -392,7 +474,10 @@ export function getLocaleCurrencyName(locale: string): string|null {
}
/**
* Returns the currency values for the locale
* Retrieves the currency values for a given locale.
* @param locale A locale code for the locale format rules to use.
* @returns The currency values.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*/
function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols} {
const data = findLocaleData(locale);
@ -400,8 +485,12 @@ function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols
}
/**
* The locale plural function used by ICU expressions to determine the plural case to use.
* See {@link NgPlural} for more information.
* Retrieves the plural function used by ICU expressions to determine the plural case to use
* for a given locale.
* @param locale A locale code for the locale format rules to use.
* @returns The plural function for the locale.
* @see `NgPlural`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -418,17 +507,24 @@ function checkFullData(data: any) {
}
/**
* Rules used to determine which day period to use (See `dayPeriods` below).
* The rules can either be an array or a single value. If it's an array, consider it as "from"
* and "to". If it's a single value then it means that the period is only valid at this exact
* value.
* There is always the same number of rules as the number of day periods, which means that the
* first rule is applied to the first day period and so on.
* You should fallback to AM/PM when there are no rules available.
* Retrieves locale-specific rules used to determine which day period to use
* when more than one period is defined for a locale.
*
* Note: this is only available if you load the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale
* data.
* There is a rule for each defined day period. The
* first rule is applied to the first day period and so on.
* Fall back to AM/PM when no rules are available.
*
* A rule can specify a period as time range, or as a single time value.
*
* This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes).
*
* @param locale A locale code for the locale format rules to use.
* @returns The rules for the locale, a single time value or array of *from-time, to-time*,
* or null if no periods are available.
*
* @see `getLocaleExtraDayPeriods()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -445,15 +541,19 @@ export function getLocaleExtraDayPeriodRules(locale: string): (Time | [Time, Tim
}
/**
* Day Periods indicate roughly how the day is broken up in different languages (e.g. morning,
* noon, afternoon, midnight, ...).
* You should use the function {@link getLocaleExtraDayPeriodRules} to determine which period to
* use.
* You should fallback to AM/PM when there are no day periods available.
* Retrieves locale-specific day periods, which indicate roughly how a day is broken up
* in different languages.
* For example, for `en-US`, periods are morning, noon, afternoon, evening, and midnight.
*
* Note: this is only available if you load the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale
* data.
* This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes).
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns The translated day-period strings.
* @see `getLocaleExtraDayPeriodRules()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -470,11 +570,15 @@ export function getLocaleExtraDayPeriods(
}
/**
* Returns the first value that is defined in an array, going backwards.
* Retrieves the first value that is defined in an array, going backwards from an index position.
*
* To avoid repeating the same data (e.g. when "format" and "standalone" are the same) we only
* add the first one to the locale data arrays, the other ones are only defined when different.
* We use this function to retrieve the first defined value.
* To avoid repeating the same data (as when the "format" and "standalone" forms are the same)
* add the first value to the locale data arrays, and add other values only if they are different.
*
* @param data The data array to retrieve from.
* @param index A 0-based index into the array to start from.
* @returns The value immediately before the given index position.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -488,7 +592,7 @@ function getLastDefinedValue<T>(data: T[], index: number): T {
}
/**
* A representation of the time with hours and minutes
* Represents a time value with hours and minutes.
*
* @publicApi
*/
@ -498,7 +602,7 @@ export type Time = {
};
/**
* Extract the hours and minutes from a string like "15:45"
* Extracts the hours and minutes from a string like "15:45"
*/
function extractTime(time: string): Time {
const [h, m] = time.split(':');
@ -506,7 +610,11 @@ function extractTime(time: string): Time {
}
/**
* Finds the locale data for a locale id
* Finds the locale data for a given locale.
*
* @param locale The locale code.
* @returns The locale data.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -534,9 +642,17 @@ export function findLocaleData(locale: string): any {
}
/**
* Returns the currency symbol for a given currency code, or the code if no symbol available
* (e.g.: format narrow = $, format wide = US$, code = USD)
* If no locale is provided, it uses the locale "en" by default
* Retrieves the currency symbol for a given currency code.
*
* For example, for the default `en-US` locale, the code `USD` can
* be represented by the narrow symbol `$` or the wide symbol `US$`.
*
* @param code The currency code.
* @param format The format, `wide` or `narrow`.
* @param locale A locale code for the locale format rules to use.
*
* @returns The symbol, or the currency code if no symbol is available.0
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
@ -555,8 +671,12 @@ export function getCurrencySymbol(code: string, format: 'wide' | 'narrow', local
const DEFAULT_NB_OF_CURRENCY_DIGITS = 2;
/**
* Returns the number of decimal digits for the given currency.
* Its value depends upon the presence of cents in that particular currency.
* Reports the number of decimal digits for a given currency.
* The value depends upon the presence of cents in that particular currency.
*
* @param code The currency code.
* @returns The number of decimal digits, typically 0 or 2.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/

20
packages/core/src/di/injector_compatibility.ts
View File

@ -70,18 +70,24 @@ export function injectInjectorOnly<T>(
/**
* Injects a token from the currently active injector.
* Must be used in the context of a factory function such as one defined for an
* `InjectionToken`. Throws an error if not called from such a context.
*
* This function must be used in the context of a factory function such as one defined for an
* `InjectionToken`, and will throw an error if not called from such a context.
* Within such a factory function, using this function to request injection of a dependency
* is faster and more type-safe than providing an additional array of dependencies
* (as has been common with `useFactory` providers).
*
* @param token The injection token for the dependency to be injected.
* @param flags Optional flags that control how injection is executed.
* The flags correspond to injection strategies that can be specified with
* parameter decorators `@Host`, `@Self`, `@SkipSef`, and `@Optional`.
* @returns True if injection is successful, null otherwise.
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'}
*
* Within such a factory function `inject` is utilized to request injection of a dependency, instead
* of providing an additional array of dependencies as was common to do with `useFactory` providers.
* `inject` is faster and more type-safe.
* {@example core/di/ts/injector_spec.ts region='ShakableInjectionToken'}
*
* @publicApi
*/