From f324ff7ab7c55e7de938f9c1f4361e461089f029 Mon Sep 17 00:00:00 2001 From: John Bartholomew Date: Tue, 16 Apr 2024 16:11:50 +0100 Subject: [PATCH] chore: update stdlib ref with tools/scripts/update_web_content.sh --- doc/ref/stdlib.html | 2097 ++++++++++++++++++++++++++----------------- 1 file changed, 1256 insertions(+), 841 deletions(-) diff --git a/doc/ref/stdlib.html b/doc/ref/stdlib.html index 391969de4..7fc55ea85 100644 --- a/doc/ref/stdlib.html +++ b/doc/ref/stdlib.html @@ -69,7 +69,7 @@

- If an external variable with the given name was defined, return its string value. Otherwise, raise an error. + If an external variable with the given name was defined, return its value. Otherwise, raise an error.

@@ -183,8 +183,8 @@

-

- std.get(o, f, default=null, inc_hidden=true) +

+ std.prune(a)

@@ -195,12 +195,13 @@

- Available since version 0.18.0. + Available since version 0.10.0.

- Returns the object's field if it exists or default value otherwise. - inc_hidden controls whether to include hidden fields. + Recursively remove all "empty" members of a. "Empty" is defined as zero + length `arrays`, zero length `objects`, or `null` values. + The argument a may have any type.

@@ -208,12 +209,13 @@

+
-

- std.objectHas(o, f) -

+

+ Mathematical Utilities +

@@ -222,16 +224,42 @@

- - Available since version 0.10.0. - + The following mathematical functions are available: +

+
    +
      std.abs(n)
    +
      std.sign(n)
    +
      std.max(a, b)
    +
      std.min(a, b)
    +
      std.pow(x, n)
    +
      std.exp(x)
    +
      std.log(x)
    +
      std.exponent(x)
    +
      std.mantissa(x)
    +
      std.floor(x)
    +
      std.ceil(x)
    +
      std.sqrt(x)
    +
      std.sin(x)
    +
      std.cos(x)
    +
      std.tan(x)
    +
      std.asin(x)
    +
      std.acos(x)
    +
      std.atan(x)
    +
      std.round(x)
    +
      std.isEven(x)
    +
      std.isOdd(x)
    +
      std.isInteger(x)
    +
      std.isDecimal(x)
    +
+

+ The function std.mod(a, b) is what the % operator is desugared to. It performs + modulo arithmetic if the left hand side is a number, or if the left hand side is a string, + it does Python-style string formatting with std.format().

- Returns true if the given object has the field (given as a string), otherwise - false. Raises an error if the arguments are not object and string - respectively. Returns false if the field is hidden. + The functions std.isEven(x) and std.isOdd(x) use integral part of a + floating number to test for even or odd.

-
@@ -240,8 +268,8 @@

-

- std.objectFields(o) +

+ std.clamp(x, minVal, maxVal)

@@ -252,24 +280,44 @@

- Available since version 0.10.0. + Available since version 0.15.0.

- Returns an array of strings, each element being a field from the given object. Does not include - hidden fields. + Clamp a value to fit within the range [minVal, maxVal]. + Equivalent to std.max(minVal, std.min(x, maxVal)). +

+

+ Example: std.clamp(-3, 0, 5) yields 0. +

+

+ Example: std.clamp(4, 0, 5) yields 4. +

+

+ Example: std.clamp(7, 0, 5) yields 5.

-

+
-

- std.objectValues(o) +

+ Assertions and Debugging +

+
+
+
+
+ +
+
+
+

+ std.assertEqual(a, b)

@@ -280,11 +328,11 @@

- Available since version 0.17.0. + Available since version 0.10.0.

- Returns an array of the values in the given object. Does not include hidden fields. + Ensure that a == b. Returns true or throws an error message.

@@ -292,11 +340,23 @@

+
-

- std.objectKeysValues(o) +

+ String Manipulation +

+
+
+
+
+ +
+
+
+

+ std.toString(a)

@@ -307,12 +367,11 @@

- Available since version 0.20.0. + Available since version 0.10.0.

- Returns an array of objects from the given object, each object having two fields: - key (string) and value (object). Does not include hidden fields. + Convert the given argument to a string.

@@ -323,8 +382,8 @@

-

- std.objectHasAll(o, f) +

+ std.codepoint(str)

@@ -339,7 +398,8 @@

- As std.objectHas but also includes hidden fields. + Returns the positive integer representing the unicode codepoint of the character in the + given single-character string. This function is the inverse of std.char(n).

@@ -350,8 +410,8 @@

-

- std.objectFieldsAll(o) +

+ std.char(n)

@@ -366,7 +426,8 @@

- As std.objectFields but also includes hidden fields. + Returns a string of length one whose only unicode codepoint has integer id n. + This function is the inverse of std.codepoint(str).

@@ -377,8 +438,8 @@

-

- std.objectValuesAll(o) +

+ std.substr(str, from, len)

@@ -389,11 +450,13 @@

- Available since version 0.17.0. + Available since version 0.10.0.

- As std.objectValues but also includes hidden fields. + Returns a string that is the part of s that starts at offset from + and is len codepoints long. If the string s is shorter than + from+len, the suffix starting at position from will be returned.

@@ -404,8 +467,8 @@

-

- std.objectKeysValuesAll(o) +

+ std.findSubstr(pat, str)

@@ -416,11 +479,12 @@

- Available since version 0.20.0. + Available since version 0.10.0.

- As std.objectKeysValues but also includes hidden fields. + Returns an array that contains the indexes of all occurrences of pat in + str.

@@ -431,8 +495,8 @@

-

- std.prune(a) +

+ std.startsWith(a, b)

@@ -447,9 +511,7 @@

- Recursively remove all "empty" members of a. "Empty" is defined as zero - length `arrays`, zero length `objects`, or `null` values. - The argument a may have any type. + Returns whether the string a is prefixed by the string b.

@@ -460,8 +522,8 @@

-

- std.mapWithKey(func, obj) +

+ std.endsWith(a, b)

@@ -476,9 +538,7 @@

- Apply the given function to all fields of the given object, also passing - the field name. The function func is expected to take the - field name as the first parameter and the field value as the second. + Returns whether the string a is suffixed by the string b.

@@ -486,13 +546,12 @@

-
-

- Mathematical Utilities -

+

+ std.stripChars(str, chars) +

@@ -501,33 +560,21 @@

- The following mathematical functions are available: + + Available since version 0.15.0. +

-
    -
      std.abs(n)
    -
      std.sign(n)
    -
      std.max(a, b)
    -
      std.min(a, b)
    -
      std.pow(x, n)
    -
      std.exp(x)
    -
      std.log(x)
    -
      std.exponent(x)
    -
      std.mantissa(x)
    -
      std.floor(x)
    -
      std.ceil(x)
    -
      std.sqrt(x)
    -
      std.sin(x)
    -
      std.cos(x)
    -
      std.tan(x)
    -
      std.asin(x)
    -
      std.acos(x)
    -
      std.atan(x)
    -
      std.round(x)
    -

- The function std.mod(a, b) is what the % operator is desugared to. It performs - modulo arithmetic if the left hand side is a number, or if the left hand side is a string, - it does Python-style string formatting with std.format(). + Removes characters chars from the beginning and from the end of str. +

+

+ Example: std.stripChars(" test test test ", " ") yields "test test test". +

+

+ Example: std.stripChars("aaabbbbcccc", "ac") yields "bbbb". +

+

+ Example: std.stripChars("cacabbbbaacc", "ac") yields "bbbb".

@@ -537,8 +584,8 @@

-

- std.clamp(x, minVal, maxVal) +

+ std.lstripChars(str, chars)

@@ -553,40 +600,27 @@

