qsharp-lang 1.1.3 → 1.1.5-dev

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

@@ -0,0 +1,39 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IndexOf
+title: IndexOf function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IndexOf
+qsharp.summary: Returns the first index of the first element in an array that satisfies a given predicate. If no such element exists, returns -1.
+---
+
+# IndexOf function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IndexOf<'T>(predicate : ('T -> Bool), array : 'T[]) : Int
+```
+
+## Summary
+Returns the first index of the first element in an array that satisfies
+a given predicate. If no such element exists, returns -1.
+
+## Input
+### predicate
+A predicate function acting on elements of the array.
+### array
+An array to be searched using the given predicate.
+
+## Output
+Either the smallest index of an element for which `predicate(array[index])` is true,
+or -1 if no such element exists.
+
+## Example
+The following code gets the index of the first even number in the input array.
+```qsharp
+let indexOfFirstEven = IndexOf(x -> x % 2 == 0, [1, 3, 17, 2, 21]);
+// `indexOfFirstEven` is 3.
+```

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

@@ -0,0 +1,40 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IndexRange
+title: IndexRange function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IndexRange
+qsharp.summary: Given an array, returns a range over the indices of that array, suitable for use in a for loop.
+---
+
+# IndexRange function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IndexRange<'TElement>(array : 'TElement[]) : Range
+```
+
+## Summary
+Given an array, returns a range over the indices of that array, suitable
+for use in a for loop.
+
+## Type Parameters
+### 'TElement
+The type of elements of the array.
+
+## Input
+### array
+An array for which a range of indices should be returned.
+
+## Output
+A range over all indices of the array.
+
+## Example
+The following `for` loops are equivalent:
+```qsharp
+for idx in IndexRange(array) { ... }
+for idx in 0 .. Length(array) - 1 { ... }
+```

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

@@ -0,0 +1,49 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Interleaved
+title: Interleaved function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Interleaved
+qsharp.summary: Interleaves two arrays of (almost) same size.
+---
+
+# Interleaved function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Interleaved<'T>(first : 'T[], second : 'T[]) : 'T[]
+```
+
+## Summary
+Interleaves two arrays of (almost) same size.
+
+## Description
+This function returns the interleaving of two arrays, starting
+with the first element from the first array, then the first
+element from the second array, and so on.
+
+The first array must either be
+of the same length as the second one, or can have one more element.
+
+## Type Parameters
+### 'T
+The type of each element of `first` and `second`.
+
+## Input
+### first
+The first array to be interleaved.
+
+### second
+The second array to be interleaved.
+
+## Output
+Interleaved array
+
+## Example
+```qsharp
+// same as interleaved = [1, -1, 2, -2, 3, -3]
+let interleaved = Interleaved([1, 2, 3], [-1, -2, -3])
+```

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

@@ -0,0 +1,28 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IsEmpty
+title: IsEmpty function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IsEmpty
+qsharp.summary: Returns true if and only if an array is empty.
+---
+
+# IsEmpty function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IsEmpty<'T>(array : 'T[]) : Bool
+```
+
+## Summary
+Returns true if and only if an array is empty.
+
+## Input
+### array
+The array to be checked.
+
+## Output
+`true` if and only if the array is empty (has length 0).

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

@@ -0,0 +1,42 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IsRectangularArray
+title: IsRectangularArray function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IsRectangularArray
+qsharp.summary: Returns whether a 2-dimensional array has a rectangular shape
+---
+
+# IsRectangularArray function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IsRectangularArray<'T>(array : 'T[][]) : Bool
+```
+
+## Summary
+Returns whether a 2-dimensional array has a rectangular shape
+
+## Type Parameters
+### 'T
+The type of each element of `array`.
+
+## Input
+### array
+A 2-dimensional array of elements.
+
+## Output
+`true` if the array is rectangular, `false` otherwise.
+
+## Example
+```qsharp
+IsRectangularArray([[1, 2], [3, 4]]);       // true
+IsRectangularArray([[1, 2, 3], [4, 5, 6]]); // true
+IsRectangularArray([[1, 2], [3, 4, 5]]);    // false
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.IsSquareArray

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

