qsharp-lang 1.1.3 → 1.1.5-dev

package/docs/Microsoft.Quantum.Arrays/Any.md

@@ -0,0 +1,41 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Any
+title: Any function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Any
+qsharp.summary: Given an array and a predicate that is defined for the elements of the array, checks if at least one element of the array satisfies the predicate.
+---
+
+# Any function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Any<'T>(predicate : ('T -> Bool), array : 'T[]) : Bool
+```
+
+## Summary
+Given an array and a predicate that is defined
+for the elements of the array, checks if at least one element of
+the array satisfies the predicate.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### predicate
+A function from `'T` to `Bool` that is used to check elements.
+### array
+An array of elements over `'T`.
+
+## Output
+A `Bool` value of the OR function of the predicate applied to all elements.
+
+## Example
+```qsharp
+let anyEven = Any(x -> x % 2 == 0, [1, 3, 6, 7, 9]);
+```

package/docs/Microsoft.Quantum.Arrays/Chunks.md

@@ -0,0 +1,34 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Chunks
+title: Chunks function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Chunks
+qsharp.summary: Splits an array into multiple parts of equal length.
+---
+
+# Chunks function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Chunks<'T>(chunkSize : Int, array : 'T[]) : 'T[][]
+```
+
+## Summary
+Splits an array into multiple parts of equal length.
+
+## Input
+### chunkSize
+The length of each chunk. Must be positive.
+### array
+The array to be split in chunks.
+
+## Output
+A array containing each chunk of the original array.
+
+## Remarks
+Note that the last element of the output may be shorter
+than `chunkSize` if `Length(array)` is not divisible by `chunkSize`.

package/docs/Microsoft.Quantum.Arrays/CircularlyShifted.md

@@ -0,0 +1,46 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.CircularlyShifted
+title: CircularlyShifted function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: CircularlyShifted
+qsharp.summary: Shift an array circularly left or right by a specific step size.
+---
+
+# CircularlyShifted function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function CircularlyShifted<'T>(stepCount : Int, array : 'T[]) : 'T[]
+```
+
+## Summary
+Shift an array circularly left or right by a specific step size.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### stepCount
+The amount of positions by which the array elements will be shifted.
+If this is positive, `array` is circularly shifted to the right.
+If this is negative, `array` is circularly shifted to the left.
+### array
+Array to be circularly shifted.
+
+## Output
+An array `output` that is the `array` circularly shifted to the right or left
+by the specified step size.
+
+## Example
+```qsharp
+let array = [10, 11, 12];
+// The following line returns [11, 12, 10].
+let output = CircularlyShifted(2, array);
+// The following line returns [12, 10, 11].
+let output = CircularlyShifted(-2, array);
+```

package/docs/Microsoft.Quantum.Arrays/ColumnAt.md

@@ -0,0 +1,47 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.ColumnAt
+title: ColumnAt function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: ColumnAt
+qsharp.summary: Extracts a column from a matrix.
+---
+
+# ColumnAt function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function ColumnAt<'T>(column : Int, matrix : 'T[][]) : 'T[]
+```
+
+## Summary
+Extracts a column from a matrix.
+
+## Description
+This function extracts a column in a matrix in row-wise order.
+Extracting a row corresponds to element access of the first index
+and therefore requires no further treatment.
+
+## Type Parameters
+### 'T
+The type of each element of `matrix`.
+
+## Input
+### column
+Column of the matrix
+### matrix
+2-dimensional matrix in row-wise order
+
+## Example
+```qsharp
+let matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+let column = ColumnAt(0, matrix);
+// same as: column = [1, 4, 7]
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Transposed
+- Microsoft.Quantum.Arrays.Diagonal

package/docs/Microsoft.Quantum.Arrays/Count.md

@@ -0,0 +1,42 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Count
+title: Count function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Count
+qsharp.summary: Given an array and a predicate that is defined for the elements of the array, returns the number of elements an array that consists of those elements that satisfy the predicate.
+---
+
+# Count function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Count<'T>(predicate : ('T -> Bool), array : 'T[]) : Int
+```
+
+## Summary
+Given an array and a predicate that is defined
+for the elements of the array, returns the number of elements
+an array that consists of those elements that satisfy the predicate.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### predicate
+A function from `'T` to Boolean that is used to filter elements.
+### array
+An array of elements over `'T`.
+
+## Output
+The number of elements in `array` that satisfy the predicate.
+
+## Example
+```qsharp
+ let evensCount = Count(x -> x % 2 == 0, [1, 3, 6, 7, 9]);
+// evensCount is 1.
+```

package/docs/Microsoft.Quantum.Arrays/Diagonal.md