- Clamp a value to fit within the range [minVal, maxVal]. - Equivalent to std.max(minVal, std.min(x, maxVal)). + Removes characters chars from the beginning of str.

- Example: std.clamp(-3, 0, 5) yields 0. + Example: std.lstripChars(" test test test ", " ") yields "test test test ".

- Example: std.clamp(4, 0, 5) yields 4. + Example: std.lstripChars("aaabbbbcccc", "ac") yields "bbbbcccc".

- Example: std.clamp(7, 0, 5) yields 5. + Example: std.lstripChars("cacabbbbaacc", "ac") yields "bbbbaacc".

- -
-
-
-

- Assertions and Debugging -

-
-
-
-
-
-

- std.assertEqual(a, b) +

+ std.rstripChars(str, chars)

@@ -597,35 +631,31 @@

- Available since version 0.10.0. + Available since version 0.15.0.

- Ensure that a == b. Returns true or throws an error message. + Removes characters chars from the end of str. +

+

+ Example: std.rstripChars(" test test test ", " ") yields " test test test". +

+

+ Example: std.rstripChars("aaabbbbcccc", "ac") yields "aaabbbb". +

+

+ Example: std.rstripChars("cacabbbbaacc", "ac") yields "cacabbbb".

-

-
-

- String Manipulation -

-
-
-
-
- -
-
-
-

- std.toString(a) +

+ std.split(str, c)

@@ -640,9 +670,18 @@

- Convert the given argument to a string. + Split the string str into an array of strings, divided by the string + c. +

+

+ Note: Versions up to and including 0.18.0 require c to be a single character. +

+

+ Example: std.split("foo/_bar", "/_") yields [ "foo", "bar" ]. +

+

+ Example: std.split("/_foo/_bar", "/_") yields [ "", "foo", "bar" ].

-

@@ -651,8 +690,8 @@

-

- std.codepoint(str) +

+ std.splitLimit(str, c, maxsplits)

@@ -667,10 +706,18 @@

- Returns the positive integer representing the unicode codepoint of the character in the - given single-character string. This function is the inverse of std.char(n). + As std.split(str, c) but will stop after maxsplits splits, thereby the largest + array it will return has length maxsplits + 1. A limit of -1 means unlimited. +

+

+ Note: Versions up to and including 0.18.0 require c to be a single character. +

+

+ Example: std.splitLimit("foo/_bar", "/_", 1) yields [ "foo", "bar" ]. +

+

+ Example: std.splitLimit("/_foo/_bar", "/_", 1) yields [ "", "foo/_bar" ].

-

@@ -679,8 +726,8 @@

-

- std.char(n) +

+ std.splitLimitR(str, c, maxsplits)

@@ -691,14 +738,15 @@

- Available since version 0.10.0. + Available since version 0.19.0.

- Returns a string of length one whose only unicode codepoint has integer id n. - This function is the inverse of std.codepoint(str). + As std.splitLimit(str, c, maxsplits) but will split from right to left. +

+

+ Example: std.splitLimitR("/_foo/_bar", "/_", 1) yields [ "/_foo", "bar" ].

-

@@ -707,8 +755,8 @@

-

- std.substr(str, from, len) +

+ std.strReplace(str, from, to)

@@ -723,11 +771,12 @@

- Returns a string that is the part of s that starts at offset from - and is len codepoints long. If the string s is shorter than - from+len, the suffix starting at position from will be returned. + Returns a copy of the string in which all occurrences of string from have been + replaced with string to. +

+

+ Example: std.strReplace('I like to skate with my skateboard', 'skate', 'surf') yields "I like to surf with my surfboard".

-

@@ -736,8 +785,8 @@

-

- std.findSubstr(pat, str) +

+ std.isEmpty(str)

@@ -748,12 +797,11 @@

- Available since version 0.10.0. + Available since version 0.20.0.

- Returns an array that contains the indexes of all occurrences of pat in - str. + Returns true if the given string is of zero length.

@@ -764,8 +812,8 @@

-

- std.startsWith(a, b) +

+ std.trim(str)

@@ -776,11 +824,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- Returns whether the string a is prefixed by the string b. + Returns a copy of string after eliminating leading and trailing whitespaces.

@@ -791,8 +839,8 @@

-

- std.endsWith(a, b) +

+ std.equalsIgnoreCase(str1, str2)

@@ -803,11 +851,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- Returns whether the string a is suffixed by the string b. + Returns true if the the given str1 is equal to str2 by doing case insensitive comparison, false otherwise.

@@ -818,8 +866,8 @@

-

- std.stripChars(str, chars) +

+ std.asciiUpper(str)

@@ -830,20 +878,14 @@

- Available since version 0.15.0. + Available since version 0.10.0.

- Removes characters chars from the beginning and from the end of str. -

-

- Example: std.stripChars(" test test test ", " ") yields "test test test". -

-

- Example: std.stripChars("aaabbbbcccc", "ac") yields "bbbb". + Returns a copy of the string in which all ASCII letters are capitalized.

- Example: std.stripChars("cacabbbbaacc", "ac") yields "bbbb". + Example: std.asciiUpper('100 Cats!') yields "100 CATS!".

@@ -853,8 +895,8 @@

-

- std.lstripChars(str, chars) +

+ std.asciiLower(str)

@@ -865,20 +907,14 @@

- Available since version 0.15.0. + Available since version 0.10.0.

- Removes characters chars from the beginning of str. -

-

- Example: std.lstripChars(" test test test ", " ") yields "test test test ". -

-

- Example: std.lstripChars("aaabbbbcccc", "ac") yields "bbbbcccc". + Returns a copy of the string in which all ASCII letters are lower cased.

- Example: std.lstripChars("cacabbbbaacc", "ac") yields "bbbbaacc". + Example: std.asciiLower('100 Cats!') yields "100 cats!".

@@ -888,8 +924,8 @@

-

- std.rstripChars(str, chars) +

+ std.stringChars(str)

@@ -900,20 +936,15 @@

- Available since version 0.15.0. + Available since version 0.10.0.

- Removes characters chars from the end of str. -

-

- Example: std.rstripChars(" test test test ", " ") yields " test test test". -

-

- Example: std.rstripChars("aaabbbbcccc", "ac") yields "aaabbbb". + Split the string str into an array of strings, each containing a single + codepoint.

- Example: std.rstripChars("cacabbbbaacc", "ac") yields "cacabbbb". + Example: std.stringChars("foo") yields [ "f", "o", "o" ].

@@ -923,8 +954,8 @@

-

- std.split(str, c) +

+ std.format(str, vals)

@@ -939,17 +970,23 @@

- Split the string str into an array of strings, divided by the string - c. + Format the string str using the values in vals. The values can be + an array, an object, or in other cases are treated as if they were provided in a singleton + array. The string formatting follows the same rules as + Python. The % operator can be used as a shorthand for this function.

- Note: Versions up to and including 0.18.0 require c to be a single character. + Example: std.format("Hello %03d", 12) yields "Hello 012".

- Example: std.split("foo/_bar", "/_") yields [ "foo", "bar" ]. + Example: "Hello %03d" % 12 yields "Hello 012".

- Example: std.split("/_foo/_bar", "/_") yields [ "", "foo", "bar" ]. + Example: "Hello %s, age %d" % ["Foo", 25] yields "Hello Foo, age 25". +

+

+ Example: "Hello %(name)s, age %(age)d" % {age: 25, name: "Foo"} yields "Hello Foo, age 25".

@@ -959,8 +996,8 @@

-

- std.splitLimit(str, c, maxsplits) +

+ std.escapeStringBash(str)

@@ -975,18 +1012,11 @@

- As std.split(str, c) but will stop after maxsplits splits, thereby the largest - array it will return has length maxsplits + 1. A limit of -1 means unlimited. -

-

- Note: Versions up to and including 0.18.0 require c to be a single character. -

-