@@ -0,0 +1,42 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IsSorted
+title: IsSorted function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IsSorted
+qsharp.summary: Given an array, returns whether that array is sorted as defined by a given comparison function.
+---
+
+# IsSorted function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IsSorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : Bool
+```
+
+## Summary
+Given an array, returns whether that array is sorted as defined by
+a given comparison function.
+
+## Type Parameters
+### 'T
+The type of each element of `array`.
+
+## Input
+### comparison
+A function that compares two elements such that `a` is considered to
+be less than or equal to `b` if `comparison(a, b)` is `true`.
+### array
+The array to be checked.
+
+## Output
+`true` if and only if for each pair of elements `a` and `b` of
+`array` occurring in that order, `comparison(a, b)` is `true`.
+
+## Remarks
+The function `comparison` is assumed to be transitive, such that
+if `comparison(a, b)` and `comparison(b, c)`, then `comparison(a, c)`
+is assumed.

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

@@ -0,0 +1,42 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.IsSquareArray
+title: IsSquareArray function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: IsSquareArray
+qsharp.summary: Returns whether a 2-dimensional array has a square shape
+---
+
+# IsSquareArray function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function IsSquareArray<'T>(array : 'T[][]) : Bool
+```
+
+## Summary
+Returns whether a 2-dimensional array has a square shape
+
+## Type Parameters
+### 'T
+The type of each element of `array`.
+
+## Input
+### array
+A 2-dimensional array of elements.
+
+## Example
+```qsharp
+IsSquareArray([[1, 2], [3, 4]]);         // true
+IsSquareArray([[1, 2, 3], [4, 5, 6]]);   // false
+IsSquareArray([[1, 2], [3, 4], [5, 6]]); // false
+```
+
+## Output
+`true` if the array is square, `false` otherwise.
+
+## See Also
+- Microsoft.Quantum.Arrays.IsRectangularArray

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

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

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

