From 1ddb2bcd09a1b4ac7f18c70f5b871bd4939d6cd7 Mon Sep 17 00:00:00 2001 From: nova Date: Thu, 12 Dec 2019 00:13:21 +0530 Subject: [PATCH] added jsdoc to Sprintf wrapper for sprintf --- .../javascript/ts/src/singleton/Sprintf.ts | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/chatto/src/main/javascript/ts/src/singleton/Sprintf.ts b/chatto/src/main/javascript/ts/src/singleton/Sprintf.ts index fed2126..2d86c87 100644 --- a/chatto/src/main/javascript/ts/src/singleton/Sprintf.ts +++ b/chatto/src/main/javascript/ts/src/singleton/Sprintf.ts @@ -1,4 +1,80 @@ // /// +/** + * Returns a formatted string: + * + * string sprintf(string format, mixed arg1?, mixed arg2?, ...) + * + * ### Argument swapping + * + * You can also swap the arguments. That is, the order of the placeholders doesn't have to match the order of the arguments. + * You can do that by simply indicating in the format string which arguments the placeholders refer to: + * + * sprintf('%2$s %3$s a %1$s', 'cracker', 'Polly', 'wants') + * + * And, of course, you can repeat the placeholders without having to increase the number of arguments. + * + * ### Named arguments + * + * Format strings may contain replacement fields rather than positional placeholders. Instead of referring to a certain argument, + * you can now refer to a certain key within an object. Replacement fields are surrounded by rounded parentheses - `(` and `)` - + * and begin with a keyword that refers to a key: + * + * var user = { + * name: 'Dolly', + * } + * sprintf('Hello %(name)s', user) // Hello Dolly + * + * Keywords in replacement fields can be optionally followed by any number of keywords or indexes: + * + * var users = [ + * {name: 'Dolly'}, + * {name: 'Molly'}, + * {name: 'Polly'}, + * ] + * sprintf('Hello %(users[0].name)s, %(users[1].name)s and %(users[2].name)s', {users: users}) // Hello Dolly, Molly and Polly + * + * Note: mixing positional and named placeholders is not (yet) supported + * + * ### Computed values + * + * You can pass in a function as a dynamic value and it will be invoked (with no arguments) in order to compute the value on the fly. + * + * sprintf('Current date and time: %s', function() { return new Date().toString() }) + * + * @param format: format string + * The placeholders in the format string are marked by `%` and are followed by one or more of these elements, in this order: + * * An optional number followed by a `$` sign that selects which argument index to use for the value. If not specified, + * arguments will be placed in the same order as the placeholders in the input string. + * * An optional `+` sign that forces to preceed the result with a plus or minus sign on numeric values. By default, + * only the `-` sign is used on negative numbers. + * * An optional padding specifier that says what character to use for padding (if specified). Possible values are + * `0` or any other character precedeed by a `'` (single quote). The default is to pad with *spaces*. + * * An optional `-` sign, that causes `sprintf` to left-align the result of this placeholder. The default is to right-align the result. + * * An optional number, that says how many characters the result should have. If the value to be returned is shorter + * than this number, the result will be padded. When used with the `j` (JSON) type specifier, the padding length + * specifies the tab size used for indentation. + * * An optional precision modifier, consisting of a `.` (dot) followed by a number, that says how many digits should be + * displayed for floating point numbers. When used with the `g` type specifier, it specifies the number of significant + * digits. When used on a string, it causes the result to be truncated. + * * A type specifier that can be any of: + * * `%` — yields a literal `%` character + * * `b` — yields an integer as a binary number + * * `c` — yields an integer as the character with that ASCII value + * * `d` or `i` — yields an integer as a signed decimal number + * * `e` — yields a float using scientific notation + * * `u` — yields an integer as an unsigned decimal number + * * `f` — yields a float as is; see notes on precision above + * * `g` — yields a float as is; see notes on precision above + * * `o` — yields an integer as an octal number + * * `s` — yields a string as is + * * `t` — yields `true` or `false` + * * `T` — yields the type of the argument1 + * * `v` — yields the primitive value of the specified argument + * * `x` — yields an integer as a hexadecimal number (lower-case) + * * `X` — yields an integer as a hexadecimal number (upper-case) + * * `j` — yields a JavaScript object or array as a JSON encoded string + * @param args: the arguments for the format string + */ export function Sprintf(message: string, ...args: any[]): string { // @ts-ignore return sprintf(message, ...args);