- Example: std.splitLimit("foo/_bar", "/_", 1) yields [ "foo", "bar" ]. -

-

- Example: std.splitLimit("/_foo/_bar", "/_", 1) yields [ "", "foo/_bar" ]. + Wrap str in single quotes, and escape any single quotes within str + by changing them to a sequence '"'"'. This allows injection of arbitrary strings + as arguments of commands in bash scripts.

+

@@ -995,8 +1025,8 @@

-

- std.splitLimitR(str, c, maxsplits) +

+ std.escapeStringDollars(str)

@@ -1007,15 +1037,14 @@

- Available since version 0.19.0. + Available since version 0.10.0.

- As std.splitLimit(str, c, maxsplits) but will split from right to left. -

-

- Example: std.splitLimitR("/_foo/_bar", "/_", 1) yields [ "/_foo", "bar" ]. + Convert $ to $$ in str. This allows injection of arbitrary strings into + systems that use $ for string interpolation (like Terraform).

+

@@ -1024,8 +1053,8 @@

-

- std.strReplace(str, from, to) +

+ std.escapeStringJson(str)

@@ -1040,11 +1069,12 @@

- Returns a copy of the string in which all occurrences of string from have been - replaced with string to. + Convert str to allow it to be embedded in a JSON representation, within a + string. This adds quotes, escapes backslashes, and escapes unprintable characters.

- Example: std.strReplace('I like to skate with my skateboard', 'skate', 'surf') yields "I like to surf with my surfboard". + Example: local description = "Multiline\nc:\\path"; + "{name: %s}" % std.escapeStringJson(description) yields "{name: \"Multiline\\nc:\\\\path\"}".

@@ -1054,8 +1084,8 @@

-

- std.isEmpty(str) +

+ std.escapeStringPython(str)

@@ -1066,11 +1096,12 @@

- Available since version 0.20.0. + Available since version 0.10.0.

- Returns true if the given string is of zero length. + Convert str to allow it to be embedded in Python. This is an alias for + std.escapeStringJson.

@@ -1081,8 +1112,8 @@

-

- std.asciiUpper(str) +

+ std.escapeStringXml(str)

@@ -1097,21 +1128,40 @@

- Returns a copy of the string in which all ASCII letters are capitalized. -

-

- Example: std.asciiUpper('100 Cats!') yields "100 CATS!". + Convert str to allow it to be embedded in XML (or HTML). The following replacements are made: + 

+        {
+          "<": "&lt;",
+          ">": "&gt;",
+          "&": "&amp;",
+          "\"": "&quot;",
+          "'": "&apos;",
+        }
+

+

+
-

- std.asciiLower(str) +

+ Parsing +

+
+
+
+
+ +
+
+
+

+ std.parseInt(str)

@@ -1126,10 +1176,13 @@

- Returns a copy of the string in which all ASCII letters are lower cased. + Parses a signed decimal integer from the input string.

- Example: std.asciiLower('100 Cats!') yields "100 cats!". + Example: std.parseInt("123") yields 123. +

+

+ Example: std.parseInt("-123") yields -123.

@@ -1139,8 +1192,8 @@

-

- std.stringChars(str) +

+ std.parseOctal(str)

@@ -1155,11 +1208,10 @@

- Split the string str into an array of strings, each containing a single - codepoint. + Parses an unsigned octal integer from the input string. Initial zeroes are tolerated.

- Example: std.stringChars("foo") yields [ "f", "o", "o" ]. + Example: std.parseOctal("755") yields 493.

@@ -1169,8 +1221,8 @@

-

- std.format(str, vals) +

+ std.parseHex(str)

@@ -1185,23 +1237,10 @@

- Format the string str using the values in vals. The values can be - an array, an object, or in other cases are treated as if they were provided in a singleton - array. The string formatting follows the same rules as - Python. The % operator can be used as a shorthand for this function. -

-

- Example: std.format("Hello %03d", 12) yields "Hello 012". -

-

- Example: "Hello %03d" % 12 yields "Hello 012". -

-

- Example: "Hello %s, age %d" % ["Foo", 25] yields "Hello Foo, age 25". + Parses an unsigned hexadecimal integer, from the input string. Case insensitive.

- Example: "Hello %(name)s, age %(age)d" % {age: 25, name: "Foo"} yields "Hello Foo, age 25". + Example: std.parseHex("ff") yields 255.

@@ -1211,8 +1250,8 @@

-

- std.escapeStringBash(str) +

+ std.parseJson(str)

@@ -1223,43 +1262,15 @@

- Available since version 0.10.0. + Available since version 0.13.0.

- Wrap str in single quotes, and escape any single quotes within str - by changing them to a sequence '"'"'. This allows injection of arbitrary strings - as arguments of commands in bash scripts. -

- -
-
-

-
- -
-
-
-

- std.escapeStringDollars(str) -

-
-
-
-
-
-
-
-

- - Available since version 0.10.0. - + Parses a JSON string.

- Convert $ to $$ in str. This allows injection of arbitrary strings into - systems that use $ for string interpolation (like Terraform). + Example: std.parseJson('{"foo": "bar"}') yields { "foo": "bar" }.

-
@@ -1268,8 +1279,8 @@

-

- std.escapeStringJson(str) +

+ std.parseYaml(str)

@@ -1280,16 +1291,18 @@

- Available since version 0.10.0. + Available since version 0.18.0.

- Convert str to allow it to be embedded in a JSON representation, within a - string. This adds quotes, escapes backslashes, and escapes unprintable characters. + Parses a YAML string. This is provided as a "best-effort" mechanism and should not be relied on to provide + a fully standards compliant YAML parser. YAML is a superset of JSON, consequently "downcasting" or + manifestation of YAML into JSON or Jsonnet values will only succeed when using the subset of YAML that is + compatible with JSON. The parser does not support YAML documents with scalar values at the root. The + root node of a YAML document must start with either a YAML sequence or map to be successfully parsed.

- Example: local description = "Multiline\nc:\\path"; - "{name: %s}" % std.escapeStringJson(description) yields "{name: \"Multiline\\nc:\\\\path\"}". + Example: std.parseYaml('foo: bar') yields { "foo": "bar" }.

@@ -1299,8 +1312,8 @@

-

- std.escapeStringPython(str) +

+ std.encodeUTF8(str)

@@ -1311,12 +1324,12 @@

- Available since version 0.10.0. + Available since version 0.13.0.

- Convert str to allow it to be embedded in Python. This is an alias for - std.escapeStringJson. + Encode a string using UTF8. Returns an array of numbers + representing bytes.

@@ -1327,8 +1340,8 @@

-

- std.escapeStringXml(str) +

+ std.decodeUTF8(arr)

@@ -1339,20 +1352,12 @@

- Available since version 0.10.0. + Available since version 0.13.0.

- Convert str to allow it to be embedded in XML (or HTML). The following replacements are made: - 

-        {
-          "<": "&lt;",
-          ">": "&gt;",
-          "&": "&amp;",
-          "\"": "&quot;",
-          "'": "&apos;",
-        }
-
+ Decode an array of numbers representing bytes using UTF8. + Returns a string.

@@ -1364,8 +1369,8 @@

-

- Parsing +

+ Manifestation

@@ -1375,8 +1380,8 @@

-

- std.parseInt(str) +

+ std.manifestIni(ini)

@@ -1391,14 +1396,34 @@

- Parses a signed decimal integer from the input string. -

-

- Example: std.parseInt("123") yields 123. + Convert the given structure to a string in INI format. This + allows using Jsonnet's + object model to build a configuration to be consumed by an application expecting an INI + file. The data is in the form of a set of sections, each containing a key/value mapping. + These examples should make it clear:

+ 
{
+    main: { a: "1", b: "2" },
+    sections: {
+        s1: {x: "11", y: "22", z: "33"},
+        s2: {p: "yes", q: ""},
+        empty: {},
+    }
+}