@@ -0,0 +1,52 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.MappedByIndex
+title: MappedByIndex function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: MappedByIndex
+qsharp.summary: Given an array and a function that is defined for the indexed elements of the array, returns a new array that consists of the images of the original array under the function.
+---
+
+# MappedByIndex function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function MappedByIndex<'T, 'U>(mapper : ((Int, 'T) -> 'U), array : 'T[]) : 'U[]
+```
+
+## Summary
+Given an array and a function that is defined
+for the indexed elements of the array, returns a new array that consists
+of the images of the original array under the function.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+### 'U
+The result type of the `mapper` function.
+
+## Input
+### mapper
+A function from `(Int, 'T)` to `'U` that is used to map elements
+and their indices.
+### array
+An array of elements over `'T`.
+
+## Output
+An array `'U[]` of elements that are mapped by the `mapper` function.
+
+## Example
+The following two lines are equivalent:
+```qsharp
+let array = MappedByIndex(f, [x0, x1, x2]);
+```
+and
+```qsharp
+let array = [f(0, x0), f(1, x1), f(2, x2)];
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Mapped

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

@@ -0,0 +1,46 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.MappedOverRange
+title: MappedOverRange function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: MappedOverRange
+qsharp.summary: Given a range and a function that takes an integer as input, returns a new array that consists of the images of the range values under the function.
+---
+
+# MappedOverRange function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function MappedOverRange<'T>(mapper : (Int -> 'T), range : Range) : 'T[]
+```
+
+## Summary
+Given a range and a function that takes an integer as input,
+returns a new array that consists
+of the images of the range values under the function.
+
+## Type Parameters
+### 'T
+The result type of the `mapper` function.
+
+## Input
+### mapper
+A function from `Int` to `'T` that is used to map range values.
+### range
+A range of integers.
+
+## Output
+An array `'T[]` of elements that are mapped by the `mapper` function.
+
+## Example
+This example adds 1 to a range of even numbers:
+```qsharp
+let numbers = MappedOverRange(x -> x + 1, 0..2..10);
+// numbers = [1, 3, 5, 7, 9, 11]
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Mapped

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

@@ -0,0 +1,33 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Most
+title: Most function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Most
+qsharp.summary: Creates an array that is equal to an input array except that the last array element is dropped.
+---
+
+# Most function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Most<'T>(array : 'T[]) : 'T[]
+```
+
+## Summary
+Creates an array that is equal to an input array except that the last array
+element is dropped.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### array
+An array whose first to second-to-last elements are to form the output array.
+
+## Output
+An array containing the elements `array[0..Length(array) - 2]`.

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

@@ -0,0 +1,32 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.MostAndTail
+title: MostAndTail function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: MostAndTail
+qsharp.summary: Returns a tuple of all but one and the last element of the array.
+---
+
+# MostAndTail function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function MostAndTail<'A>(array : 'A[]) : ('A[], 'A)
+```
+
+## Summary
+Returns a tuple of all but one and the last element 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 all but one and the last element of the array.

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

@@ -0,0 +1,49 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Padded
+title: Padded function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Padded
+qsharp.summary: Returns an array padded at with specified values up to a specified length.
+---
+
+# Padded function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Padded<'T>(paddedLength : Int, defaultElement : 'T, inputArray : 'T[]) : 'T[]
+```
+
+## Summary
+Returns an array padded at with specified values up to a
+specified length.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### paddedLength
+The length of the padded array. If this is positive, `array`
+is padded at the head. If this is negative, `array` is padded
+at the tail.
+### defaultElement
+Default value to use for padding elements.
+### array
+Array to be padded.
+
+## Output
+An array `output` that is the `array` padded at the head or the tail
+with `defaultElement`s until `output` has length `paddedLength`
+
+## Example
+```qsharp
+let array = [10, 11, 12];
+// The following line returns [10, 12, 15, 2, 2].
+let output = Padded(-5, 2, array);
+// The following line returns [2, 2, 10, 12, 15].
+let output = Padded(5, 2, array);
+```

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

@@ -0,0 +1,44 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Partitioned
+title: Partitioned function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Partitioned
+qsharp.summary: Splits an array into multiple parts.
+---
+
+# Partitioned function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Partitioned<'T>(partitionSizes : Int[], array : 'T[]) : 'T[][]
+```
+
+## Summary
+Splits an array into multiple parts.
+
+## Input
+### partitionSizes
+Number of elements in each split part of array.
+### array
+Input array to be split.
+
+## Output
+Multiple arrays where the first array is the first `partitionSizes[0]` of `array`
+and the second array are the next `partitionSizes[1]` of `array` etc. The last array
+will contain all remaining elements. If the array is split exactly, the
+last array will be the empty array, indicating there are no remaining elements.
+In other words, `Tail(Partitioned(...))` will always return the remaining
+elements, while `Most(Partitioned(...))` will always return the complete
+partitions of the array.
+
+## Example
+```qsharp
+// The following returns [[2, 3], [5], [7]];
+let split = Partitioned([2, 1], [2, 3, 5, 7]);
+// The following returns [[2, 3], [5, 7], []];
+let split = Partitioned([2, 2], [2, 3, 5, 7]);
+```

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

@@ -0,0 +1,33 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Rest
+title: Rest function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Rest
+qsharp.summary: Creates an array that is equal to an input array except that the first array element is dropped.
+---
+
+# Rest function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Rest<'T>(array : 'T[]) : 'T[]
+```
+
+## Summary
+Creates an array that is equal to an input array except that the first array
+element is dropped.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### array
+An array whose second to last elements are to form the output array.
+
+## Output
+An array containing the elements `array[1..Length(array) - 1]`.

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

@@ -0,0 +1,33 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.Reversed
+title: Reversed function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Reversed
+qsharp.summary: Create an array that contains the same elements as an input array but in reversed order.
+---
+
+# Reversed function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function Reversed<'T>(array : 'T[]) : 'T[]
+```
+
+## Summary
+Create an array that contains the same elements as an input array but in reversed
+order.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### array
+An array whose elements are to be copied in reversed order.
+
+## Output
+An array containing the elements `array[Length(array) - 1]` .. `array[0]`.

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

@@ -0,0 +1,41 @@
+---
+uid: Qdk.Microsoft.Quantum.Arrays.SequenceI
+title: SequenceI function
+ms.date: 02/23/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: SequenceI
+qsharp.summary: Get an array of integers in a given interval.
+---
+
+# SequenceI function
+
+Namespace: Microsoft.Quantum.Arrays
+
+```qsharp
+function SequenceI(from : Int, to : Int) : Int[]
+```
+
+## Summary
+Get an array of integers in a given interval.
+
+## Input
+### from
+An inclusive start index of the interval.
+### to
+An inclusive end index of the interval that is not smaller than `from`.
+
+## Output
+An array containing the sequence of numbers `from`, `from + 1`, ...,
+`to`.
+
+## Example
+```qsharp
+let arr1 = SequenceI(0, 3); // [0, 1, 2, 3]
+let arr2 = SequenceI(23, 29); // [23, 24, 25, 26, 27, 28, 29]
+let arr3 = SequenceI(-5, -2); // [-5, -4, -3, -2]
+
+let numbers = SequenceI(0, _); // function to create sequence from 0 to `to`
+let naturals = SequenceI(1, _); // function to create sequence from 1 to `to`
+```