Search

/**
 * Returns the least element according to the specified comparator or accessor
 * @param iterable - The iterable to search
 * @param comparator - Comparator function or accessor function
 * @returns The least element or undefined if no comparable elements exist
 */
function least(iterable: Iterable<any>, comparator?: ((a: any, b: any) => number) | ((d: any) => any)): any;

import { least } from "d3-array";

const data = [{foo: 42}, {foo: 91}];

// With comparator
least(data, (a, b) => a.foo - b.foo); // {foo: 42}
least(data, (a, b) => b.foo - a.foo); // {foo: 91}

// With accessor
least(data, a => a.foo); // {foo: 42}

/**
 * Returns the index of the least element according to the specified comparator or accessor
 * @param iterable - The iterable to search
 * @param comparator - Comparator function or accessor function
 * @returns The index of the least element or -1 if no comparable elements exist
 */
function leastIndex(iterable: Iterable<any>, comparator?: ((a: any, b: any) => number) | ((d: any) => any)): number;

/**
 * @deprecated Use leastIndex() instead
 * Legacy alias for leastIndex
 */
function scan(iterable: Iterable<any>, comparator?: ((a: any, b: any) => number) | ((d: any) => any)): number;

/**
 * Returns the greatest element according to the specified comparator or accessor
 * @param iterable - The iterable to search
 * @param comparator - Comparator function or accessor function
 * @returns The greatest element or undefined if no comparable elements exist
 */
function greatest(iterable: Iterable<any>, comparator?: ((a: any, b: any) => number) | ((d: any) => any)): any;

/**
 * Returns the index of the greatest element according to the specified comparator or accessor
 * @param iterable - The iterable to search
 * @param comparator - Comparator function or accessor function
 * @returns The index of the greatest element or -1 if no comparable elements exist
 */
function greatestIndex(iterable: Iterable<any>, comparator?: ((a: any, b: any) => number) | ((d: any) => any)): number;

/**
 * Returns the insertion point for x in array to maintain sorted order (left side)
 * @param array - The sorted array to search
 * @param x - The value to find insertion point for
 * @param lo - Starting index (inclusive, defaults to 0)
 * @param hi - Ending index (exclusive, defaults to array.length)
 * @returns The insertion index
 */
function bisectLeft(array: any[], x: any, lo?: number, hi?: number): number;

/**
 * Returns the insertion point for x in array to maintain sorted order (right side)
 * @param array - The sorted array to search
 * @param x - The value to find insertion point for
 * @param lo - Starting index (inclusive, defaults to 0)
 * @param hi - Ending index (exclusive, defaults to array.length)
 * @returns The insertion index
 */
function bisectRight(array: any[], x: any, lo?: number, hi?: number): number;
function bisect(array: any[], x: any, lo?: number, hi?: number): number; // Alias for bisectRight

import { bisectLeft, bisectRight } from "d3-array";

const arr = [1, 2, 4, 4, 6];

bisectLeft(arr, 4);  // 2 (insert before existing 4s)
bisectRight(arr, 4); // 4 (insert after existing 4s)
bisectLeft(arr, 3);  // 2 (between 2 and 4)
bisectRight(arr, 5); // 4 (between 4 and 6)

/**
 * Returns the index of the value closest to x in the given array
 * @param array - The sorted array to search
 * @param x - The target value
 * @param lo - Starting index (inclusive, defaults to 0)
 * @param hi - Ending index (exclusive, defaults to array.length)
 * @returns The index of the closest value
 */
function bisectCenter(array: any[], x: any, lo?: number, hi?: number): number;

/**
 * Returns a new bisector using the specified accessor or comparator function
 * @param accessor - Function to extract values for comparison
 * @returns Bisector object with left, right, and center methods
 */
function bisector(accessor: (d: any) => any): Bisector;

/**
 * Returns a new bisector using the specified comparator function
 * @param comparator - Function to compare elements (d, x) => number
 * @returns Bisector object with left, right, and center methods
 */
function bisector(comparator: (d: any, x: any) => number): Bisector;

interface Bisector {
  /**
   * Equivalent to bisectLeft, but uses this bisector's associated comparator
   */
  left(array: any[], x: any, lo?: number, hi?: number): number;
  
  /**
   * Equivalent to bisectRight, but uses this bisector's associated comparator
   */
  right(array: any[], x: any, lo?: number, hi?: number): number;
  
  /**
   * Returns the index of the closest value to x in the given sorted array
   */
  center(array: any[], x: any, lo?: number, hi?: number): number;
}

import { bisector } from "d3-array";

const data = [
  {date: new Date(2011, 1, 1), value: 0.5},
  {date: new Date(2011, 2, 1), value: 0.6},
  {date: new Date(2011, 3, 1), value: 0.7},
  {date: new Date(2011, 4, 1), value: 0.8}
];

// Using accessor
const bisectDate = bisector(d => d.date).right;
const index = bisectDate(data, new Date(2011, 2, 15));

// Using comparator
const bisectDateComparator = bisector((d, x) => d.date - x).right;
const index2 = bisectDateComparator(data, new Date(2011, 2, 15));

/**
 * Rearranges the array so that the kth element is in its sorted position
 * @param array - The array to rearrange (modified in-place)
 * @param k - The target index
 * @param left - Starting index (defaults to 0)
 * @param right - Ending index (defaults to array.length - 1)
 * @param compare - Comparison function (defaults to ascending)
 * @returns The array (modified in-place)
 */
function quickselect(
  array: any[], 
  k: number, 
  left?: number, 
  right?: number, 
  compare?: (a: any, b: any) => number
): any[];

import { quickselect } from "d3-array";

const arr = [3, 1, 4, 1, 5, 9, 2, 6];
quickselect(arr, 3); // Partially sorts so arr[3] is the 4th smallest element

/**
 * Returns -1, 0, or 1 for natural order comparison
 * @param a - First value to compare
 * @param b - Second value to compare
 * @returns -1 if a < b, 1 if a > b, 0 if equal, NaN if not comparable
 */
function ascending(a: any, b: any): number;

import { ascending } from "d3-array";

ascending(1, 2);     // -1
ascending(2, 1);     // 1
ascending(1, 1);     // 0
ascending(null, 1);  // NaN

/**
 * Returns -1, 0, or 1 for reverse natural order comparison
 * @param a - First value to compare
 * @param b - Second value to compare
 * @returns 1 if a < b, -1 if a > b, 0 if equal, NaN if not comparable
 */
function descending(a: any, b: any): number;

import { descending, ascending } from "d3-array";

// Using with built-in sort
[3, 1, 4, 1, 5].sort(ascending);  // [1, 1, 3, 4, 5]
[3, 1, 4, 1, 5].sort(descending); // [5, 4, 3, 1, 1]

// Natural order vs lexicographic order
["10", "2"].sort();           // ["10", "2"] (lexicographic)
["10", "2"].sort(ascending);  // ["10", "2"] (natural order for strings)
[10, 2].sort(ascending);      // [2, 10] (natural order for numbers)