- Example: std.parseInt("-123") yields -123. + Yields a string containing this INI file:

+ 
a = 1
+b = 2
+[empty]
+[s1]
+x = 11
+y = 22
+z = 33
+[s2]
+p = yes
+q =
+

@@ -1407,8 +1432,8 @@

-

- std.parseOctal(str) +

+ std.manifestPython(v)

@@ -1423,11 +1448,25 @@

- Parses an unsigned octal integer from the input string. Initial zeroes are tolerated. + Convert the given value to a JSON-like form that is compatible with Python. The chief + differences are True / False / None instead of true / false / null.

+ 
{
+    b: ["foo", "bar"],
+    c: true,
+    d: null,
+    e: { f1: false, f2: 42 },
+}

- Example: std.parseOctal("755") yields 493. + Yields a string containing Python code like:

+ 
{
+    "b": ["foo", "bar"],
+    "c": True,
+    "d": None,
+    "e": {"f1": False, "f2": 42}
+}
+

@@ -1436,8 +1475,8 @@

-

- std.parseHex(str) +

+ std.manifestPythonVars(conf)

@@ -1452,11 +1491,24 @@

- Parses an unsigned hexadecimal integer, from the input string. Case insensitive. + Convert the given object to a JSON-like form that is compatible with Python. The key + difference to std.manifestPython is that the top level is represented as a list + of Python global variables.

+ 
{
+    b: ["foo", "bar"],
+    c: true,
+    d: null,
+    e: { f1: false, f2: 42 },
+}

- Example: std.parseHex("ff") yields 255. + Yields a string containing this Python code:

+ 
b = ["foo", "bar"]
+c = True
+d = None
+e = {"f1": False, "f2": 42}
+

@@ -1465,8 +1517,8 @@

-

- std.parseJson(str) +

+ std.manifestJsonEx(value, indent, newline, key_val_sep)

@@ -1477,14 +1529,30 @@

- Available since version 0.13.0. + Available since version 0.10.0.

- Parses a JSON string. + Convert the given object to a JSON form. indent is a string containing + one or more whitespaces that are used for indentation. newline is + by default \n and is inserted where a newline would normally be used + to break long lines. key_val_sep is used to separate the key and value + of an object field:

- Example: std.parseJson('{"foo": "bar"}') yields { "foo": "bar" }. + Example: std.manifestJsonEx( + { + x: [1, 2, 3, true, false, null, + "string\nstring"], + y: { a: 1, b: 2, c: [1, 2] }, + }, " ") yields "{\n \"x\": [\n 1,\n 2,\n 3,\n true,\n false,\n null,\n \"string\\nstring\"\n ],\n \"y\": {\n \"a\": 1,\n \"b\": 2,\n \"c\": [\n 1,\n 2\n ]\n }\n}". +

+

+ Example: std.manifestJsonEx( + { + x: [1, 2, "string\nstring"], + y: { a: 1, b: [1, 2] }, + }, "", " ", " : ") yields "{ \"x\" : [ 1, 2, \"string\\nstring\" ], \"y\" : { \"a\" : 1, \"b\" : [ 1, 2 ] } }".

@@ -1494,8 +1562,8 @@

-

- std.parseYaml(str) +

+ std.manifestJsonMinified(value)

@@ -1510,14 +1578,16 @@

- Parses a YAML string. This is provided as a "best-effort" mechanism and should not be relied on to provide - a fully standards compliant YAML parser. YAML is a superset of JSON, consequently "downcasting" or - manifestation of YAML into JSON or Jsonnet values will only succeed when using the subset of YAML that is - compatible with JSON. The parser does not support YAML documents with scalar values at the root. The - root node of a YAML document must start with either a YAML sequence or map to be successfully parsed. + Convert the given object to a minified JSON form. Under the covers, + it calls std.manifestJsonEx:'):

- Example: std.parseYaml('foo: bar') yields { "foo": "bar" }. + Example: std.manifestJsonMinified( + { + x: [1, 2, 3, true, false, null, + "string\nstring"], + y: { a: 1, b: 2, c: [1, 2] }, + }) yields "{\"x\":[1,2,3,true,false,null,\"string\\nstring\"],\"y\":{\"a\":1,\"b\":2,\"c\":[1,2]}}".

@@ -1527,8 +1597,8 @@

-

- std.encodeUTF8(str) +

+ std.manifestYamlDoc(value, indent_array_in_object=false, quote_keys=true)

@@ -1539,40 +1609,523 @@

- Available since version 0.13.0. + Available since version 0.10.0.

- Encode a string using UTF8. Returns an array of numbers - representing bytes. + Convert the given value to a YAML form. Note that std.manifestJson could also + be used for this purpose, because any JSON is also valid YAML. But this function will + produce more canonical-looking YAML.

- -
-
-

-
- -
-
-
-

- std.decodeUTF8(arr) -

-
-
-
-
-
+ 
std.manifestYamlDoc(
+  {
+      x: [1, 2, 3, true, false, null,
+          "string\nstring\n"],
+      y: { a: 1, b: 2, c: [1, 2] },
+  },
+  indent_array_in_object=false)
+

+ Yields a string containing this YAML: +

+ 
"x":
+  - 1
+  - 2
+  - 3
+  - true
+  - false
+  - null
+  - |
+      string
+      string
+"y":
+  "a": 1
+  "b": 2
+  "c":
+      - 1
+      - 2
+

+ The indent_array_in_object param adds additional indentation which some people + may find easier to read. +

+

+ The quote_keys parameter controls whether YAML identifiers are always quoted + or only when necessary. +

+ +
+
+

+

+ +
+
+
+

+ std.manifestYamlStream(value, indent_array_in_object=false, c_document_end=false, quote_keys=true) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Given an array of values, emit a YAML "stream", which is a sequence of documents separated + by --- and ending with .... +

+ 
std.manifestYamlStream(
+  ['a', 1, []],
+  indent_array_in_object=false,
+  c_document_end=true)
+

+ Yields this string: +

+ 
---
+"a"
+---
+1
+---
+[]
+...
+

+ The indent_array_in_object and quote_keys params are the + same as in manifestYamlDoc. +

+

+ The c_document_end param adds the optional terminating .... +

+ +
+
+
+
+ +
+
+
+

+ std.manifestXmlJsonml(value) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Convert the given JsonML-encoded value to a string + containing the XML. +

+ 
std.manifestXmlJsonml([
+    'svg', { height: 100, width: 100 },
+    [
+        'circle', {
+        cx: 50, cy: 50, r: 40,
+        stroke: 'black', 'stroke-width': 3,
+        fill: 'red',
+        }
+    ],
+])
+

+ Yields a string containing this XML (all on one line): +

+ 
<svg height="100" width="100">
+    <circle cx="50" cy="50" fill="red" r="40"
+    stroke="black" stroke-width="3"></circle>;
+</svg>;
+

+ Which represents the following image: +

+ + + Sorry, your browser does not support inline SVG. + +

+ JsonML is designed to preserve "mixed-mode content" (i.e., textual data outside of or next + to elements). This includes the whitespace needed to avoid having all the XML on one line, + which is meaningful in XML. In order to have whitespace in the XML output, it must be + present in the JsonML input: +

+ 
std.manifestXmlJsonml([
+    'svg',
+    { height: 100, width: 100 },
+    '\n  ',
+    [
+        'circle',
+        {
+        cx: 50, cy: 50, r: 40, stroke: 'black',
+        'stroke-width': 3, fill: 'red',
+        }
+    ],
+    '\n',
+])
+ +
+
+
+
+ +
+
+
+

+ std.manifestTomlEx(toml, indent) +

+
+
+
+
+
+
+
+

+ + Available since version 0.18.0. + +

+

+ Convert the given object to a TOML form. indent is a string containing + one or more whitespaces that are used for indentation: +

