Merge pull request #1043 from Gijsreyn/add-reference-array-functions

michaeltlombardi · web-flow · commit a9092309ef6c · 2025-08-12T13:39:44.000Z
Add reference documentation for array functions
diff --git a/docs/reference/schemas/config/functions/array.md b/docs/reference/schemas/config/functions/array.md
@@ -0,0 +1,190 @@
+---
+description: Reference for the 'array' DSC configuration document function
+ms.date:     08/12/2025
+ms.topic:    reference
+title:       array
+---
+
+# array
+
+## Synopsis
+
+Creates an array from the given elements (strings, numbers, arrays, or objects).
+
+## Syntax
+
+```Syntax
+array(<element1>, <element2>, ...)
+```
+
+## Description
+
+The `array()` function creates an array from the provided arguments, allowing
+mixed data types within the same array. Unlike `createArray()` which requires
+all elements to be the same type, `array()` accepts any combination of strings,
+numbers, arrays, and objects as arguments.
+
+This function is useful when you need to combine different types of data into a
+single collection, such as mixing configuration values, computed results, and
+structured metadata in deployment scenarios.
+
+## Examples
+
+### Example 1 - Build a deployment plan
+
+This example demonstrates combining different data types to create a comprehensive
+deployment configuration. The array contains an existing server list, a numeric
+batch size, and a configuration object with deployment strategy details.
+
+```yaml
+# array.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+parameters:
+  webServers:
+    type: array
+    defaultValue:
+    - web01
+    - web02
+  batchSize:
+    type: int
+    defaultValue: 2
+resources:
+- name: Deployment Plan
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output: "[array(parameters('webServers'), parameters('batchSize'), createObject('strategy', 'blue-green'))]"
+```
+
+```bash
+dsc config get --file array.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Deployment Plan
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+      - - web01
+        - web02
+      - 2
+      - strategy: blue-green
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Compose mixed telemetry payload parts
+
+This example shows how to construct a telemetry payload by combining a string
+identifier, structured metadata object, and numeric status code into a single
+array for logging or monitoring systems.
+
+```yaml
+# array.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+parameters:
+  correlationId:
+    type: string
+    defaultValue: ABC123
+resources:
+- name: Telemetry Payload
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      payload: "[array(parameters('correlationId'), createObject('severity', 'info'), 200)]"
+```
+
+```bash
+dsc config get --file array.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Telemetry Payload
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        payload:
+        - ABC123
+        - severity: info
+        - 200
+messages: []
+hadErrors: false
+```
+
+### Example 3 - Combine generated and literal collections
+
+This example demonstrates nesting arrays and objects within a parent array,
+showing how `array()` can combine results from other DSC functions like
+`createArray()` and `createObject()` with literal values.
+
+```yaml
+# array.example.3.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Combined Collections
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      combined: "[array(createArray('a','b'), array(1,2), createObject('k','v'))]"
+```
+
+```bash
+dsc config get --file array.example.3.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Combined Collections
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        combined:
+        - - a
+          - b
+        - - 1
+          - 2
+        - k: v
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### element1, element2, ...
+
+The elements to include in the array.
+
+```yaml
+Type:         string, number, array, or object
+Required:     false
+Multiplicity: 0 or more
+```
+
+Each element provided as an argument will be added to the resulting array in the
+order specified. All elements must be one of the four accepted types: string,
+number (integer), array, or object. Boolean and null values are not supported.
+
+## Output
+
+Returns a new array containing the provided elements in order.
+
+```yaml
+Type: array
+```
+
+## Related functions
+
+- [`createArray()`][00] - Creates a homogeneous array (all elements same type)
+- [`createObject()`][01] - Builds an object from key/value pairs
+- [`first()`][02] - Gets the first element from an array
+- [`indexOf()`][03] - Finds the index of an item in an array
+
+<!-- Link reference definitions -->
+[00]: ./createArray.md
+[01]: ./createObject.md
+[02]: ./first.md
+[03]: ./indexOf.md
diff --git a/docs/reference/schemas/config/functions/first.md b/docs/reference/schemas/config/functions/first.md
@@ -0,0 +1,176 @@
+---
+description: Reference for the 'first' DSC configuration document function
+ms.date:     08/12/2025
+ms.topic:    reference
+title:       first
+---
+
+# first
+
+## Synopsis
+
+Returns the first element of an array or the first character of a string.
+
+## Syntax
+
+```Syntax
+first(<arrayOrString>)
+```
+
+## Description
+
+The `first()` function extracts the first element from an array or the first
+character from a string. When used with arrays, it returns the actual first
+element preserving its original data type (string, number, array, or object).
+When used with strings, it returns a new single-character string containing
+the first Unicode character.
+
+This function is particularly useful for accessing the primary or default item
+from a collection, or extracting prefixes from identifiers and codes. The
+function will return an error if the input array or string is empty.
+
+## Examples
+
+### Example 1 - Get the first server hostname
+
+This example shows how to extract the primary server from a list of servers,
+which could be useful for identifying the lead server in a cluster or getting
+the default target for deployment operations.
+
+```yaml
+# first.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+parameters:
+  servers:
+    type: array
+    defaultValue:
+    - web01
+    - web02
+resources:
+- name: First Server
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      firstServer: "[first(parameters('servers'))]"
+```
+
+```bash
+dsc config get --file first.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: First Server
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        firstServer: web01
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Extract leading character for a prefix
+
+This example demonstrates extracting the first character from an environment
+code to create abbreviated prefixes for resource naming or tagging schemes.
+
+```yaml
+# first.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+parameters:
+  environmentCode:
+    type: string
+    defaultValue: Prod
+resources:
+- name: Prefix Builder
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      prefix: "[first(parameters('environmentCode'))]"
+```
+
+```bash
+dsc config get --file first.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Prefix Builder
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        prefix: P
+messages: []
+hadErrors: false
+```
+
+### Example 3 - Chain with array construction
+
+This example shows how `first()` can be combined with `array()` to get the
+first element from a dynamically constructed array containing mixed data types.
+
+```yaml
+# first.example.3.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Chained Example
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      firstMixed: "[first(array(createArray('a','b'), createObject('k','v')))]"
+```
+
+```bash
+dsc config get --file first.example.3.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Chained Example
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        firstMixed:
+        - a
+        - b
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### input
+
+The array or string to extract the first element or character from.
+
+```yaml
+Type:     array or string
+Required: true
+```
+
+If the input is an array, the first element is returned with its original data
+type preserved. If the input is a string, the first Unicode character is
+returned as a new string. Empty arrays and empty strings will result in an
+error.
+
+## Output
+
+Returns the first element or character.
+
+```yaml
+Type: string | number | array | object
+```
+
+## Related functions
+
+- [`array()`][00] - Creates an array from heterogeneous elements
+- [`createArray()`][01] - Creates a homogeneous array
+- [`indexOf()`][02] - Finds the index of an item in an array
+
+<!-- Link reference definitions -->
+[00]: ./array.md
+[01]: ./createArray.md
+[02]: ./indexOf.md
diff --git a/docs/reference/schemas/config/functions/indexOf.md b/docs/reference/schemas/config/functions/indexOf.md
