Skip to content

Commit f0fec5a

Browse files
julienduchesnejulienduchesne
authored
Pull new stdlib docs (#206)
1 parent 147ddac commit f0fec5a

File tree

1 file changed

+104
-41
lines changed

1 file changed

+104
-41
lines changed

‎pkg/stdlib/stdlib-content.jsonnet‎

Lines changed: 104 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
local html = import 'html.libsonnet';
22

3+
local exampleDocMultiline(mid, ex) =
4+
html.spaceless([
5+
html.p({}, 'Example:'),
6+
html.pre({}, ex.input),
7+
html.p({}, mid),
8+
html.pre({}, ex.output),
9+
])
10+
;
11+
312
{
413
intro: html.paragraphs([
514
|||
@@ -98,6 +107,8 @@ local html = import 'html.libsonnet';
98107
<ul><code>std.pow(x, n)</code></ul>
99108
<ul><code>std.exp(x)</code></ul>
100109
<ul><code>std.log(x)</code></ul>
110+
<ul><code>std.log2(x)</code></ul>
111+
<ul><code>std.log10(x)</code></ul>
101112
<ul><code>std.exponent(x)</code></ul>
102113
<ul><code>std.mantissa(x)</code></ul>
103114
<ul><code>std.floor(x)</code></ul>
@@ -109,12 +120,19 @@ local html = import 'html.libsonnet';
109120
<ul><code>std.asin(x)</code></ul>
110121
<ul><code>std.acos(x)</code></ul>
111122
<ul><code>std.atan(x)</code></ul>
123+
<ul><code>std.atan2(y, x)</code></ul>
124+
<ul><code>std.deg2rad(x)</code></ul>
125+
<ul><code>std.rad2deg(x)</code></ul>
126+
<ul><code>std.hypot(a, b)</code></ul>
112127
<ul><code>std.round(x)</code></ul>
113128
<ul><code>std.isEven(x)</code></ul>
114129
<ul><code>std.isOdd(x)</code></ul>
115130
<ul><code>std.isInteger(x)</code></ul>
116131
<ul><code>std.isDecimal(x)</code></ul>
117132
</ul>
133+
<p>
134+
The constant <code>std.pi</code> is also available.
135+
</p>
118136
<p>
119137
The function <code>std.mod(a, b)</code> is what the % operator is desugared to. It performs
120138
modulo arithmetic if the left hand side is a number, or if the left hand side is a string,
@@ -199,11 +217,18 @@ local html = import 'html.libsonnet';
199217
name: 'substr',
200218
params: ['str', 'from', 'len'],
201219
availableSince: '0.10.0',
202-
description: |||
203-
Returns a string that is the part of <code>s</code> that starts at offset <code>from</code>
204-
and is <code>len</code> codepoints long. If the string <code>s</code> is shorter than
205-
<code>from+len</code>, the suffix starting at position <code>from</code> will be returned.
206-
|||,
220+
description: html.paragraphs([
221+
|||
222+
Returns a string that is the part of <code>str</code> that starts at offset <code>from</code>
223+
and is <code>len</code> codepoints long. If the string <code>str</code> is shorter than
224+
<code>from+len</code>, the suffix starting at position <code>from</code> will be returned.
225+
|||,
226+
|||
227+
The slice operator (e.g., <code>str[from:to]</code>) can also be used on strings, as an
228+
alternative to this function. However, note that the slice operator takes a start and an
229+
end index, but <code>std.substr</code> takes a start index and a length.
230+
|||,
231+
]),
207232
},
208233
{
209234
name: 'findSubstr',
@@ -382,15 +407,15 @@ local html = import 'html.libsonnet';
382407
{
383408
name: 'trim',
384409
params: ['str'],
385-
availableSince: 'upcoming',
410+
availableSince: '0.21.0',
386411
description: |||
387412
Returns a copy of string after eliminating leading and trailing whitespaces.
388413
|||,
389414
},
390415
{
391416
name: 'equalsIgnoreCase',
392417
params: ['str1', 'str2'],
393-
availableSince: 'upcoming',
418+
availableSince: '0.21.0',
394419
description: |||
395420
Returns true if the the given <code>str1</code> is equal to <code>str2</code> by doing case insensitive comparison, false otherwise.
396421
|||,
@@ -763,7 +788,7 @@ local html = import 'html.libsonnet';
763788
|||),
764789
],
765790
examples: [
766-
{
791+
exampleDocMultiline('Yields a string containing this JSON:', {
767792
input: |||
768793
std.manifestJsonEx(
769794
{
@@ -787,8 +812,8 @@ local html = import 'html.libsonnet';
787812
y: { a: 1, b: 2, c: [1, 2] },
788813
}, ' '
789814
),
790-
},
791-
{
815+
}),
816+
exampleDocMultiline('Yields a string containing this JSON:', {
792817
input: |||
793818
std.manifestJsonEx(
794819
{
@@ -803,7 +828,7 @@ local html = import 'html.libsonnet';
803828
y: { a: 1, b: [1, 2] },
804829
}, '', ' ', ' : '
805830
),
806-
},
831+
}),
807832
],
808833
},
809834
{
@@ -815,7 +840,7 @@ local html = import 'html.libsonnet';
815840
it calls <code>std.manifestJsonEx</code> with a 4-space indent:
816841
|||,
817842
examples: [
818-
{
843+
exampleDocMultiline('Yields a string containing this JSON:', {
819844
input: |||
820845
std.manifestJson(
821846
{
@@ -839,7 +864,7 @@ local html = import 'html.libsonnet';
839864
y: { a: 1, b: 2, c: [1, 2] },
840865
}
841866
),
842-
},
867+
}),
843868
],
844869
},
845870
{
@@ -851,7 +876,7 @@ local html = import 'html.libsonnet';
851876
it calls <code>std.manifestJsonEx</code>:
852877
|||,
853878
examples: [
854-
{
879+
exampleDocMultiline('Yields a string containing this JSON:', {
855880
input: |||
856881
std.manifestJsonMinified(
857882
{
@@ -875,7 +900,7 @@ local html = import 'html.libsonnet';
875900
y: { a: 1, b: 2, c: [1, 2] },
876901
}
877902
),
878-
},
903+
}),
879904
],
880905
},
881906
{
@@ -1046,7 +1071,7 @@ local html = import 'html.libsonnet';
10461071
one or more whitespaces that are used for indentation:
10471072
|||,
10481073
examples: [
1049-
{
1074+
exampleDocMultiline('Yields a string containing this TOML file:', {
10501075
input: |||
10511076
std.manifestTomlEx({
10521077
key1: "value",
@@ -1085,7 +1110,7 @@ local html = import 'html.libsonnet';
10851110
],
10861111
}, ' ')
10871112
),
1088-
},
1113+
}),
10891114
],
10901115
},
10911116
],
@@ -1209,21 +1234,31 @@ local html = import 'html.libsonnet';
12091234
name: 'foldl',
12101235
params: ['func', 'arr', 'init'],
12111236
availableSince: '0.10.0',
1212-
description: |||
1213-
Classic foldl function. Calls the function on the result of the previous function call and
1214-
each array element, or <code>init</code> in the case of the initial element. Traverses the
1215-
array from left to right.
1216-
|||,
1237+
description: html.paragraphs([
1238+
|||
1239+
Classic foldl function. Calls the function for each array element, passing the result from
1240+
the previous call (or <code>init</code> for the first call), and the array element. Traverses
1241+
the array from left to right.
1242+
|||,
1243+
|||
1244+
For example: <code>foldl(f, [1,2,3], 0)</code> is equivalent to <code>f(f(f(0, 1), 2), 3)</code>.
1245+
|||,
1246+
]),
12171247
},
12181248
{
12191249
name: 'foldr',
12201250
params: ['func', 'arr', 'init'],
12211251
availableSince: '0.10.0',
1222-
description: |||
1223-
Classic foldr function. Calls the function on the result of the previous function call and
1224-
each array element, or <code>init</code> in the case of the initial element. Traverses the
1225-
array from right to left.
1226-
|||,
1252+
description: html.paragraphs([
1253+
|||
1254+
Classic foldr function. Calls the function for each array element, passing the array element
1255+
and the result from the previous call (or <code>init</code> for the first call). Traverses
1256+
the array from right to left.
1257+
|||,
1258+
|||
1259+
For example: <code>foldr(f, [1,2,3], 0)</code> is equivalent to <code>f(1, f(2, f(3, 0)))</code>.
1260+
|||,
1261+
]),
12271262
},
12281263
{
12291264
name: 'range',
@@ -1303,6 +1338,26 @@ local html = import 'html.libsonnet';
13031338
},
13041339
],
13051340
},
1341+
{
1342+
name: 'deepJoin',
1343+
params: ['arr'],
1344+
availableSince: '0.10.0',
1345+
description: |||
1346+
Concatenate an array containing strings and arrays to form a single string. If <code>arr</code> is
1347+
a string, it is returned unchanged. If it is an array, it is flattened and the string elements are
1348+
concatenated together with no separator.
1349+
|||,
1350+
examples: [
1351+
{
1352+
input: 'std.deepJoin(["one ", ["two ", "three ", ["four "], []], "five ", ["six"]])',
1353+
output: std.deepJoin(['one ', ['two ', 'three ', ['four '], []], 'five ', ['six']]),
1354+
},
1355+
{
1356+
input: 'std.deepJoin("hello")',
1357+
output: std.deepJoin('hello'),
1358+
},
1359+
],
1360+
},
13061361
{
13071362
name: 'lines',
13081363
params: ['arr'],
@@ -1329,7 +1384,7 @@ local html = import 'html.libsonnet';
13291384
{
13301385
name: 'flattenDeepArray',
13311386
params: ['value'],
1332-
availableSince: 'upcoming',
1387+
availableSince: '0.21.0',
13331388
description: |||
13341389
Concatenate an array containing values and arrays into a single flattened array.
13351390
|||,
@@ -1415,27 +1470,35 @@ local html = import 'html.libsonnet';
14151470
{
14161471
name: 'minArray',
14171472
params: ['arr', 'keyF', 'onEmpty'],
1418-
availableSince: 'upcoming',
1473+
availableSince: '0.21.0',
14191474
description: html.paragraphs([
14201475
|||
1421-
Return the min of all element in <code>arr</code>.
1476+
Return the minimum of all elements in <code>arr</code>. If <code>keyF</code> is provided, it is called on each element
1477+
of the array and should return a comparator value, and in this case <code>minArray</code> will return an element
1478+
with the minimum comparator value. If <code>onEmpty</code> is provided, and <code>arr</code> is empty, then
1479+
<code>minArray</code> will return the provided <code>onEmpty</code> value. If <code>onEmpty</code> is not provided,
1480+
then an empty <code>arr</code> will raise an error.
14221481
|||,
14231482
]),
14241483
},
14251484
{
14261485
name: 'maxArray',
14271486
params: ['arr', 'keyF', 'onEmpty'],
1428-
availableSince: 'upcoming',
1487+
availableSince: '0.21.0',
14291488
description: html.paragraphs([
14301489
|||
1431-
Return the max of all element in <code>arr</code>.
1490+
Return the maximum of all elements in <code>arr</code>. If <code>keyF</code> is provided, it is called on each element
1491+
of the array and should return a comparator value, and in this case <code>maxArray</code> will return an element
1492+
with the maximum comparator value. If <code>onEmpty</code> is provided, and <code>arr</code> is empty, then
1493+
<code>maxArray</code> will return the provided <code>onEmpty</code> value. If <code>onEmpty</code> is not provided,
1494+
then an empty <code>arr</code> will raise an error.
14321495
|||,
14331496
]),
14341497
},
14351498
{
14361499
name: 'contains',
14371500
params: ['arr', 'elem'],
1438-
availableSince: 'upcoming',
1501+
availableSince: '0.21.0',
14391502
description: html.paragraphs([
14401503
|||
14411504
Return true if given <code>elem</code> is present in <code>arr</code>, false otherwise.
@@ -1455,7 +1518,7 @@ local html = import 'html.libsonnet';
14551518
{
14561519
name: 'remove',
14571520
params: ['arr', 'elem'],
1458-
availableSince: 'upcoming',
1521+
availableSince: '0.21.0',
14591522
description: html.paragraphs([
14601523
|||
14611524
Remove first occurrence of <code>elem</code> from <code>arr</code>.
@@ -1465,7 +1528,7 @@ local html = import 'html.libsonnet';
14651528
{
14661529
name: 'removeAt',
14671530
params: ['arr', 'idx'],
1468-
availableSince: 'upcoming',
1531+
availableSince: '0.21.0',
14691532
description: html.paragraphs([
14701533
|||
14711534
Remove element at <code>idx</code> index from <code>arr</code>.
@@ -1593,7 +1656,7 @@ local html = import 'html.libsonnet';
15931656
params: ['o'],
15941657
availableSince: '0.20.0',
15951658
description: |||
1596-
Returns an array of objects from the given object, each object having two fields:
1659+
Returns an array of objects from the given object, each object having two fields:
15971660
<code>key</code> (string) and <code>value</code> (object). Does not include hidden fields.
15981661
|||,
15991662
},
@@ -1632,7 +1695,7 @@ local html = import 'html.libsonnet';
16321695
{
16331696
name: 'objectRemoveKey',
16341697
params: ['obj', 'key'],
1635-
availableSince: 'upcoming',
1698+
availableSince: '0.21.0',
16361699
description: |||
16371700
Returns a new object after removing the given key from object.
16381701
|||,
@@ -1699,7 +1762,7 @@ local html = import 'html.libsonnet';
16991762
{
17001763
name: 'sha1',
17011764
params: ['s'],
1702-
availableSince: 'upcoming',
1765+
availableSince: '0.21.0',
17031766
description: [
17041767
html.p({}, |||
17051768
Encodes the given value into an SHA1 string.
@@ -1712,7 +1775,7 @@ local html = import 'html.libsonnet';
17121775
{
17131776
name: 'sha256',
17141777
params: ['s'],
1715-
availableSince: 'upcoming',
1778+
availableSince: '0.21.0',
17161779
description: [
17171780
html.p({}, |||
17181781
Encodes the given value into an SHA256 string.
@@ -1725,7 +1788,7 @@ local html = import 'html.libsonnet';
17251788
{
17261789
name: 'sha512',
17271790
params: ['s'],
1728-
availableSince: 'upcoming',
1791+
availableSince: '0.21.0',
17291792
description: [
17301793
html.p({}, |||
17311794
Encodes the given value into an SHA512 string.
@@ -1738,7 +1801,7 @@ local html = import 'html.libsonnet';
17381801
{
17391802
name: 'sha3',
17401803
params: ['s'],
1741-
availableSince: 'upcoming',
1804+
availableSince: '0.21.0',
17421805
description: [
17431806
html.p({}, |||
17441807
Encodes the given value into an SHA3 string.

0 commit comments

Comments
 (0)