Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add summary lines back into stdlib readmes #1952

Merged
merged 4 commits into from
Oct 8, 2024
Merged

Add summary lines back into stdlib readmes #1952

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bd92c02
Fix stdlib readmes
sezna Oct 8, 2024
67dba5e
update expects
sezna Oct 8, 2024
69b55ec
remove doubled up summaries
sezna Oct 8, 2024
a575e36
update expects
sezna Oct 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions library/std/src/Std/Arrays.qs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import Std.Diagnostics.*;
import Std.Math.*;

/// # Summary
sezna marked this conversation as resolved.
Show resolved Hide resolved
/// # Summary
/// Given an array and a predicate that is defined
/// for the elements of the array, and checks if all elements of the
Expand Down Expand Up @@ -37,6 +38,7 @@ function All<'T>(predicate : ('T -> Bool), array : 'T[]) : Bool {
true
}

/// # 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.
Expand Down Expand Up @@ -68,6 +70,7 @@ function Any<'T>(predicate : ('T -> Bool), array : 'T[]) : Bool {
false
}

/// # Summary
/// Splits an array into multiple parts of equal length.
///
/// # Input
Expand Down Expand Up @@ -95,6 +98,7 @@ function Chunks<'T>(chunkSize : Int, array : 'T[]) : 'T[][] {
output
}

/// # Summary
/// Shift an array circularly left or right by a specific step size.
///
/// # Type Parameters
Expand Down Expand Up @@ -142,6 +146,7 @@ function CircularlyShifted<'T>(stepCount : Int, array : 'T[]) : 'T[] {
rightPart + leftPart
}

/// # Summary
/// Extracts a column from a matrix.
///
/// # Description
Expand Down Expand Up @@ -178,6 +183,7 @@ function ColumnAt<'T>(column : Int, matrix : 'T[][]) : 'T[] {
columnValues
}

/// # 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.
Expand Down Expand Up @@ -210,6 +216,7 @@ function Count<'T>(predicate : ('T -> Bool), array : 'T[]) : Int {
count
}

/// # Summary
/// Returns an array of diagonal elements of a 2-dimensional array
///
/// # Description
Expand Down Expand Up @@ -246,6 +253,7 @@ function Diagonal<'T>(matrix : 'T[][]) : 'T[] {
diagonal
}

/// # Summary
/// Repeats an operation for a given number of samples, collecting its outputs
/// in an array.
///
Expand Down Expand Up @@ -277,6 +285,7 @@ operation DrawMany<'TInput, 'TOutput>(op : ('TInput => 'TOutput), nSamples : Int
outputs
}

/// # Summary
/// Given an array, returns a new array containing elements of the original
/// array along with the indices of each element.
///
Expand Down Expand Up @@ -305,6 +314,7 @@ function Enumerated<'TElement>(array : 'TElement[]) : (Int, 'TElement)[] {
MappedByIndex((index, element) -> (index, element), array)
}

/// # Summary
/// Returns an array containing the elements of another array,
/// excluding elements at a given list of indices.
///
Expand Down Expand Up @@ -346,6 +356,7 @@ function Excluding<'T>(remove : Int[], array : 'T[]) : 'T[] {
output
}

/// # 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.
Expand Down Expand Up @@ -378,6 +389,7 @@ function Filtered<'T>(predicate : ('T -> Bool), array : 'T[]) : 'T[] {
filtered
}

/// # 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.
///
Expand Down Expand Up @@ -411,6 +423,7 @@ function FlatMapped<'TInput, 'TOutput>(mapper : ('TInput -> 'TOutput[]), array :
output
}

/// # Summary
/// Given an array of arrays, returns the concatenation of all arrays.
///
/// # Type Parameters
Expand All @@ -437,6 +450,7 @@ function Flattened<'T>(arrays : 'T[][]) : 'T[] {
output
}

