qsharp-lang 1.1.2-dev → 1.1.4-dev

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

@@ -0,0 +1,43 @@
+---
+uid: Microsoft.Quantum.Arrays.ForEach
+title: ForEach operation
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: opeartion
+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](xref: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: Microsoft.Quantum.Arrays.Head
+title: Head function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.HeadAndRest
+title: HeadAndRest function
+ms.date: 02/16/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](xref: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.

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

@@ -0,0 +1,40 @@
+---
+uid: Microsoft.Quantum.Arrays.IndexOf
+title: IndexOf function
+ms.date: 02/16/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](xref: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,41 @@
+---
+uid: Microsoft.Quantum.Arrays.IndexRange
+title: IndexRange function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.Interleaved
+title: Interleaved function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.IsEmpty
+title: IsEmpty function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.IsRectangularArray
+title: IsRectangularArray function
+ms.date: 02/16/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](xref: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,43 @@
+---
+uid: Microsoft.Quantum.Arrays.IsSorted
+title: IsSorted function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.IsSquareArray
+title: IsSquareArray function
+ms.date: 02/16/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](xref: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,43 @@
+---
+uid: Microsoft.Quantum.Arrays.Mapped
+title: Mapped function
+ms.date: 02/16/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](xref: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,54 @@
+---
+uid: Microsoft.Quantum.Arrays.MappedByIndex
+title: MappedByIndex function
+ms.date: 02/16/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](xref: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,48 @@
+---
+uid: Microsoft.Quantum.Arrays.MappedOverRange
+title: MappedOverRange function
+ms.date: 02/16/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](xref: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,34 @@
+---
+uid: Microsoft.Quantum.Arrays.Most
+title: Most function
+ms.date: 02/16/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](xref: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: Microsoft.Quantum.Arrays.MostAndTail
+title: MostAndTail function
+ms.date: 02/16/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](xref: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,50 @@
+---
+uid: Microsoft.Quantum.Arrays.Padded
+title: Padded function
+ms.date: 02/16/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](xref: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);
+```