koconut
Version:
Provide interchainable array, set, map and etc supporting both normal and async callbacks as their action arguments.
1,247 lines • 98.3 kB
TypeScript
import {
KoconutPrimitive,
KoconutArray,
KoconutSet,
KoconutBoolean,
KoconutComparable,
Predicator,
Selector,
Comparator,
Action,
Transformer,
} from '../../module';
export declare class KoconutIterable<
DataType,
CombinedDataType,
WrapperType extends Iterable<DataType>,
CombinedWrapperType extends Iterable<CombinedDataType>,
> extends KoconutPrimitive<WrapperType> {
protected combinedDataWrapper?: CombinedWrapperType;
protected mSize: number;
/**
* Returns the number of the elements matching the given ```predicate```. If the ```predicate``` is ommitted it'll returns the whole number of elements.
* @param {Predicator<CombinedDataType> | null} predicate A callback function that accepts an argument. The method calls the ```predicate``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```predicate```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<number>}
*
* @since 1.0.10
*
* @category Calculator
*
* @example
* ``` typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const numberOfAllArrayElements = await koconutArray
* .count()
* .yield()
* console.log(numberOfAllArrayElements)
* // ↑ 5
*
* const numberOfArrayElementsHigherThan2 = await koconutArray
* .count(eachNumber => eachNumber > 2)
* .yield()
* console.log(numberOfArrayElementsHigherThan2)
* // ↑ 3 -- i.e. [3, 4, 5]
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of(1,2,3,4,5)
*
* const numberOfAllSetElements = await koconutSet
* .count()
* .yield()
* console.log(numberOfAllSetElements)
* // ↑ 5
*
* const numberOfOddSetElements = await koconutSet
* .count(eachNumber => eachNumber % 2 == 1)
* .yield()
* console.log(numberOfOddSetElements)
* // ↑ 3 -- i.e. [1, 3, 5]
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of(1,2,3)
* .associateWith(eachNumber => eachNumber * 2)
* // ↑ Map { 1 => 2,
* // 2 => 4,
* // 3 => 6 }
*
* const numberOfAllMapEntries = await koconutMap
* .count()
* .yield()
* console.log(numberOfAllMapEntries)
* // ↑ 3
*
* const numberOfMapEntriesValueHigherThan5 = await koconutMap
* .count(eachEntry => eachEntry.value > 5)
* .yield()
* console.log(numberOfMapEntriesValueHigherThan5)
* // ↑ 1 -- i.e. Entry { 3, 6 }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(1,2,3,4,5)
*
* const numberOfArrayElementsLessThan3 = await koconutArray2
* .count(async eachNumber => eachNumber < 3)
* .yield()
* console.log(numberOfArrayElementsLessThan3)
* // ↑ 2 -- i.e. [1, 2]
*
* const numberOfEvenArrayElements = await koconutArray2
* .count(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 2 == 0)
* }))
* .yield()
* console.log(numberOfEvenArrayElements)
* // ↑ 2 -- i.e. [2, 4]
* ```
*/
count(
predicate?: Predicator<CombinedDataType> | null,
thisArg?: any,
): KoconutPrimitive<number>;
/**
* Returns the first element yielding the largest value of the given function or
* throws {@link KoconutNoSuchElementException} if there are no elements.
* @param {Selector<CombinedDataType, number | string | KoconutComparable>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType>}
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
* @deprecated Use {@link maxByOrNull} instead.
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const largestNumberOfArray = await koconutArray
* .maxBy(eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray)
* // ↑ 5
*
* try {
* await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxBy(eachNumber => eachNumber)
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No element in 1 to 5 is greater than 10.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const longestStringOfSet = await koconutSet
* .maxBy(eachString => eachString.length)
* .yield()
* console.log(longestStringOfSet)
* // ↑ abc
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of(1, 12, 123)
* .associateWith(eachNumber => eachNumber.toString())
*
* const longestDigitsEntryOfMap = await koconutMap
* .maxBy(eachEntry => eachEntry.value.length)
* .yield()
* console.log(longestDigitsEntryOfMap)
* // ↑ Entry { keyElement: 123, valueElement: '123' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(19,27,32)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxBy(async eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 32
*
* const largest1sDigitNumberOfArray2 = await koconutArray2
* .maxBy(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(largest1sDigitNumberOfArray2)
* // ↑ 19
* ```
*/
maxBy(
selector: Selector<CombinedDataType, number | string | KoconutComparable>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType>;
/**
* Returns the first element yielding the largest value of the given function or null if there are no elements.
*
* @param {Selector<CombinedDataType, number| string| KoconutComparable>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const largestNumberOfArray = await koconutArray
* .maxByOrNull(eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray)
* // ↑ 5
*
*
* const largestNumberOfEmptyArray = await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxByOrNull(eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const longestStringOfSet = await koconutSet
* .maxByOrNull(eachString => eachString.length)
* .yield()
* console.log(longestStringOfSet)
* // ↑ abc
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of(1, 12, 123)
* .associateWith(eachNumber => eachNumber.toString())
*
* const longestDigitsEntryOfMap = await koconutMap
* .maxByOrNull(eachEntry => eachEntry.value.length)
* .yield()
* console.log(longestDigitsEntryOfMap)
* // ↑ Entry { keyElement: 123, valueElement: '123' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(19,27,32)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxByOrNull(async eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 32
*
* const largest1sDigitNumberOfArray2 = await koconutArray2
* .maxByOrNull(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(largest1sDigitNumberOfArray2)
* // ↑ 19
* ```
*/
maxByOrNull(
selector: Selector<CombinedDataType, number | string | KoconutComparable>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType | null>;
/**
* Returns the largest value among all values produced by ```selector``` function applied to each element in the collection or
* throws {@link KoconutNoSuchElementException} if there are no elements.
* @param {Selector<CombinedDataType, number | string | ComparableType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<number | string | ComparableType> }
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,7,9)
*
* const largestRemainderNumberDividedBy5OfArray = await koconutArray
* .maxOf(eachNumber => eachNumber % 5)
* .yield()
* console.log(largestRemainderNumberDividedBy5OfArray)
* // ↑ 4
*
* try {
* await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxOf(eachNumber => eachNumber % 5)
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No element in 1 to 5 is greater than 10.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const longestStringLengthOfSet = await koconutSet
* .maxOf(eachString => eachString.length)
* .yield()
* console.log(longestStringLengthOfSet)
* // ↑ 3
*
* class ComparableString implements KoconutComparable{
* str : string
* constructor(str : string) {
* this.str = str
* }
* // Override
* compareTo(other : ComparableString) : number {
* return this.str.length - other.str.length
* }
* }
* const maxComparableString = await koconutSet
* .maxOf(eachString => new ComparableString(eachString))
* .yield()
* console.log(maxComparableString)
* // ↑ ComparableString { str: 'abc' }
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthOfMap = await koconutMap
* .maxOf(eachEntry => eachEntry.key)
* .yield()
* console.log(longestStringLengthOfMap)
* // ↑ 3
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxOf(async eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitOfArray2 = await koconutArray2
* .maxOf(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(largest1sDigitOfArray2)
* // ↑ 5
* ```
*/
maxOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, number | string | ComparableType>,
thisArg: any,
): KoconutPrimitive<number | string | ComparableType>;
/** @ignore */
maxOf(
selector: Selector<CombinedDataType, number>,
thisArg: any,
): KoconutPrimitive<number>;
/** @ignore */
maxOf(selector: Selector<CombinedDataType, number>): KoconutPrimitive<number>;
/** @ignore */
maxOf(
selector: Selector<CombinedDataType, string>,
thisArg: any,
): KoconutPrimitive<string>;
/** @ignore */
maxOf(selector: Selector<CombinedDataType, string>): KoconutPrimitive<string>;
/** @ignore */
maxOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
thisArg: any,
): KoconutPrimitive<ComparableType>;
/** @ignore */
maxOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
): KoconutPrimitive<ComparableType>;
/**
* Returns the largest value among all values produced by ```selector``` function applied to each element in the collection or
* null if there are no elements.
* @param {Selector<CombinedDataType, number | string | ComparableType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {this} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @returns {KoconutPrimitive<number | string | ComparableType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,7,9)
*
* const largestRemainderNumberDividedBy5OfArray = await koconutArray
* .maxOfOrNull(eachNumber => eachNumber % 5)
* .yield()
* console.log(largestRemainderNumberDividedBy5OfArray)
* // ↑ 4
*
* const largestRemainderNumberDividedBy5OfEmptyArray = await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxOfOrNull(eachNumber => eachNumber % 5)
* .yield()
* console.log(largestRemainderNumberDividedBy5OfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const longestStringLengthOfSet = await koconutSet
* .maxOfOrNull(eachString => eachString.length)
* .yield()
* console.log(longestStringLengthOfSet)
* // ↑ 3
*
* class ComparableString implements KoconutComparable{
* str : string
* constructor(str : string) {
* this.str = str
* }
* // Override
* compareTo(other : ComparableString) : number {
* return this.str.length - other.str.length
* }
* }
* const maxComparableString = await koconutSet
* .maxOfOrNull(eachString => new ComparableString(eachString))
* .yield()
* console.log(maxComparableString)
* // ↑ ComparableString { str: 'abc' }
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthOfMap = await koconutMap
* .maxOfOrNull(eachEntry => eachEntry.key)
* .yield()
* console.log(longestStringLengthOfMap)
* // ↑ 3
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxOfOrNull(async eachNumber => eachNumber)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitOfArray2 = await koconutArray2
* .maxOfOrNull(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(largest1sDigitOfArray2)
* // ↑ 5
* ```
*/
maxOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, number | string | ComparableType>,
thisArg: any,
): KoconutPrimitive<number | string | ComparableType | null>;
/** @ignore */
maxOfOrNull(
selector: Selector<CombinedDataType, number>,
): KoconutPrimitive<number | null>;
/** @ignore */
maxOfOrNull(
selector: Selector<CombinedDataType, number>,
thisArg: any,
): KoconutPrimitive<number | null>;
/** @ignore */
maxOfOrNull(
selector: Selector<CombinedDataType, string>,
): KoconutPrimitive<string | null>;
/** @ignore */
maxOfOrNull(
selector: Selector<CombinedDataType, string>,
thisArg: any,
): KoconutPrimitive<string | null>;
/** @ignore */
maxOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
): KoconutPrimitive<ComparableType | null>;
/** @ignore */
maxOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
thisArg: any,
): KoconutPrimitive<ComparableType | null>;
/**
* Returns the largest value according to the provided ```comparator``` among all values
* produced by ```selector``` function applied to each element in the collection all throws {@link KoconutNoSuchElementException}
* if elements are empty.
*
* @param {Selector<CombinedDataType, ResultDataType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {Comparator<ResultDataType>} comparator A callback function that accepts two arguements. The method calls the ```comparator``` to compare two selected values.
* In case the result is larger than 0, front is bigger than rear, and if it's less than 0 judge vice versa.
*
* @param {any} selectorThisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @param {any} comparatorThisArg An object to which the ```this``` keyword can refer in the ```comparator```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<ResultDataType>}
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of("1", "2", "3", "4", "5")
*
* const largestNumberedStringOfArray = await koconutArray
* .maxOfWith(
* parseInt,
* (front, rear) => front - rear
* )
* .yield()
* console.log(largestNumberedStringOfArray)
* // ↑ 5
*
* try {
* await koconutArray
* .filter(eachString => eachString.length > 2)
* .maxOfWith(
* parseInt,
* (front, rear) => front - rear
* )
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No string in "1" to "5" is logner than 2.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const lognestStringLengthOfSet = await koconutSet
* .maxOfWith(
* eachString => eachString.length,
* (front, rear) => front - rear
* )
* .yield()
* console.log(lognestStringLengthOfSet)
* // ↑ 3
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthOfMap = await koconutMap
* .maxOfWith(
* eachEntry => eachEntry.key,
* (front, rear) => front - rear
* )
* .yield()
* console.log(longestStringLengthOfMap)
* // ↑ 3
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxOfWith(
* async eachNumber => eachNumber,
* async (front, rear) => front - rear
* )
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitOfArray2 = await koconutArray2
* .maxOfWith(
* (eachNumber) => new Promise<number>(resolve => {
* resolve(eachNumber % 10)
* }),
* (front, rear) => new Promise(resolve => {
* resolve(front - rear)
* })
* )
* .yield()
* console.log(largest1sDigitOfArray2)
* // ↑ 5
* ```
*/
maxOfWith<ResultDataType>(
selector: Selector<CombinedDataType, ResultDataType>,
comparator: Comparator<ResultDataType>,
selectorThisArg?: any,
comparatorThisArg?: any,
): KoconutPrimitive<ResultDataType>;
/**
* Returns the largest value according to the provided ```comparator``` among all values
* produced by ```selector``` function applied to each element in the collection or ```null```
* if elements are empty.
*
* @param {Selector<CombinedDataType, ResultDataType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {Comparator<ResultDataType>} comparator A callback function that accepts two arguements. The method calls the ```comparator``` to compare two selected values.
* In case the result is larger than 0, front is bigger than rear, and if it's less than 0 judge vice versa.
*
* @param {any} selectorThisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @param {any} comparatorThisArg An object to which the ```this``` keyword can refer in the ```comparator```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<ResultDataType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of("1", "2", "3", "4", "5")
*
* const largestNumberedStringOfArray = await koconutArray
* .maxOfWithOrNull(
* parseInt,
* (front, rear) => front - rear
* )
* .yield()
* console.log(largestNumberedStringOfArray)
* // ↑ 5
*
* const largestNumberedStringOfEmptyArray = await koconutArray
* .filter(eachString => eachString.length > 2)
* .maxOfWithOrNull(
* parseInt,
* (front, rear) => front - rear
* )
* .yield()
* console.log(largestNumberedStringOfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const lognestStringLengthOfSet = await koconutSet
* .maxOfWithOrNull(
* eachString => eachString.length,
* (front, rear) => front - rear
* )
* .yield()
* console.log(lognestStringLengthOfSet)
* // ↑ 3
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthOfMap = await koconutMap
* .maxOfWithOrNull(
* eachEntry => eachEntry.key,
* (front, rear) => front - rear
* )
* .yield()
* console.log(longestStringLengthOfMap)
* // ↑ 3
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxOfWithOrNull(
* async eachNumber => eachNumber,
* async (front, rear) => front - rear
* )
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitOfArray2 = await koconutArray2
* .maxOfWithOrNull(
* (eachNumber) => new Promise<number>(resolve => {
* resolve(eachNumber % 10)
* }),
* (front, rear) => new Promise(resolve => {
* resolve(front - rear)
* })
* )
* .yield()
* console.log(largest1sDigitOfArray2)
* // ↑ 5
* ```
*/
maxOfWithOrNull<ResultDataType>(
selector: Selector<CombinedDataType, ResultDataType>,
comparator: Comparator<ResultDataType>,
selectorThisArg?: any,
comparatorThisArg?: any,
): KoconutPrimitive<ResultDataType | null>;
/**
* Returns the first element having the largest value according to the provided ```comparator``` or throws {@link KoconutNoSuchElementException}
* if elements are empty.
*
* @param {Comparator<CombinedDataType>} comparator A callback function that accepts two arguements. The method calls the ```comparator``` to compare two selected values.
* In case the result is larger than 0, front is bigger than rear, and if it's less than 0 judge vice versa.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```comparator```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType>}
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const largestNumberOfArray = await koconutArray
* .maxWith((front, rear) => front - rear)
* .yield()
* console.log(largestNumberOfArray)
* // ↑ 5
*
* try {
* await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxWith((front, rear) => front - rear)
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No element in 1 to 5 is greater than 10.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc", "abcd")
*
* const longestStringLengthOfSet = await koconutSet
* .maxWith((front, rear) => front.length - rear.length)
* .yield()
* console.log(longestStringLengthOfSet)
* // ↑ abcd
*
* // Case 3
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthEntryOfMap = await koconutMap
* .maxWith((front, rear) => front.key - rear.key)
* .yield()
* console.log(longestStringLengthEntryOfMap)
* // ↑ Entry { keyElement: 3, valueElement: 'abc' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxWith(async (front, rear) => front - rear)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitNumberOfArray2 = await koconutArray2
* .maxWith((front, rear) => new Promise(resolve => {
* resolve(front % 10 - rear % 10)
* }))
* .yield()
* console.log(largest1sDigitNumberOfArray2)
* // ↑ 45
* ```
*/
maxWith(
comparator: Comparator<CombinedDataType>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType>;
/**
* Returns the first element having the largest value according to the provided ```comparator``` or null
* if elements are empty.
*
* @param {Comparator<CombinedDataType>} comparator A callback function that accepts two arguements. The method calls the ```comparator``` to compare two selected values.
* In case the result is larger than 0, front is bigger than rear, and if it's less than 0 judge vice versa.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```comparator```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const largestNumberOfArray = await koconutArray
* .maxWithOrNull((front, rear) => front - rear)
* .yield()
* console.log(largestNumberOfArray)
* // ↑ 5
*
* const largestNumberOfEmptyArray = await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .maxWithOrNull((front, rear) => front - rear)
* .yield()
* console.log(largestNumberOfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc", "abcd")
*
* const longestStringLengthOfSet = await koconutSet
* .maxWithOrNull((front, rear) => front.length - rear.length)
* .yield()
* console.log(longestStringLengthOfSet)
* // ↑ abcd
*
* // Case 3
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const longestStringLengthEntryOfMap = await koconutMap
* .maxWithOrNull((front, rear) => front.key - rear.key)
* .yield()
* console.log(longestStringLengthEntryOfMap)
* // ↑ Entry { keyElement: 3, valueElement: 'abc' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const largestNumberOfArray2 = await koconutArray2
* .maxWithOrNull(async (front, rear) => front - rear)
* .yield()
* console.log(largestNumberOfArray2)
* // ↑ 51
*
* const largest1sDigitNumberOfArray2 = await koconutArray2
* .maxWithOrNull((front, rear) => new Promise(resolve => {
* resolve(front % 10 - rear % 10)
* }))
* .yield()
* console.log(largest1sDigitNumberOfArray2)
* // ↑ 45
* ```
*/
maxWithOrNull(
comparator: Comparator<CombinedDataType>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType | null>;
/**
* Returns the first element yielding the smallest value of the given function or
* throws {@link KoconutNoSuchElementException} if there are no elements.
*
* @param {Selector<CombinedDataType, number | string | KoconutComparable>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType>}
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
*
* @deprecated Use {@link minByOrNull} instead.
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const smallestNumberOfArray = await koconutArray
* .minBy(eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray)
* // ↑ 1
*
* try {
* await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .minBy(eachNumber => eachNumber)
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No element in 1 to 5 is greater than 10.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const shortestStringOfSet = await koconutSet
* .minBy(eachString => eachString.length)
* .yield()
* console.log(shortestStringOfSet)
* // ↑ a
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of(1, 12, 123)
* .associateWith(eachNumber => eachNumber.toString())
*
* const shortestDigitsEntryOfMap = await koconutMap
* .minBy(eachEntry => eachEntry.value.length)
* .yield()
* console.log(shortestDigitsEntryOfMap)
* // ↑ Entry { keyElement: 1, valueElement: '1' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(19,27,32)
*
* const smallestNumberOfArray2 = await koconutArray2
* .minBy(async eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray2)
* // ↑ 19
*
* const smallest1sDigitNumberOfArray2 = await koconutArray2
* .minBy(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(smallest1sDigitNumberOfArray2)
* // ↑ 32
* ```
*/
minBy(
selector: Selector<CombinedDataType, number | string | KoconutComparable>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType>;
/**
* Returns the first element yielding the smallest value of the given function or ```null``` if there are no elements.
*
* @param {Selector<CombinedDataType, number | string | KoconutComparable>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @return {KoconutPrimitive<CombinedDataType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,2,3,4,5)
*
* const smallestNumberOfArray = await koconutArray
* .minByOrNull(eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray)
* // ↑ 1
*
* const smallestNumberOfEmptyArray = await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .minByOrNull(eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const shortestStringOfSet = await koconutSet
* .minByOrNull(eachString => eachString.length)
* .yield()
* console.log(shortestStringOfSet)
* // ↑ a
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of(1, 12, 123)
* .associateWith(eachNumber => eachNumber.toString())
*
* const shortestDigitsEntryOfMap = await koconutMap
* .minByOrNull(eachEntry => eachEntry.value.length)
* .yield()
* console.log(shortestDigitsEntryOfMap)
* // ↑ Entry { keyElement: 1, valueElement: '1' }
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(19,27,32)
*
* const smallestNumberOfArray2 = await koconutArray2
* .minByOrNull(async eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray2)
* // ↑ 19
*
* const smallest1sDigitNumberOfArray2 = await koconutArray2
* .minByOrNull(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(smallest1sDigitNumberOfArray2)
* // ↑ 32
* ```
*/
minByOrNull(
selector: Selector<CombinedDataType, number | string | KoconutComparable>,
thisArg?: any,
): KoconutPrimitive<CombinedDataType | null>;
/**
* Returns the smallest value among all values produced by ```selector``` function applied to each element in the collection or
* throws {@link KoconutNoSuchElementException} if there are no elements.
*
* @param {Selector<CombinedDataType, number | string | ComparableType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @returns {KoconutPrimitive<number | string | ComparableType>}
*
* @throws {@link KoconutNoSuchElementException}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,7,9)
*
* const smallestRemainderNumberDividedBy5OfArray = await koconutArray
* .minOf(eachNumber => eachNumber % 5)
* .yield()
* console.log(smallestRemainderNumberDividedBy5OfArray)
* // ↑ 1
*
* try {
* await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .minOf(eachNumber => eachNumber % 5)
* .yield()
* } catch(error) {
* console.log(error.name)
* // ↑ Koconut No Such Element Exception
* // i.e. -- Array is filtered.
* // No element in 1 to 5 is greater than 10.
* }
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const shortestStringLengthOfSet = await koconutSet
* .minOf(eachString => eachString.length)
* .yield()
* console.log(shortestStringLengthOfSet)
* // ↑ 1
*
* class ComparableString implements KoconutComparable{
* str : string
* constructor(str : string) {
* this.str = str
* }
* // Override
* compareTo(other : ComparableString) : number {
* return this.str.length - other.str.length
* }
* }
* const minComparableString = await koconutSet
* .minOf(eachString => new ComparableString(eachString))
* .yield()
* console.log(minComparableString)
* // ↑ ComparableString { str: 'a' }
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const shortestStringLengthOfMap = await koconutMap
* .minOf(eachEntry => eachEntry.key)
* .yield()
* console.log(shortestStringLengthOfMap)
* // ↑ 1
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const smallestNumberOfArray2 = await koconutArray2
* .minOf(async eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray2)
* // ↑ 12
*
* const smallest1sDigitOfArray2 = await koconutArray2
* .minOf(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(smallest1sDigitOfArray2)
* // ↑ 0
* ```
*/
minOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, number | string | ComparableType>,
thisArg: any,
): KoconutPrimitive<number | string | ComparableType>;
/** @ignore */
minOf(
selector: Selector<CombinedDataType, number>,
thisArg: any,
): KoconutPrimitive<number>;
/** @ignore */
minOf(selector: Selector<CombinedDataType, number>): KoconutPrimitive<number>;
/** @ignore */
minOf(
selector: Selector<CombinedDataType, string>,
thisArg: any,
): KoconutPrimitive<string>;
/** @ignore */
minOf(selector: Selector<CombinedDataType, string>): KoconutPrimitive<string>;
/** @ignore */
minOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
thisArg: any,
): KoconutPrimitive<ComparableType>;
/** @ignore */
minOf<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
): KoconutPrimitive<ComparableType>;
/**
* Returns the smallest value among all values produced by ```selector``` function applied to each element in the collection or
* ```null``` if there are no elements.
*
* @param {Selector<CombinedDataType, number | string | ComparableType>} selector A callback function that accepts an argument. The method calls the ```selector``` one time for each element in object.
*
* @param {any} thisArg An object to which the ```this``` keyword can refer in the ```selector```. If ```thisArg``` is omitted, ```null``` is used as the ```this``` value.
*
* @returns {KoconutPrimitive<number | string | ComparableType | null>}
*
* @category Calculator
*
* @since 1.0.10
*
* @example
* ```typescript
* // Case 1 -- KoconutArray
* const koconutArray = KoconutArray.of(1,7,9)
*
* const smallestRemainderNumberDividedBy5OfArray = await koconutArray
* .minOfOrNull(eachNumber => eachNumber % 5)
* .yield()
* console.log(smallestRemainderNumberDividedBy5OfArray)
* // ↑ 1
*
* const smallestRemainderNumberDividedBy5OfEmptyArray = await koconutArray
* .filter(eachNumber => eachNumber > 10)
* .minOfOrNull(eachNumber => eachNumber % 5)
* .yield()
* console.log(smallestRemainderNumberDividedBy5OfEmptyArray)
* // ↑ null
*
* // Case 2 -- KoconutSet
* const koconutSet = KoconutSet.of("a", "ab", "abc")
*
* const shortestStringLengthOfSet = await koconutSet
* .minOfOrNull(eachString => eachString.length)
* .yield()
* console.log(shortestStringLengthOfSet)
* // ↑ 1
*
* class ComparableString implements KoconutComparable{
* str : string
* constructor(str : string) {
* this.str = str
* }
* // Override
* compareTo(other : ComparableString) : number {
* return this.str.length - other.str.length
* }
* }
* const minComparableString = await koconutSet
* .minOfOrNull(eachString => new ComparableString(eachString))
* .yield()
* console.log(minComparableString)
* // ↑ ComparableString { str: 'a' }
*
* // Case 3 -- KoconutMap
* const koconutMap = KoconutArray.of("a", "ab", "abc")
* .associate(eachString => [eachString.length, eachString])
*
* const shortestStringLengthOfMap = await koconutMap
* .minOfOrNull(eachEntry => eachEntry.key)
* .yield()
* console.log(shortestStringLengthOfMap)
* // ↑ 1
*
* // Case 4 -- You can also do it asynchronously
* const koconutArray2 = KoconutArray.of(12,51,32,45,50)
*
* const smallestNumberOfArray2 = await koconutArray2
* .minOfOrNull(async eachNumber => eachNumber)
* .yield()
* console.log(smallestNumberOfArray2)
* // ↑ 12
*
* const smallest1sDigitOfArray2 = await koconutArray2
* .minOfOrNull(eachNumber => new Promise(resolve => {
* resolve(eachNumber % 10)
* }))
* .yield()
* console.log(smallest1sDigitOfArray2)
* // ↑ 0
* ```
*/
minOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, number | string | ComparableType>,
thisArg: any,
): KoconutPrimitive<number | string | ComparableType | null>;
/** @ignore */
minOfOrNull(
selector: Selector<CombinedDataType, number>,
thisArg: any,
): KoconutPrimitive<number | null>;
/** @ignore */
minOfOrNull(
selector: Selector<CombinedDataType, number>,
): KoconutPrimitive<number | null>;
/** @ignore */
minOfOrNull(
selector: Selector<CombinedDataType, string>,
thisArg: any,
): KoconutPrimitive<string | null>;
/** @ignore */
minOfOrNull(
selector: Selector<CombinedDataType, string>,
): KoconutPrimitive<string | null>;
/** @ignore */
minOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
thisArg: any,
): KoconutPrimitive<ComparableType | null>;
/** @ignore */
minOfOrNull<ComparableType extends KoconutComparable>(
selector: Selector<CombinedDataType, ComparableType>,
): KoconutPrimitive<ComparableType>;
/**
* Returns the smallest value according to the provided ```comparator``` among all values
* produced by ```selector``` function applied to each element in