Skip to content

Commit

Permalink
docs(common): move Pipe param docs to transform function (#23062)
Browse files Browse the repository at this point in the history 
PR Close #23062
  • Loading branch information
@petebacondarwin @IgorMinar
petebacondarwin authored and IgorMinar committed Apr 5, 2018
1 parent 079d8e5 commit cdd05bd
Show file tree
Hide file tree
Showing 5 changed files with 91 additions and 85 deletions.
48 changes: 24 additions & 24 deletions packages/common/src/pipes/date_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,30 +17,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
*
* Uses the function {@link formatDate} to format a date according to locale rules.
*
* Where:
* - `value` is a date object or 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. The format can be predefined as
* shown below (all examples are given for `en-US`) or custom as shown in the table.
* - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`).
* - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`).
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`).
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`).
* - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`).
* - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`).
* - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`).
* - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`).
* - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`).
* - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`).
* - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`).
* - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`).
* - `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, the local system timezone of the end-user's browser will be used.
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*
* The following tabled describes the formatting options.
*
* | Field Type | Format | Description | Example Value |
* |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------|
Expand Down Expand Up @@ -129,6 +106,29 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
export class DatePipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private locale: string) {}

/**
* @param value a date object or a number (milliseconds since UTC epoch) or an ISO string
* (https://www.w3.org/TR/NOTE-datetime).
* @param format indicates which date/time components to include. The format can be predefined as
* shown below (all examples are given for `en-US`) or custom as shown in the table.
* - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`).
* - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`).
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`).
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`).
* - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`).
* - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`).
* - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`).
* - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`).
* - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`).
* - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`).
* - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`).
* - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`).
* @param timezone to be used for formatting the time. It understands UTC/GMT and the continental US time zone
* abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`).
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*/
transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null {
if (value == null || value === '' || value !== value) return null;

Expand Down
14 changes: 7 additions & 7 deletions packages/common/src/pipes/i18n_plural_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,6 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
*
* Maps a value to a string that pluralizes the value according to locale rules.
*
* Where:
* - `expression` is a number.
* - `mapping` is an object that mimics the ICU format, see
* http://userguide.icu-project.org/formatparse/messages
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default)
*
* ## Example
*
* {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'}
Expand All @@ -35,6 +28,13 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
export class I18nPluralPipe implements PipeTransform {
constructor(private _localization: NgLocalization) {}

/**
* @param value the number to be formatted
* @param pluralMap an object that mimics the ICU format, see
* http://userguide.icu-project.org/formatparse/messages.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*/
transform(value: number, pluralMap: {[count: string]: string}, locale?: string): string {
if (value == null) return '';

Expand Down
15 changes: 9 additions & 6 deletions packages/common/src/pipes/i18n_select_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,22 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
*
* Generic selector that displays the string that matches the current value.
*
* Where `mapping` is an object that indicates the text that should be displayed
* for different values of the provided `expression`.
* If none of the keys of the mapping match the value of the `expression`, then the content
* of the `other` key is returned when present, otherwise an empty string is returned.
* If none of the keys of the `mapping` match the `value`, then the content
* of the `other` key is returned when present, otherwise an empty string is returned.
*
* ## Example
* ## Example
*
* {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'}
*
* @experimental
* @experimental
*/
@Pipe({name: 'i18nSelect', pure: true})
export class I18nSelectPipe implements PipeTransform {
/**
* @param value a string to be internationalized.
* @param mapping an object that indicates the text that should be displayed
* for different values of the provided `value`.
*/
transform(value: string|null|undefined, mapping: {[key: string]: string}): string {
if (value == null) return '';

Expand Down
66 changes: 34 additions & 32 deletions packages/common/src/pipes/number_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* Formats a number as text. Group sizing and separator and other locale-specific
* configurations are based on the locale.
*
* Where:
* - `value` is a number
* - `digitInfo` is a `string` which has a 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`.
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*
* ### Example
*
* {@example common/pipes/ts/number_pipe.ts region='NumberPipe'}
Expand All @@ -40,6 +30,16 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
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>
* <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).
*/
transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null;

Expand All @@ -61,12 +61,6 @@ export class DecimalPipe implements PipeTransform {
* Uses the function {@link formatPercent} to format a number as a percentage according
* to locale rules.
*
* Where:
* - `value` is a number.
* - `digitInfo` See {@link DecimalPipe} for more details.
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*
* ### Example
*
* {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'}
Expand All @@ -77,6 +71,13 @@ export class DecimalPipe implements PipeTransform {
export class PercentPipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private _locale: string) {}

/**
*
* @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).
*/
transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null;

Expand All @@ -98,22 +99,6 @@ export class PercentPipe implements PipeTransform {
* Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a
* number as currency using locale rules.
*
* Where:
* - `value` is a number.
* - `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.
* - `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.
* - `digitInfo` See {@link DecimalPipe} for more details.
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*
* ### Example
*
* {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'}
Expand All @@ -124,6 +109,23 @@ export class PercentPipe implements PipeTransform {
export class CurrencyPipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private _locale: string) {}

/**
*
* @param value a 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).
*/
transform(
value: any, currencyCode?: string,
display: 'code'|'symbol'|'symbol-narrow'|string|boolean = 'symbol', digitsInfo?: string,
Expand Down
33 changes: 17 additions & 16 deletions packages/common/src/pipes/slice_pipe.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,30 +13,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* @ngModule CommonModule
* @description
*
* Creates a new List or String containing a subset (slice) of the elements.
*
* Where the input expression is a `List` or `String`, and:
* - `start`: The starting index of the subset to return.
* - **a positive integer**: return the item at `start` index and all items after
* in the list or string expression.
* - **a negative integer**: return the item at `start` index from the end and all items after
* in the list or string expression.
* - **if positive and greater than the size of the expression**: return an empty list or string.
* - **if negative and greater than the size of the expression**: return entire list or string.
* - `end`: The ending index of the subset to return.
* - **omitted**: return all items until the end.
* - **if positive**: return all items before `end` index of the list or string.
* - **if negative**: return all items before `end` index from the end of the list or string.
* Creates a new `Array` or `String` containing a subset (slice) of the elements.
*
* All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()`
* and `String.prototype.slice()`.
*
* When operating on a [List], the returned list is always a copy even when all
* When operating on an `Array`, the returned `Array` is always a copy even when all
* the elements are being returned.
*
* When operating on a blank value, the pipe returns the blank value.
*
* ## List Example
* ### List Example
*
* This `ngFor` example:
*
Expand All @@ -56,6 +43,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';

@Pipe({name: 'slice', pure: false})
export class SlicePipe implements PipeTransform {
/**
* @param value a list or a string to be sliced.
* @param start the starting index of the subset to return:
* - **a positive integer**: return the item at `start` index and all items after
* in the list or string expression.
* - **a negative integer**: return the item at `start` index from the end and all items after
* in the list or string expression.
* - **if positive and greater than the size of the expression**: return an empty list or string.
* - **if negative and greater than the size of the expression**: return entire list or string.
* @param end the ending index of the subset to return:
* - **omitted**: return all items until the end.
* - **if positive**: return all items before `end` index of the list or string.
* - **if negative**: return all items before `end` index from the end of the list or string.
*/
transform(value: any, start: number, end?: number): any {
if (value == null) return value;

Expand Down

0 comments on commit cdd05bd

Please sign in to comment.