Skip to content

Commit

Permalink
docs: add number pipes
Browse files Browse the repository at this point in the history
  • Loading branch information
@jbogarthyde
jbogarthyde committed Jun 14, 2018
1 parent 5025ab4 commit 4b9b3c3
Showing 1 changed file with 74 additions and 41 deletions.
115 changes: 74 additions & 41 deletions packages/common/src/pipes/number_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* @ngModule CommonModule
* @description
*
* Uses the function {@link formatNumber} to format a number according to locale rules.
* Uses the function `formatNumber()` to transform a number into a string,
* formatted according to locale rules that determine group sizing and
* separator, decimal-point character, and other locale-specific
* configurations.
*
* Formats a number as text. Group sizing and separator and other locale-specific
* configurations are based on the locale.
* @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is US English.
*
* ### Example
*
* {@example common/pipes/ts/number_pipe.ts region='NumberPipe'}
* <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
*
*
*/
Expand All @@ -31,16 +34,18 @@ export class DecimalPipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private _locale: string) {}

/**
* @param value a number to be formatted.
* @param digitsInfo a `string` which has a following format: <br>
* @param value The number to be formatted.
* @param digitsInfo Decimal representation options, specified by a string
* in the following format:<br>
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`.
* - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to
* `0`.
* - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to
* `3`.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
* - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* Default is `1`.
* - `minFractionDigits`: The minimum number of digits after the decimal point.
* Default is `0`.
* - `maxFractionDigits`: The maximum number of digits after the decimal point.
* Default is `3`.
* @param locale A locale code for the locale format rules to use. Default is the
* caller's `LOCALE_ID`.
*/
transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null;
Expand All @@ -60,12 +65,17 @@ export class DecimalPipe implements PipeTransform {
* @ngModule CommonModule
* @description
*
* Uses the function {@link formatPercent} to format a number as a percentage according
* to locale rules.
*
* ### Example
* Uses the function `formatPercent()` to transform a number to a percentage
* string, formatted according to locale rules that determine group sizing and
* separator, decimal-point character, and other locale-specific
* configurations.
*
* {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'}
* @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is US English.
*
* <code-example path="common/pipes/ts/percent_pipe.ts" region='PercentPipe'></code-example>
*
*
*/
Expand All @@ -75,10 +85,19 @@ export class PercentPipe implements PipeTransform {

/**
*
* @param value a number to be formatted as a percentage.
* @param digitsInfo see {@link DecimalPipe} for more details.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
* @param value The number to be format as a percentage.
* @param digitsInfo Decimal representation options, specified by a string
* in the following format:<br>
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* Default is `1`.
* - `minFractionDigits`: The minimum number of digits after the decimal point.
* Default is `0`.
* - `maxFractionDigits`: The maximum number of digits after the decimal point.
* Default is `3`.
* @param locale A locale code for the locale format rules to use. Default is the
* caller's `LOCALE_ID`.
*
*/
transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null;
Expand All @@ -98,12 +117,17 @@ export class PercentPipe implements PipeTransform {
* @ngModule CommonModule
* @description
*
* Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a
* number as currency using locale rules.
* Uses the functions `getCurrencySymbol()` and `formatCurrency()` to transform
* a number to a currency string, formatted according to locale rules
* that determine group sizing and separator, decimal-point character,
* and other locale-specific configurations.
*
* ### Example
* @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is US English.
*
* {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'}
* <code-example path="common/pipes/ts/currency_pipe.ts" region='CurrencyPipe'></code-example>
*
*
*/
Expand All @@ -113,20 +137,29 @@ export class CurrencyPipe implements PipeTransform {

/**
*
* @param value a number to be formatted as currency.
* @param value The number to be formatted as currency.
* @param currencyCodeis the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code,
* such as `USD` for the US dollar and `EUR` for the euro.
* @param display indicates whether to show the currency symbol, the code or a custom value:
* - `code`: use code (e.g. `USD`).
* - `symbol`(default): use symbol (e.g. `$`).
* - `symbol-narrow`: some countries have two symbols for their currency, one regular and one
* narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`).
* - `string`: use this value instead of a code or a symbol.
* - boolean (deprecated from v5): `true` for symbol and false for `code`.
* If there is no narrow symbol for the chosen currency, the regular symbol will be used.
* @param digitsInfo see {@link DecimalPipe} for more details.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
* @param display How to indicate the currency. One of the following:
* - `code`: Show the code (such as `USD`).
* - `symbol`(default): Show the symbol (such as `$`).
* - `symbol-narrow`: Use the narrow symbol for locales that have two symbols for their currency.
* For example, the Canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`. If the
* locale has no narrow symbol, uses the standard symbol for the locale.
* - String: Use the given string value instead of a code or a symbol.
* - Boolean (deprecated from v5): `true` for symbol and false for `code`.
*
* @param digitsInfo Decimal representation options, specified by a string
* in the following format:<br>
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* Default is `1`.
* - `minFractionDigits`: The minimum number of digits after the decimal point.
* Default is `0`.
* - `maxFractionDigits`: The maximum number of digits after the decimal point.
* Default is `3`.
* @param locale A locale code for the locale format rules to use. Default is the
* caller's `LOCALE_ID`.
*/
transform(
value: any, currencyCode?: string,
Expand Down Expand Up @@ -167,7 +200,7 @@ function isEmpty(value: any): boolean {
}

/**
* Transforms a string into a number (if needed)
* Transforms a string into a number (if needed).
*/
function strToNumber(value: number | string): number {
// Convert strings to numbers
Expand Down

0 comments on commit 4b9b3c3

Please sign in to comment.