Object functions for Bicep

This article describes the Bicep functions for working with objects.

contains

contains(container, itemToFind)

Checks whether an array contains a value, an object contains a key, or a string contains a substring. The string comparison is case-sensitive. However, when testing if an object contains a key, the comparison is case-insensitive.

Namespace: sys.

Parameters

Parameter Required Type Description
container Yes array, object, or string The value that contains the value to find.
itemToFind Yes string or int The value to find.

Return value

True if the item is found; otherwise, False.

Example

The following example shows how to use contains with different types:

param stringToTest string = 'OneTwoThree'
param objectToTest object = {
  'one': 'a'
  'two': 'b'
  'three': 'c'
}
param arrayToTest array = [
  'one'
  'two'
  'three'
]

output stringTrue bool = contains(stringToTest, 'e')
output stringFalse bool = contains(stringToTest, 'z')
output objectTrue bool = contains(objectToTest, 'one')
output objectFalse bool = contains(objectToTest, 'a')
output arrayTrue bool = contains(arrayToTest, 'three')
output arrayFalse bool = contains(arrayToTest, 'four')

The output from the preceding example with the default values is:

Name Type Value
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

empty

empty(itemToTest)

Determines if an array, object, or string is empty.

Namespace: sys.

Parameters

Parameter Required Type Description
itemToTest Yes array, object, or string The value to check if it's empty.

Return value

Returns True if the value is empty; otherwise, False.

Example

The following example checks whether an array, object, and string are empty.

param testArray array = []
param testObject object = {}
param testString string = ''

output arrayEmpty bool = empty(testArray)
output objectEmpty bool = empty(testObject)
output stringEmpty bool = empty(testString)

The output from the preceding example with the default values is:

Name Type Value
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool True

intersection

intersection(arg1, arg2, arg3, ...)

Returns a single array or object with the common elements from the parameters.

Namespace: sys.

Parameters

Parameter Required Type Description
arg1 Yes array or object The first value to use for finding common elements.
arg2 Yes array or object The second value to use for finding common elements.
additional arguments No array or object Additional values to use for finding common elements.

Return value

An array or object with the common elements.

Example

The following example shows how to use intersection with arrays and objects:

param firstObject object = {
  'one': 'a'
  'two': 'b'
  'three': 'c'
}
param secondObject object = {
  'one': 'a'
  'two': 'z'
  'three': 'c'
}
param firstArray array = [
  'one'
  'two'
  'three'
]
param secondArray array = [
  'two'
  'three'
]

output objectOutput object = intersection(firstObject, secondObject)
output arrayOutput array = intersection(firstArray, secondArray)

The output from the preceding example with the default values is:

Name Type Value
objectOutput Object {"one": "a", "three": "c"}
arrayOutput Array ["two", "three"]

json

json(arg1)

Converts a valid JSON string into a JSON data type.

Namespace: sys.

Parameters

Parameter Required Type Description
arg1 Yes string The value to convert to JSON. The string must be a properly formatted JSON string.

Return value

The JSON data type from the specified string, or an empty value when null is specified.

Remarks

If you need to include a parameter value or variable in the JSON object, use the concat function to create the string that you pass to the function.

Example

The following example shows how to use the json function. Notice that you can pass in null for an empty object.

param jsonEmptyObject string = 'null'
param jsonObject string = '{\'a\': \'b\'}'
param jsonString string = '\'test\''
param jsonBoolean string = 'true'
param jsonInt string = '3'
param jsonArray string = '[[1,2,3]]'
param concatValue string = 'demo value'

output emptyObjectOutput bool = empty(json(jsonEmptyObject))
output objectOutput object = json(jsonObject)
output stringOutput string =json(jsonString)
output booleanOutput bool = json(jsonBoolean)
output intOutput int = json(jsonInt)
output arrayOutput array = json(jsonArray)
output concatObjectOutput object = json(concat('{"a": "', concatValue, '"}'))

The output from the preceding example with the default values is:

Name Type Value
emptyObjectOutput Boolean True
objectOutput Object {"a": "b"}
stringOutput String test
booleanOutput Boolean True
intOutput Integer 3
arrayOutput Array [ 1, 2, 3 ]
concatObjectOutput Object { "a": "demo value" }

length

length(arg1)

Returns the number of elements in an array, characters in a string, or root-level properties in an object.

Namespace: sys.

Parameters

Parameter Required Type Description
arg1 Yes array, string, or object The array to use for getting the number of elements, the string to use for getting the number of characters, or the object to use for getting the number of root-level properties.

Return value

An int.

Example

The following example shows how to use length with an array and string:

param arrayToTest array = [
  'one'
  'two'
  'three'
]
param stringToTest string = 'One Two Three'
param objectToTest object = {
  'propA': 'one'
  'propB': 'two'
  'propC': 'three'
  'propD': {
      'propD-1': 'sub'
      'propD-2': 'sub'
  }
}

output arrayLength int = length(arrayToTest)
output stringLength int = length(stringToTest)
output objectLength int = length(objectToTest)

The output from the preceding example with the default values is:

Name Type Value
arrayLength Int 3
stringLength Int 13
objectLength Int 4

union

union(arg1, arg2, arg3, ...)

Returns a single array or object with all elements from the parameters. Duplicate values or keys are only included once.

Namespace: sys.

Parameters

Parameter Required Type Description
arg1 Yes array or object The first value to use for joining elements.
arg2 Yes array or object The second value to use for joining elements.
additional arguments No array or object Additional values to use for joining elements.

Return value

An array or object.

Example

The following example shows how to use union with arrays and objects:

param firstObject object = {
  'one': 'a'
  'two': 'b'
  'three': 'c1'
}

param secondObject object = {
  'three': 'c2'
  'four': 'd'
  'five': 'e'
}

param firstArray array = [
  'one'
  'two'
  'three'
]

param secondArray array = [
  'three'
  'four'
]

output objectOutput object = union(firstObject, secondObject)
output arrayOutput array = union(firstArray, secondArray)

The output from the preceding example with the default values is:

Name Type Value
objectOutput Object {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput Array ["one", "two", "three", "four"]

Next steps