+

+ Example: std.manifestTomlEx({ + key1: "value", + key2: 1, + section: { + a: 1, + b: "str", + c: false, + d: [1, "s", [2, 3]], + subsection: { + k: "v", + }, + }, + sectionArray: [ + { k: "v1", v: 123 }, + { k: "v2", c: "value2" }, + ], + }, " ") yields "key1 = \"value\"\nkey2 = 1\n\n[section]\n a = 1\n b = \"str\"\n c = false\n d = [\n 1,\n \"s\",\n [ 2, 3 ]\n ]\n\n [section.subsection]\n k = \"v\"\n\n[[sectionArray]]\n k = \"v1\"\n v = 123\n\n[[sectionArray]]\n c = \"value2\"\n k = \"v2\"". +

+
+
+
+
+ + +
+
+
+

+ Arrays +

+
+
+
+
+ +
+
+
+

+ std.makeArray(sz, func) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Create a new array of sz elements by calling func(i) to initialize + each element. Func is expected to be a function that takes a single parameter, the index of + the element it should initialize. +

+

+ Example: std.makeArray(3,function(x) x * x) yields [ 0, 1, 4 ]. +

+
+
+
+
+ +
+
+
+

+ std.member(arr, x) +

+
+
+
+
+
+
+
+

+ + Available since version 0.15.0. + +

+

+ Returns whether x occurs in arr. + Argument arr may be an array or a string. +

+ +
+
+
+
+ +
+
+
+

+ std.count(arr, x) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Return the number of times that x occurs in arr. +

+ +
+
+
+
+ +
+
+
+