/// # Summary
/// Iterates a function `f` through an array `array`, returning
/// `f(...f(f(initialState, array[0]), array[1]), ...)`.
///
Expand Down Expand Up @@ -471,6 +485,7 @@ function Fold<'State, 'T>(folder : (('State, 'T) -> 'State), state : 'State, arr
current
}

/// # 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.
Expand Down Expand Up @@ -500,6 +515,7 @@ operation ForEach<'T, 'U>(action : ('T => 'U), array : 'T[]) : 'U[] {
output
}

/// # Summary
/// Returns the first element of the array.
///
/// # Type Parameters
Expand All @@ -517,6 +533,7 @@ function Head<'A>(array : 'A[]) : 'A {
array[0]
}

/// # Summary
/// Returns a tuple of first and all remaining elements of the array.
///
/// # Type Parameters
Expand All @@ -533,6 +550,7 @@ function HeadAndRest<'A>(array : 'A[]) : ('A, 'A[]) {
(Head(array), Rest(array))
}

/// # Summary
/// Returns the first index of the first element in an array that satisfies
/// a given predicate. If no such element exists, returns -1.
///
Expand Down Expand Up @@ -561,6 +579,7 @@ function IndexOf<'T>(predicate : ('T -> Bool), array : 'T[]) : Int {
-1
}

/// # Summary
/// Given an array, returns a range over the indices of that array, suitable
/// for use in a for loop.
///
Expand All @@ -585,6 +604,7 @@ function IndexRange<'TElement>(array : 'TElement[]) : Range {
0..Length(array) - 1
}

/// # Summary
/// Interleaves two arrays of (almost) same size.
///
/// # Description
Expand Down Expand Up @@ -632,6 +652,7 @@ function Interleaved<'T>(first : 'T[], second : 'T[]) : 'T[] {
interleaved
}

/// # Summary
/// Returns true if and only if an array is empty.
///
/// # Input
Expand All @@ -644,6 +665,7 @@ function IsEmpty<'T>(array : 'T[]) : Bool {
Length(array) == 0
}

/// # Summary
/// Returns whether a 2-dimensional array has a rectangular shape
///
/// # Type Parameters
Expand Down Expand Up @@ -679,6 +701,7 @@ function IsRectangularArray<'T>(array : 'T[][]) : Bool {
true
}

/// # Summary
/// Given an array, returns whether that array is sorted as defined by
/// a given comparison function.
///
Expand Down Expand Up @@ -710,6 +733,7 @@ function IsSorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : Bool {
true
}

/// # Summary
/// Returns whether a 2-dimensional array has a square shape
///
/// # Type Parameters
Expand Down Expand Up @@ -745,6 +769,7 @@ function IsSquareArray<'T>(array : 'T[][]) : Bool {
true
}

/// # 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.
Expand Down Expand Up @@ -774,6 +799,7 @@ function Mapped<'T, 'U>(mapper : ('T -> 'U), array : 'T[]) : 'U[] {
mapped
}

/// # 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.
Expand Down Expand Up @@ -814,6 +840,7 @@ function MappedByIndex<'T, 'U>(mapper : ((Int, 'T) -> 'U), array : 'T[]) : 'U[]
mapped
}

/// # 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.
Expand Down Expand Up @@ -848,6 +875,7 @@ function MappedOverRange<'T>(mapper : (Int -> 'T), range : Range) : 'T[] {
output
}

/// # Summary
/// Creates an array that is equal to an input array except that the last array
/// element is dropped.
///
Expand All @@ -865,6 +893,7 @@ function Most<'T>(array : 'T[]) : 'T[] {
array[...Length(array) - 2]
}

/// # Summary
/// Returns a tuple of all but one and the last element of the array.
///
/// # Type Parameters
Expand All @@ -881,6 +910,7 @@ function MostAndTail<'A>(array : 'A[]) : ('A[], 'A) {
(Most(array), Tail(array))
}

/// # Summary
/// Returns an array padded at with specified values up to a
/// specified length.
///
Expand Down Expand Up @@ -925,6 +955,7 @@ function Padded<'T>(paddedLength : Int, defaultElement : 'T, inputArray : 'T[])
}
}

