1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
# Format
The `Format` module is a mostly deprecated module that implements `printf()`
style formatting for GJS.
In most cases, native [template literals][template-literals] should be preferred
now, except in few situations like Gettext (See [Bug #60027][bug-60027]).
```js
const foo = 'Pi';
const bar = 1;
const baz = Math.PI;
// expected result: "Pi to 2 decimal points: 3.14"
// Native template literals
const str1 = `${foo} to ${bar*2} decimal points: ${baz.toFixed(bar*2)}`
// Format.vprintf()
const str2 = Format.vprintf('%s to %d decimal points: %.2f', [foo, bar*2, baz]);
```
#### Import
> Attention: This module is not available as an ECMAScript Module
The `Format` module is available on the global `imports` object:
```js
const Format = imports.format;
```
[template-literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
[bug-60027]: https://savannah.gnu.org/bugs/?60027
### Format.format(...args)
> Deprecated: Use [`Format.vprintf()`](#format-vprintf) instead
Type:
* Prototype Function
Parameters:
* args (`Any`) — Formatting substitutions
Returns:
* (`String`) — A new formatted string
This function was intended to extend the `String` object and provide a
`String.format` API for string formatting.
Example usage:
```js
const Format = imports.format;
// Applying format() to the string prototype.
//
// This is highly discouraged, especially in GNOME Shell extensions where other
// extensions might overwrite it. Use Format.vprintf() directly instead.
String.prototype.format = Format.format;
// Usage with String.prototype.format()
// expected result: "A formatted string"
const str = 'A %s %s'.format('formatted', 'string');
```
### Format.printf(fmt, ...args)
> Deprecated: Use [template literals][template-literals] with `print()` instead
Type:
* Static
Parameters:
* fmt (`String`) — A format template
* args (`Any`) — Formatting substitutions
Substitute the specifiers in `fmt` with `args` and print the result to `stdout`.
Example usage:
```js
// expected output: A formatted string
Format.printf('A %s %s', 'formatted', 'string');
```
### Format.vprintf(fmt, args)
> Deprecated: Prefer [template literals][template-literals] when possible
Type:
* Static
Parameters:
* fmt (`String`) — A format template
* args (`Array(Any)`) — Formatting substitutions
Returns:
* (`String`) — A new formatted string
Substitute the specifiers in `fmt` with `args` and return a new string. It
supports the `%s`, `%d`, `%x` and `%f` specifiers.
For `%f` it also supports precisions like `vprintf('%.2f', [1.526])`. All
specifiers can be prefixed with a minimum field width (e.g.
`vprintf('%5s', ['foo'])`). Unless the width is prefixed with `'0'`, the
formatted string will be padded with spaces.
Example usage:
```js
// expected result: "A formatted string"
const str = Format.vprintf('A %s %s', ['formatted', 'string']);
// Usage with Gettext
Format.vprintf(_('%d:%d'), [11, 59]);
Format.vprintf(
Gettext.ngettext('I have %d apple', 'I have %d apples', num), [num]);
```
[template-literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
|