+ std.find(value, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Returns an array that contains the indexes of all occurrences of value in + arr. +

+ +
+
+
+
+ +
+
+
+

+ std.map(func, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Apply the given function to every element of the array to form a new array. +

+ +
+
+
+
+ +
+
+
+

+ std.mapWithIndex(func, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Similar to map above, but it also passes to the function the element's + index in the array. The function func is expected to take the index as the + first parameter and the element as the second. +

+ +
+
+
+
+ +
+
+
+

+ std.filterMap(filter_func, map_func, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ It first filters, then maps the given array, using the two functions provided. +

+ +
+
+
+
+ +
+
+
+

+ std.flatMap(func, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Apply the given function to every element of arr to form a new array then flatten the result. + The argument arr must be an array or a string. If arr is an array, function func must return an array. + If arr is a string, function func must return an string. +

+

+ The std.flatMap function can be thought of as a generalized std.map, + with each element mapped to 0, 1 or more elements. +

+

+ Example: std.flatMap(function(x) [x, x], [1, 2, 3]) yields [ 1, 1, 2, 2, 3, 3 ]. +

+

+ Example: std.flatMap(function(x) if x == 2 then [] else [x], [1, 2, 3]) yields [ 1, 3 ]. +

+

+ Example: std.flatMap(function(x) if x == 2 then [] else [x * 3, x * 2], [1, 2, 3]) yields [ 3, 2, 9, 6 ]. +

+

+ Example: std.flatMap(function(x) x+x, "foo") yields "ffoooo". +

+
+
+
+
+ +
+
+
+

+ std.filter(func, arr) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Return a new array containing all the elements of arr for which the + func function returns true. +

+ +
+
+
+
+ +
+
+
+

+ std.foldl(func, arr, init) +

+
+
+
+
+

- Available since version 0.13.0. + Available since version 0.10.0.

- Decode an array of numbers representing bytes using UTF8. - Returns a string. + Classic foldl function. Calls the function on the result of the previous function call and + each array element, or init in the case of the initial element. Traverses the + array from left to right.

@@ -1580,13 +2133,30 @@

-
-

- Manifestation -

+

+ std.foldr(func, arr, init) +

+
+
+
+
+
+
+
+

+ + Available since version 0.10.0. + +

+

+ Classic foldr function. Calls the function on the result of the previous function call and + each array element, or init in the case of the initial element. Traverses the + array from right to left. +

+
@@ -1595,8 +2165,8 @@

-

- std.manifestIni(ini) +

+ std.range(from, to)

@@ -1611,33 +2181,8 @@

- Convert the given structure to a string in INI format. This - allows using Jsonnet's - object model to build a configuration to be consumed by an application expecting an INI - file. The data is in the form of a set of sections, each containing a key/value mapping. - These examples should make it clear: -

- 
{
-    main: { a: "1", b: "2" },
-    sections: {
-        s1: {x: "11", y: "22", z: "33"},
-        s2: {p: "yes", q: ""},
-        empty: {},
-    }
-}
-

- Yields a string containing this INI file: + Return an array of ascending numbers between the two limits, inclusively.

- 
a = 1
-b = 2
-[empty]
-[s1]
-x = 11
-y = 22
-z = 33
-[s2]
-p = yes
-q =

@@ -1647,8 +2192,8 @@

-

- std.manifestPython(v) +

+ std.repeat(what, count)

@@ -1659,29 +2204,18 @@

- Available since version 0.10.0. + Available since version 0.15.0.

- Convert the given value to a JSON-like form that is compatible with Python. The chief - differences are True / False / None instead of true / false / null. + Repeats an array or a string what a number of times specified by an integer count.

- 
{
-    b: ["foo", "bar"],
-    c: true,
-    d: null,
-    e: { f1: false, f2: 42 },
-}

- Yields a string containing Python code like: + Example: std.repeat([1, 2, 3], 3) yields [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]. +

+

+ Example: std.repeat("blah", 2) yields "blahblah".

- 
{
-    "b": ["foo", "bar"],
-    "c": True,
-    "d": None,
-    "e": {"f1": False, "f2": 42}
-}
-

@@ -1690,8 +2224,8 @@

-

- std.manifestPythonVars(conf) +

+ std.slice(indexable, index, end, step)

@@ -1706,24 +2240,23 @@

- Convert the given object to a JSON-like form that is compatible with Python. The key - difference to std.manifestPython is that the top level is represented as a list - of Python global variables. + Selects the elements of an array or a string from index to end with step and returns an array or a string respectively.

- 
{
-    b: ["foo", "bar"],
-    c: true,
-    d: null,
-    e: { f1: false, f2: 42 },
-}

- Yields a string containing this Python code: + Note that it's recommended to use dedicated slicing syntax both for arrays and strings (e.g. arr[0:4:1] instead of std.slice(arr, 0, 4, 1)). +

+

+ Example: std.slice([1, 2, 3, 4, 5, 6], 0, 4, 1) yields [ 1, 2, 3, 4 ]. +

+

+ Example: std.slice([1, 2, 3, 4, 5, 6], 1, 6, 2) yields [ 2, 4, 6 ]. +

+

+ Example: std.slice("jsonnet", 0, 4, 1) yields "json". +

+

+ Example: std.slice("jsonnet", -3, null, null) yields "net".

- 
b = ["foo", "bar"]
-c = True
-d = None
-e = {"f1": False, "f2": 42}
-

@@ -1732,8 +2265,8 @@

-

- std.manifestJsonEx(value, indent, newline, key_val_sep) +

+ std.join(sep, arr)

@@ -1748,26 +2281,16 @@

- Convert the given object to a JSON form. indent is a string containing - one or more whitespaces that are used for indentation. newline is - by default \n and is inserted where a newline would normally be used - to break long lines. key_val_sep is used to separate the key and value - of an object field: + If sep is a string, then arr must be an array of strings, in which + case they are concatenated with sep used as a delimiter. If sep + is an array, then arr must be an array of arrays, in which case the arrays are + concatenated in the same way, to produce a single array.

- Example: std.manifestJsonEx( - { - x: [1, 2, 3, true, false, null, - "string\nstring"], - y: { a: 1, b: 2, c: [1, 2] }, - }, " ") yields "{\n \"x\": [\n 1,\n 2,\n 3,\n true,\n false,\n null,\n \"string\\nstring\"\n ],\n \"y\": {\n \"a\": 1,\n \"b\": 2,\n \"c\": [\n 1,\n 2\n ]\n }\n}". + Example: std.join(".", ["www", "google", "com"]) yields "www.google.com".

- Example: std.manifestJsonEx( - { - x: [1, 2, "string\nstring"], - y: { a: 1, b: [1, 2] }, - }, "", " ", " : ") yields "{ \"x\" : [ 1, 2, \"string\\nstring\" ], \"y\" : { \"a\" : 1, \"b\" : [ 1, 2 ] } }". + Example: std.join([9, 9], [[1], [2, 3]]) yields [ 1, 9, 9, 2, 3 ].

@@ -1777,8 +2300,8 @@

-

- std.manifestJsonMinified(value) +

+ std.lines(arr)

@@ -1789,21 +2312,14 @@

- Available since version 0.18.0. + Available since version 0.10.0.

- Convert the given object to a minified JSON form. Under the covers, - it calls std.manifestJsonEx:'): -

-

- Example: std.manifestJsonMinified( - { - x: [1, 2, 3, true, false, null, - "string\nstring"], - y: { a: 1, b: 2, c: [1, 2] }, - }) yields "{\"x\":[1,2,3,true,false,null,\"string\\nstring\"],\"y\":{\"a\":1,\"b\":2,\"c\":[1,2]}}". + Concatenate an array of strings into a text file with newline characters after each string. + This is suitable for constructing bash scripts and the like.

+

@@ -1812,8 +2328,8 @@

-

- std.manifestYamlDoc(value, indent_array_in_object=false, quote_keys=true) +

+ std.flattenArrays(arr)

@@ -1828,43 +2344,65 @@

- Convert the given value to a YAML form. Note that std.manifestJson could also - be used for this purpose, because any JSON is also valid YAML. But this function will - produce more canonical-looking YAML. + Concatenate an array of arrays into a single array.

- 
std.manifestYamlDoc(
-  {
-      x: [1, 2, 3, true, false, null,
-          "string\nstring\n"],
-      y: { a: 1, b: 2, c: [1, 2] },
-  },
-  indent_array_in_object=false)

- Yields a string containing this YAML: + Example: std.flattenArrays([[1, 2], [3, 4], [[5, 6], [7, 8]]]) yields [ 1, 2, 3, 4, [ 5, 6 ], [ 7, 8 ] ].

- 
"x":
-  - 1
-  - 2
-  - 3
-  - true
-  - false
-  - null
-  - |
-      string
-      string
-"y":
-  "a": 1
-  "b": 2
-  "c":
-      - 1
-      - 2
+

+
+
+

+ +
+
+
+

+ std.flattenDeepArray(value) +

+
+
+
+
+
+
+

- The indent_array_in_object param adds additional indentation which some people - may find easier to read. + + Available in upcoming release. +

- The quote_keys parameter controls whether YAML identifiers are always quoted - or only when necessary. + Concatenate an array containing values and arrays into a single flattened array. +

+

+ Example: std.flattenDeepArray([[1, 2], [], [3, [4]], [[5, 6, [null]], [7, 8]]]) yields [ 1, 2, 3, 4, 5, 6, null, 7, 8 ]. +

+
+
+
+
+ +
+
+
+

+ std.reverse(arrs) +

+
+
+
+
+
+
+
+

+ + Available since version 0.13.0. + +

+

+ Reverses an array.

@@ -1875,8 +2413,8 @@

-

- std.manifestYamlStream(value, indent_array_in_object=false, c_document_end=false, quote_keys=true) +

+ std.sort(arr, keyF=id)

@@ -1891,29 +2429,11 @@

- Given an array of values, emit a YAML "stream", which is a sequence of documents separated - by --- and ending with .... -

- 
std.manifestYamlStream(
-  ['a', 1, []],
-  indent_array_in_object=false,
-  c_document_end=true)
-

- Yields this string: -

- 
---
-"a"
----
-1
----
-[]
-...
-

- The indent_array_in_object and quote_keys params are the - same as in manifestYamlDoc. + Sorts the array using the <= operator.

- The c_document_end param adds the optional terminating .... + Optional argument keyF is a single argument function used to extract comparison key from each array element. + Default value is identity function keyF=function(x) x.

@@ -1924,8 +2444,8 @@

-

- std.manifestXmlJsonml(value) +

+ std.uniq(arr, keyF=id)

@@ -1940,52 +2460,12 @@

- Convert the given JsonML-encoded value to a string - containing the XML. -

- 
std.manifestXmlJsonml([
-    'svg', { height: 100, width: 100 },
-    [
-        'circle', {
-        cx: 50, cy: 50, r: 40,
-        stroke: 'black', 'stroke-width': 3,
-        fill: 'red',
-        }
-    ],
-])
-

- Yields a string containing this XML (all on one line): -

- 
<svg height="100" width="100">
-    <circle cx="50" cy="50" fill="red" r="40"
-    stroke="black" stroke-width="3"></circle>;
-</svg>;
-

- Which represents the following image: + Removes successive duplicates. When given a sorted array, removes all duplicates.

- - - Sorry, your browser does not support inline SVG. -

- JsonML is designed to preserve "mixed-mode content" (i.e., textual data outside of or next - to elements). This includes the whitespace needed to avoid having all the XML on one line, - which is meaningful in XML. In order to have whitespace in the XML output, it must be - present in the JsonML input: + Optional argument keyF is a single argument function used to extract comparison key from each array element. + Default value is identity function keyF=function(x) x.

- 
std.manifestXmlJsonml([
-    'svg',
-    { height: 100, width: 100 },
-    '\n  ',
-    [
-        'circle',
-        {
-        cx: 50, cy: 50, r: 40, stroke: 'black',
-        'stroke-width': 3, fill: 'red',
-        }
-    ],
-    '\n',
-])

@@ -1995,8 +2475,8 @@

-

- std.manifestTomlEx(toml, indent) +

+ std.all(arr)

@@ -2007,44 +2487,16 @@

- Available since version 0.18.0. + Available since version 0.19.0.

- Convert the given object to a TOML form. indent is a string containing - one or more whitespaces that are used for indentation: + Return true if all elements of arr is true, false otherwise. all([]) evaluates to true.

- Example: std.manifestTomlEx({ - key1: "value", - key2: 1, - section: { - a: 1, - b: "str", - c: false, - d: [1, "s", [2, 3]], - subsection: { - k: "v", - }, - }, - sectionArray: [ - { k: "v1", v: 123 }, - { k: "v2", c: "value2" }, - ], - }, " ") yields "key1 = \"value\"\nkey2 = 1\n\n[section]\n a = 1\n b = \"str\"\n c = false\n d = [\n 1,\n \"s\",\n [ 2, 3 ]\n ]\n\n [section.subsection]\n k = \"v\"\n\n[[sectionArray]]\n k = \"v1\"\n v = 123\n\n[[sectionArray]]\n c = \"value2\"\n k = \"v2\"". + It's an error if 1) arr is not an array, or 2) arr contains non-boolean values.

-
-
-

-
- - -
-
-
-

- Arrays -

+
@@ -2053,8 +2505,8 @@

-

- std.makeArray(sz, func) +

+ std.any(arr)

@@ -2065,17 +2517,16 @@

- Available since version 0.10.0. + Available since version 0.19.0.

- Create a new array of sz elements by calling func(i) to initialize - each element. Func is expected to be a function that takes a single parameter, the index of - the element it should initialize. + Return true if any element of arr is true, false otherwise. any([]) evaluates to false.

- Example: std.makeArray(3,function(x) x * x) yields [ 0, 1, 4 ]. + It's an error if 1) arr is not an array, or 2) arr contains non-boolean values.

+

@@ -2084,8 +2535,8 @@

-

- std.member(arr, x) +

+ std.sum(arr)

@@ -2096,12 +2547,11 @@

- Available since version 0.15.0. + Available since version 0.20.0.

- Returns whether x occurs in arr. - Argument arr may be an array or a string. + Return sum of all element in arr.

@@ -2112,8 +2562,8 @@

-

- std.count(arr, x) +

+ std.minArray(arr, keyF, onEmpty)

@@ -2124,11 +2574,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- Return the number of times that x occurs in arr. + Return the min of all element in arr.

@@ -2139,8 +2589,8 @@

-

- std.find(value, arr) +

+ std.maxArray(arr, keyF, onEmpty)

@@ -2151,12 +2601,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- Returns an array that contains the indexes of all occurrences of value in - arr. + Return the max of all element in arr.

@@ -2167,8 +2616,8 @@

-

- std.map(func, arr) +

+ std.contains(arr, elem)

@@ -2179,11 +2628,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- Apply the given function to every element of the array to form a new array. + Return true if given elem is present in arr, false otherwise.

@@ -2194,8 +2643,8 @@

-

- std.mapWithIndex(func, arr) +

+ std.avg(arr)

@@ -2206,13 +2655,11 @@

- Available since version 0.10.0. + Available since version 0.20.0.

- Similar to map above, but it also passes to the function the element's - index in the array. The function func is expected to take the index as the - first parameter and the element as the second. + Return average of all element in arr.

@@ -2223,8 +2670,8 @@

-

- std.filterMap(filter_func, map_func, arr) +

+ std.remove(arr, elem)

@@ -2235,11 +2682,11 @@

- Available since version 0.10.0. + Available in upcoming release.

- It first filters, then maps the given array, using the two functions provided. + Remove first occurrence of elem from arr.

@@ -2250,8 +2697,8 @@

-

- std.flatMap(func, arr) +

+ std.removeAt(arr, idx)

@@ -2262,41 +2709,25 @@

- Available since version 0.10.0. + Available in upcoming release.

- Apply the given function to every element of arr to form a new array then flatten the result. - The argument arr must be an array or a string. If arr is an array, function func must return an array. - If arr is a string, function func must return an string. -

-

- The std.flatMap function can be thought of as a generalized std.map, - with each element mapped to 0, 1 or more elements. -

-

- Example: std.flatMap(function(x) [x, x], [1, 2, 3]) yields [ 1, 1, 2, 2, 3, 3 ]. -

-

- Example: std.flatMap(function(x) if x == 2 then [] else [x], [1, 2, 3]) yields [ 1, 3 ]. -

-

- Example: std.flatMap(function(x) if x == 2 then [] else [x * 3, x * 2], [1, 2, 3]) yields [ 3, 2, 9, 6 ]. -

-

- Example: std.flatMap(function(x) x+x, "foo") yields "ffoooo". + Remove element at idx index from arr.

+

+
-

- std.filter(func, arr) -

+

+ Sets +

@@ -2305,15 +2736,18 @@

- - Available since version 0.10.0. - + Sets are represented as ordered arrays without duplicates.

- Return a new array containing all the elements of arr for which the - func function returns true. + Note that the std.set* functions rely on the uniqueness and ordering + on arrays passed to them to work. This can be guaranteed by using std.set(arr). + If that is not the case, the functions will quietly return non-meaningful results. +

+

+ All set.set* functions accept keyF function of one argument, which can be + used to extract key to use from each element. All Set operations then use extracted key for the purpose + of identifying uniqueness. Default value is identity function local id = function(x) x.

-
@@ -2322,8 +2756,8 @@

-

- std.foldl(func, arr, init) +

+ std.set(arr, keyF=id)

@@ -2338,9 +2772,7 @@

- Classic foldl function. Calls the function on the result of the previous function call and - each array element, or init in the case of the initial element. Traverses the - array from left to right. + Shortcut for std.uniq(std.sort(arr)).

@@ -2351,8 +2783,8 @@

-

- std.foldr(func, arr, init) +

+ std.setInter(a, b, keyF=id)

@@ -2367,9 +2799,7 @@

- Classic foldr function. Calls the function on the result of the previous function call and - each array element, or init in the case of the initial element. Traverses the - array from right to left. + Set intersection operation (values in both a and b).

@@ -2380,8 +2810,8 @@

-

- std.range(from, to) +

+ std.setUnion(a, b, keyF=id)

@@ -2396,9 +2826,17 @@

- Return an array of ascending numbers between the two limits, inclusively. + Set union operation (values in any of a or b). Note that + on sets will simply + concatenate + the arrays, possibly forming an array that is not a set (due to not being ordered without + duplicates). +

+

+ Example: std.setUnion([1, 2], [2, 3]) yields [ 1, 2, 3 ]. +

+

+ Example: std.setUnion([{n:"A", v:1}, {n:"B"}], [{n:"A", v: 9999}, {n:"C"}], keyF=function(x) x.n) yields [ { "n": "A", "v": 1 }, { "n": "B" }, { "n": "C" } ].

-

@@ -2407,8 +2845,8 @@

-

- std.repeat(what, count) +

+ std.setDiff(a, b, keyF=id)

@@ -2416,21 +2854,16 @@

-
-

- - Available since version 0.15.0. - -

-

- Repeats an array or a string what a number of times specified by an integer count. -

+

- Example: std.repeat([1, 2, 3], 3) yields [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]. + + Available since version 0.10.0. +

- Example: std.repeat("blah", 2) yields "blahblah". + Set difference operation (values in a but not b).

+
@@ -2439,8 +2872,8 @@

-

- std.slice(indexable, index, end, step) +

+ std.setMember(x, arr, keyF=id)

@@ -2455,30 +2888,31 @@

- Selects the elements of an array or a string from index to end with step and returns an array or a string respectively. -

-

- Note that it's recommended to use dedicated slicing syntax both for arrays and strings (e.g. arr[0:4:1] instead of std.slice(arr, 0, 4, 1)). -

-

- Example: std.slice([1, 2, 3, 4, 5, 6], 0, 4, 1) yields [ 1, 2, 3, 4 ]. -

-

- Example: std.slice([1, 2, 3, 4, 5, 6], 1, 6, 2) yields [ 2, 4, 6 ]. -

-

- Example: std.slice("jsonnet", 0, 4, 1) yields "json". + Returns true if x is a member of array, otherwise false.

+

+
-

- std.join(sep, arr) +

+ Objects +

+
+
+
+
+ +
+
+
+

+ std.get(o, f, default=null, inc_hidden=true)

@@ -2489,21 +2923,14 @@

- Available since version 0.10.0. + Available since version 0.18.0.

- If sep is a string, then arr must be an array of strings, in which - case they are concatenated with sep used as a delimiter. If sep - is an array, then arr must be an array of arrays, in which case the arrays are - concatenated in the same way, to produce a single array. -

-

- Example: std.join(".", ["www", "google", "com"]) yields "www.google.com". -

-

- Example: std.join([9, 9], [[1], [2, 3]]) yields [ 1, 9, 9, 2, 3 ]. + Returns the object's field if it exists or default value otherwise. + inc_hidden controls whether to include hidden fields.

+

@@ -2512,8 +2939,8 @@

-

- std.lines(arr) +

+ std.objectHas(o, f)

@@ -2528,8 +2955,9 @@

- Concatenate an array of strings into a text file with newline characters after each string. - This is suitable for constructing bash scripts and the like. + Returns true if the given object has the field (given as a string), otherwise + false. Raises an error if the arguments are not object and string + respectively. Returns false if the field is hidden.

@@ -2540,8 +2968,8 @@

-

- std.flattenArrays(arr) +

+ std.objectFields(o)

@@ -2556,11 +2984,10 @@

- Concatenate an array of arrays into a single array. -

-

- Example: std.flattenArrays([[1, 2], [3, 4], [[5, 6], [7, 8]]]) yields [ 1, 2, 3, 4, [ 5, 6 ], [ 7, 8 ] ]. + Returns an array of strings, each element being a field from the given object. Does not include + hidden fields.

+

@@ -2569,8 +2996,8 @@

-

- std.reverse(arrs) +

+ std.objectValues(o)

@@ -2581,11 +3008,11 @@

- Available since version 0.13.0. + Available since version 0.17.0.

- Reverses an array. + Returns an array of the values in the given object. Does not include hidden fields.

@@ -2596,8 +3023,8 @@

-

- std.sort(arr, keyF=id) +

+ std.objectKeysValues(o)

@@ -2608,15 +3035,12 @@

- Available since version 0.10.0. + Available since version 0.20.0.

- Sorts the array using the <= operator. -

-

- Optional argument keyF is a single argument function used to extract comparison key from each array element. - Default value is identity function keyF=function(x) x. + Returns an array of objects from the given object, each object having two fields: + key (string) and value (object). Does not include hidden fields.

@@ -2627,8 +3051,8 @@

-

- std.uniq(arr, keyF=id) +

+ std.objectHasAll(o, f)

@@ -2643,11 +3067,7 @@

- Removes successive duplicates. When given a sorted array, removes all duplicates. -

-

- Optional argument keyF is a single argument function used to extract comparison key from each array element. - Default value is identity function keyF=function(x) x. + As std.objectHas but also includes hidden fields.

@@ -2658,8 +3078,8 @@

-

- std.all(arr) +

+ std.objectFieldsAll(o)

@@ -2670,14 +3090,11 @@

- Available since version 0.19.0. + Available since version 0.10.0.

- Return true if all elements of arr is true, false otherwise. all([]) evaluates to true. -

-

- It's an error if 1) arr is not an array, or 2) arr contains non-boolean values. + As std.objectFields but also includes hidden fields.

@@ -2688,8 +3105,8 @@

-

- std.any(arr) +

+ std.objectValuesAll(o)

@@ -2700,14 +3117,11 @@

- Available since version 0.19.0. + Available since version 0.17.0.

- Return true if any element of arr is true, false otherwise. any([]) evaluates to false. -

-

- It's an error if 1) arr is not an array, or 2) arr contains non-boolean values. + As std.objectValues but also includes hidden fields.

@@ -2718,8 +3132,8 @@

-

- std.sum(arr) +

+ std.objectKeysValuesAll(o)

@@ -2734,7 +3148,7 @@

- Return sum of all element in arr. + As std.objectKeysValues but also includes hidden fields.

@@ -2742,13 +3156,12 @@

-
-

- Sets -

+

+ std.objectRemoveKey(obj, key) +

@@ -2757,18 +3170,14 @@

- Sets are represented as ordered arrays without duplicates. -

-

- Note that the std.set* functions rely on the uniqueness and ordering - on arrays passed to them to work. This can be guaranteed by using std.set(arr). - If that is not the case, the functions will quietly return non-meaningful results. + + Available in upcoming release. +

- All set.set* functions accept keyF function of one argument, which can be - used to extract key to use from each element. All Set operations then use extracted key for the purpose - of identifying uniqueness. Default value is identity function local id = function(x) x. + Returns a new object after removing the given key from object.

+
@@ -2777,8 +3186,8 @@

-

- std.set(arr, keyF=id) +

+ std.mapWithKey(func, obj)

@@ -2793,7 +3202,9 @@

- Shortcut for std.uniq(std.sort(arr)). + Apply the given function to all fields of the given object, also passing + the field name. The function func is expected to take the + field name as the first parameter and the field value as the second.

@@ -2801,11 +3212,23 @@

+
-

- std.setInter(a, b, keyF=id) +

+ Encoding +

+
+
+
+
+ +
+
+
+

+ std.base64(input)

@@ -2820,7 +3243,11 @@

- Set intersection operation (values in both a and b). + Encodes the given value into a base64 string. The encoding sequence is A-Za-z0-9+/ with + = + to pad the output to a multiple of 4 characters. The value can be a string or an array of + numbers, but the codepoints / numbers must be in the 0 to 255 range. The resulting string + has no line breaks.

@@ -2831,8 +3258,8 @@

-

- std.setUnion(a, b, keyF=id) +

+ std.base64DecodeBytes(str)

@@ -2847,17 +3274,11 @@

- Set union operation (values in any of a or b). Note that + on sets will simply - concatenate - the arrays, possibly forming an array that is not a set (due to not being ordered without - duplicates). -

-

- Example: std.setUnion([1, 2], [2, 3]) yields [ 1, 2, 3 ]. -

-

- Example: std.setUnion([{n:"A", v:1}, {n:"B"}], [{n:"A", v: 9999}, {n:"C"}], keyF=function(x) x.n) yields [ { "n": "A", "v": 1 }, { "n": "B" }, { "n": "C" } ]. + Decodes the given base64 string into an array of bytes (number values). Currently assumes + the input string has no linebreaks and is padded to a multiple of 4 (with the = character). + In other words, it consumes the output of std.base64().

+

@@ -2866,8 +3287,8 @@

-

- std.setDiff(a, b, keyF=id) +

+ std.base64Decode(str)

@@ -2882,7 +3303,10 @@

- Set difference operation (values in a but not b). + Deprecated, use std.base64DecodeBytes and decode the string explicitly (e.g. with std.decodeUTF8) instead. +

+

+ Behaves like std.base64DecodeBytes() except returns a naively encoded string instead of an array of bytes.

@@ -2893,8 +3317,8 @@

-

- std.setMember(x, arr, keyF=id) +

+ std.md5(s)

@@ -2909,7 +3333,7 @@

- Returns true if x is a member of array, otherwise false. + Encodes the given value into an MD5 string.

@@ -2917,23 +3341,11 @@

- -
-
-
-

- Encoding -

-
-
-
-
-
-

- std.base64(input) +

+ std.sha1(s)

@@ -2944,15 +3356,14 @@

- Available since version 0.10.0. + Available in upcoming release.

- Encodes the given value into a base64 string. The encoding sequence is A-Za-z0-9+/ with - = - to pad the output to a multiple of 4 characters. The value can be a string or an array of - numbers, but the codepoints / numbers must be in the 0 to 255 range. The resulting string - has no line breaks. + Encodes the given value into an SHA1 string. +

+

+ This function is only available in Go version of jsonnet.

@@ -2963,8 +3374,8 @@

-

- std.base64DecodeBytes(str) +

+ std.sha256(s)

@@ -2975,13 +3386,14 @@

- Available since version 0.10.0. + Available in upcoming release.

- Decodes the given base64 string into an array of bytes (number values). Currently assumes - the input string has no linebreaks and is padded to a multiple of 4 (with the = character). - In other words, it consumes the output of std.base64(). + Encodes the given value into an SHA256 string. +

+

+ This function is only available in Go version of jsonnet.

@@ -2992,8 +3404,8 @@

-

- std.base64Decode(str) +

+ std.sha512(s)

@@ -3004,14 +3416,14 @@

- Available since version 0.10.0. + Available in upcoming release.

- Deprecated, use std.base64DecodeBytes and decode the string explicitly (e.g. with std.decodeUTF8) instead. + Encodes the given value into an SHA512 string.

- Behaves like std.base64DecodeBytes() except returns a naively encoded string instead of an array of bytes. + This function is only available in Go version of jsonnet.

@@ -3022,8 +3434,8 @@

-

- std.md5(s) +

+ std.sha3(s)

@@ -3034,11 +3446,14 @@

- Available since version 0.10.0. + Available in upcoming release.

- Encodes the given value into an MD5 string. + Encodes the given value into an SHA3 string. +

+

+ This function is only available in Go version of jsonnet.