/// # Summary
/// Splits an array into multiple parts.
///
/// # Input
Expand Down Expand Up @@ -964,6 +995,7 @@ function Partitioned<'T>(partitionSizes : Int[], array : 'T[]) : 'T[][] {
output
}

/// # Summary
/// Creates an array that is equal to an input array except that the first array
/// element is dropped.
///
Expand All @@ -981,6 +1013,7 @@ function Rest<'T>(array : 'T[]) : 'T[] {
array[1...]
}

/// # Summary
/// Create an array that contains the same elements as an input array but in reversed
/// order.
///
Expand All @@ -998,6 +1031,7 @@ function Reversed<'T>(array : 'T[]) : 'T[] {
array[...-1...]
}

/// # Summary
/// Get an array of integers in a given interval.
///
/// # Input
Expand Down Expand Up @@ -1028,6 +1062,7 @@ function SequenceI(from : Int, to : Int) : Int[] {
array
}

/// # Summary
/// Get an array of integers in a given interval.
///
/// # Input
Expand Down Expand Up @@ -1061,6 +1096,7 @@ function SequenceL(from : BigInt, to : BigInt) : BigInt[] {
array
}

/// # Summary
/// Given an array, returns the elements of that array sorted by a given
/// comparison function.
///
Expand Down Expand Up @@ -1110,6 +1146,7 @@ function Sorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : 'T[] {
)
}

/// # Summary
/// Given two sorted arrays, returns a single array containing the
/// elements of both in sorted order. Used internally by `Sorted`.
internal function SortedMerged<'T>(comparison : (('T, 'T) -> Bool), left : 'T[], right : 'T[]) : 'T[] {
Expand All @@ -1131,6 +1168,7 @@ internal function SortedMerged<'T>(comparison : (('T, 'T) -> Bool), left : 'T[],
output + remainingLeft + remainingRight
}

/// # Summary
/// Takes an array and a list of locations and
/// produces a new array formed from the elements of the original
/// array that match the given locations.
Expand Down Expand Up @@ -1168,6 +1206,7 @@ function Subarray<'T>(locations : Int[], array : 'T[]) : 'T[] {
subarray
}

/// # Summary
/// Applies a swap of two elements in an array.
///
/// # Input
Expand All @@ -1194,6 +1233,7 @@ function Swapped<'T>(firstIndex : Int, secondIndex : Int, array : 'T[]) : 'T[] {
w/ secondIndex <- array[firstIndex]
}

/// # Summary
/// Returns the transpose of a matrix represented as an array
/// of arrays.
///
Expand Down Expand Up @@ -1237,6 +1277,7 @@ function Transposed<'T>(matrix : 'T[][]) : 'T[][] {
transposed
}

/// # Summary
/// Returns the last element of the array.
///
/// # Type Parameters
Expand All @@ -1255,6 +1296,7 @@ function Tail<'A>(array : 'A[]) : 'A {
array[size - 1]
}

/// # Summary
/// Given an array of 2-tuples, returns a tuple of two arrays, each containing
/// the elements of the tuples of the input array.
///
Expand Down Expand Up @@ -1291,6 +1333,7 @@ function Unzipped<'T, 'U>(array : ('T, 'U)[]) : ('T[], 'U[]) {
return (first, second);
}

/// # Summary
/// Given a predicate and an array, returns the indices of that
/// array where the predicate is true.
///
Expand All @@ -1316,6 +1359,7 @@ function Where<'T>(predicate : ('T -> Bool), array : 'T[]) : Int[] {
indexes
}

/// # Summary
/// Returns all consecutive subarrays of length `size`.
///
/// # Description
Expand Down Expand Up @@ -1357,6 +1401,7 @@ function Windows<'T>(size : Int, array : 'T[]) : 'T[][] {
windows
}

/// # Summary
/// Given two arrays, returns a new array of pairs such that each pair
/// contains an element from each original array.
///
Expand Down
Loading
Loading