@@ -0,0 +1,43 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Diagonal
+title: Diagonal function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Diagonal
+qsharp.summary: Returns an array of diagonal elements of a 2-dimensional array
+---
+
+# Diagonal function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Diagonal<'T>(matrix : 'T[][]) : 'T[]
+```
+
+## Summary
+Returns an array of diagonal elements of a 2-dimensional array
+
+## Description
+If the 2-dimensional array has not a square shape, the diagonal over
+the minimum over the number of rows and columns will be returned.
+
+## Type Parameters
+### 'T
+The type of each element of `matrix`.
+
+## Input
+### matrix
+2-dimensional matrix in row-wise order.
+
+## Example
+```qsharp
+let matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+let diagonal = Diagonal(matrix);
+// same as: column = [1, 5, 9]
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Transposed

package/docs/Microsoft.Quantum.Arrays/DrawMany.md

@@ -0,0 +1,43 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.DrawMany
+title: DrawMany operation
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: operation
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: DrawMany
+qsharp.summary: Repeats an operation for a given number of samples, collecting its outputs in an array.
+---
+
+# DrawMany operation
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+operation DrawMany<'TInput, 'TOutput>(op : ('TInput => 'TOutput), nSamples : Int, input : 'TInput) : 'TOutput[]
+```
+
+## Summary
+Repeats an operation for a given number of samples, collecting its outputs
+in an array.
+
+## Input
+### op
+The operation to be called repeatedly.
+### nSamples
+The number of samples of calling `op` to collect.
+### input
+The input to be passed to `op`.
+
+## Type Parameters
+### TInput
+The type of input expected by `op`.
+### TOutput
+The type of output returned by `op`.
+
+## Example
+The following samples an alternating array of results.
+```qsharp
+use qubit = Qubit();
+let results = Microsoft.Quantum.Arrays.DrawMany(q => {X(q); M(q)}, 3, qubit);
+```

package/docs/Microsoft.Quantum.Arrays/Enumerated.md

@@ -0,0 +1,44 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Enumerated
+title: Enumerated function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Enumerated
+qsharp.summary: Given an array, returns a new array containing elements of the original array along with the indices of each element.
+---
+
+# Enumerated function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Enumerated<'TElement>(array : 'TElement[]) : (Int, 'TElement)[]
+```
+
+## Summary
+Given an array, returns a new array containing elements of the original
+array along with the indices of each element.
+
+## Type Parameters
+### 'TElement
+The type of elements of the array.
+
+## Input
+### array
+An array whose elements are to be enumerated.
+
+## Output
+A new array containing elements of the original array along with their
+indices.
+
+## Example
+The following `for` loops are equivalent:
+```qsharp
+for (idx in IndexRange(array)) {
+    let element = array[idx];
+    ...
+}
+for ((idx, element) in Enumerated(array)) { ... }
+```

package/docs/Microsoft.Quantum.Arrays/Excluding.md

@@ -0,0 +1,46 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Excluding
+title: Excluding function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Excluding
+qsharp.summary: Returns an array containing the elements of another array, excluding elements at a given list of indices.
+---
+
+# Excluding function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Excluding<'T>(remove : Int[], array : 'T[]) : 'T[]
+```
+
+## Summary
+Returns an array containing the elements of another array,
+excluding elements at a given list of indices.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### remove
+An array of indices denoting which elements should be excluded.
+from the output.
+### array
+Array of which the values in the output array are taken.
+
+## Output
+An array `output` such that `output[0]` is the first element
+of `array` whose index does not appear in `remove`,
+such that `output[1]` is the second such element, and so
+forth.
+
+## Example
+```qsharp
+let array = [10, 11, 12, 13, 14, 15];
+// The following line returns [10, 12, 15].
+let subarray = Excluding([1, 3, 4], array);
+```

package/docs/Microsoft.Quantum.Arrays/Filtered.md

@@ -0,0 +1,42 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Filtered
+title: Filtered function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Filtered
+qsharp.summary: Given an array and a predicate that is defined for the elements of the array, returns an array that consists of those elements that satisfy the predicate.
+---
+
+# Filtered function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Filtered<'T>(predicate : ('T -> Bool), array : 'T[]) : 'T[]
+```
+
+## Summary
+Given an array and a predicate that is defined
+for the elements of the array, returns an array that consists of
+those elements that satisfy the predicate.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### predicate
+A function from `'T` to Boolean that is used to filter elements.
+### array
+An array of elements over `'T`.
+
+## Output
+An array `'T[]` of elements that satisfy the predicate.
+
+## Example
+The following code creates an array that contains only even numbers.
+```qsharp
+Filtered(x -> x % 2 == 0, [0, 1, 2, 3, 4])
+```

package/docs/Microsoft.Quantum.Arrays/FlatMapped.md

@@ -0,0 +1,45 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.FlatMapped
+title: FlatMapped function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: FlatMapped
+qsharp.summary: Given an array and a function that maps an array element to some output array, returns the concatenated output arrays for each array element.
+---
+
+# FlatMapped function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function FlatMapped<'TInput, 'TOutput>(mapper : ('TInput -> 'TOutput[]), array : 'TInput[]) : 'TOutput[]
+```
+
+## Summary
+Given an array and a function that maps an array element to some output
+array, returns the concatenated output arrays for each array element.
+
+## Type Parameters
+### 'TInput
+The type of `array` elements.
+### 'TOutput
+The `mapper` function returns arrays of this type.
+
+## Input
+### mapper
+A function from `'TInput` to `'TOutput[]` that is used to map array elements.
+### array
+An array of elements.
+
+## Output
+An array of `'TOutput[]` which is the concatenation of all arrays generated by
+the mapping function.
+
+## Example
+The following code creates an array with each element of the input array repeated twice.
+```qsharp
+let repeatedPairs = FlatMapped(x -> Repeated(x, 2), [1, 2, 3]);
+// repeatedPairs is [1, 1, 2, 2, 3, 3].
+```

package/docs/Microsoft.Quantum.Arrays/Flattened.md

@@ -0,0 +1,38 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Flattened
+title: Flattened function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Flattened
+qsharp.summary: Given an array of arrays, returns the concatenation of all arrays.
+---
+
+# Flattened function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Flattened<'T>(arrays : 'T[][]) : 'T[]
+```
+
+## Summary
+Given an array of arrays, returns the concatenation of all arrays.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### arrays
+Array of arrays.
+
+## Output
+Concatenation of all arrays.
+
+## Example
+```qsharp
+let flattened = Flattened([[1, 2], [3], [4, 5, 6]]);
+// flattened = [1, 2, 3, 4, 5, 6]
+```

package/docs/Microsoft.Quantum.Arrays/Fold.md

@@ -0,0 +1,46 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Fold
+title: Fold function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Fold
+qsharp.summary: Iterates a function `f` through an array `array`, returning `f(...f(f(initialState, array[0]), array[1]), ...)`.
+---
+
+# Fold function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Fold<'State, 'T>(folder : (('State, 'T) -> 'State), state : 'State, array : 'T[]) : 'State
+```
+
+## Summary
+Iterates a function `f` through an array `array`, returning
+`f(...f(f(initialState, array[0]), array[1]), ...)`.
+
+## Type Parameters
+### 'State
+The type of states the `folder` function operates on, i.e., accepts as its first
+argument and returns.
+### 'T
+The type of `array` elements.
+
+## Input
+### folder
+A function to be folded over the array.
+### state
+The initial state of the folder.
+### array
+An array of values to be folded over.
+
+## Output
+The final state returned by the folder after iterating over
+all elements of `array`.
+
+## Example
+```qsharp
+let sum = Fold((x, y) -> x + y, 0, [1, 2, 3, 4, 5]); // `sum` is 15.
+```

package/docs/Microsoft.Quantum.Arrays/ForEach.md

@@ -0,0 +1,41 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.ForEach
+title: ForEach operation
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: operation
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: ForEach
+qsharp.summary: Given an array and an operation that is defined for the elements of the array, returns a new array that consists of the images of the original array under the operation.
+---
+
+# ForEach operation
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+operation ForEach<'T, 'U>(action : ('T => 'U), array : 'T[]) : 'U[]
+```
+
+## Summary
+Given an array and an operation that is defined
+for the elements of the array, returns a new array that consists
+of the images of the original array under the operation.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+### 'U
+The result type of the `action` operation.
+
+## Input
+### action
+An operation from `'T` to `'U` that is applied to each element.
+### array
+An array of elements over `'T`.
+
+## Output
+An array `'U[]` of elements that are mapped by the `action` operation.
+
+## See Also
+- Microsoft.Quantum.Arrays.Mapped

package/docs/Microsoft.Quantum.Arrays/Head.md

@@ -0,0 +1,32 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Head
+title: Head function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Head
+qsharp.summary: Returns the first element of the array.
+---
+
+# Head function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Head<'A>(array : 'A[]) : 'A
+```
+
+## Summary
+Returns the first element of the array.
+
+## Type Parameters
+### 'A
+The type of the array elements.
+
+## Input
+### array
+Array of which the first element is taken. Array must have at least 1 element.
+
+## Output
+The first element of the array.

package/docs/Microsoft.Quantum.Arrays/HeadAndRest.md

@@ -0,0 +1,32 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.HeadAndRest
+title: HeadAndRest function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: HeadAndRest
+qsharp.summary: Returns a tuple of first and all remaining elements of the array.
+---
+
+# HeadAndRest function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function HeadAndRest<'A>(array : 'A[]) : ('A, 'A[])
+```
+
+## Summary
+Returns a tuple of first and all remaining elements of the array.
+
+## Type Parameters
+### 'A
+The type of the array elements.
+
+## Input
+### array
+An array with at least one element.
+
+## Output
+A tuple of first and all remaining elements of the array.