Array Utilities

/**
 * Gets the last element without removing it
 * @param {Array<T>|string} array - Array to peek at
 * @return {T} Last element
 * @template T
 */
goog.array.peek = function(array) {};

/**
 * Gets the last element of an array
 * @param {Array<T>} array - Array to get last element from
 * @return {T} Last element
 * @template T
 */
goog.array.last = function(array) {};

/**
 * Finds the index of an element in an array
 * @param {Array<T>} arr - Array to search
 * @param {T} obj - Element to find
 * @param {number=} opt_fromIndex - Starting index
 * @return {number} Index of element, -1 if not found
 * @template T
 */
goog.array.indexOf = function(arr, obj, opt_fromIndex) {};

/**
 * Finds the last index of an element in an array
 * @param {Array<T>} arr - Array to search
 * @param {T} obj - Element to find
 * @param {number=} opt_fromIndex - Starting index from end
 * @return {number} Last index of element, -1 if not found
 * @template T
 */
goog.array.lastIndexOf = function(arr, obj, opt_fromIndex) {};

/**
 * Tests if array contains an element
 * @param {Array<T>} arr - Array to test
 * @param {T} obj - Element to look for
 * @return {boolean} True if element is found
 * @template T
 */
goog.array.contains = function(arr, obj) {};

/**
 * Tests if array is empty
 * @param {Array<T>} arr - Array to test
 * @return {boolean} True if empty
 * @template T
 */
goog.array.isEmpty = function(arr) {};

/**
 * Finds the first element matching a predicate
 * @param {Array<T>} arr - Array to search
 * @param {function(T, number, Array<T>): boolean} f - Predicate function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {T} First matching element or null
 * @template T
 */
goog.array.find = function(arr, f, opt_obj) {};

/**
 * Finds the index of first element matching a predicate
 * @param {Array<T>} arr - Array to search
 * @param {function(T, number, Array<T>): boolean} f - Predicate function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {number} Index of first match or -1
 * @template T
 */
goog.array.findIndex = function(arr, f, opt_obj) {};

/**
 * Finds the last element matching a predicate
 * @param {Array<T>} arr - Array to search
 * @param {function(T, number, Array<T>): boolean} f - Predicate function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {T} Last matching element or null
 * @template T
 */
goog.array.findRight = function(arr, f, opt_obj) {};

/**
 * Finds the index of last element matching a predicate
 * @param {Array<T>} arr - Array to search
 * @param {function(T, number, Array<T>): boolean} f - Predicate function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {number} Index of last match or -1
 * @template T
 */
goog.array.findIndexRight = function(arr, f, opt_obj) {};

/**
 * Iterates over array elements
 * @param {Array<T>} arr - Array to iterate
 * @param {function(T, number, Array<T>)} f - Iterator function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @template T
 */
goog.array.forEach = function(arr, f, opt_obj) {};

/**
 * Iterates over array elements in reverse order
 * @param {Array<T>} arr - Array to iterate
 * @param {function(T, number, Array<T>)} f - Iterator function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @template T
 */
goog.array.forEachRight = function(arr, f, opt_obj) {};

/**
 * Creates new array with elements passing a test
 * @param {Array<T>} arr - Array to filter
 * @param {function(T, number, Array<T>): boolean} f - Test function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Array<T>} Filtered array
 * @template T
 */
goog.array.filter = function(arr, f, opt_obj) {};

/**
 * Creates new array with transformed elements
 * @param {Array<T>} arr - Array to map
 * @param {function(T, number, Array<T>): R} f - Transform function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Array<R>} Mapped array
 * @template T,R
 */
goog.array.map = function(arr, f, opt_obj) {};

/**
 * Reduces array to single value
 * @param {Array<T>} arr - Array to reduce
 * @param {function(R, T, number, Array<T>): R} f - Reducer function
 * @param {R} val - Initial value
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {R} Reduced value
 * @template T,R
 */
goog.array.reduce = function(arr, f, val, opt_obj) {};

/**
 * Reduces array from right to single value
 * @param {Array<T>} arr - Array to reduce
 * @param {function(R, T, number, Array<T>): R} f - Reducer function
 * @param {R} val - Initial value
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {R} Reduced value
 * @template T,R
 */
goog.array.reduceRight = function(arr, f, val, opt_obj) {};

/**
 * Tests if some elements pass a test
 * @param {Array<T>} arr - Array to test
 * @param {function(T, number, Array<T>): boolean} f - Test function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {boolean} True if any element passes test
 * @template T
 */
goog.array.some = function(arr, f, opt_obj) {};

/**
 * Tests if all elements pass a test
 * @param {Array<T>} arr - Array to test
 * @param {function(T, number, Array<T>): boolean} f - Test function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {boolean} True if all elements pass test
 * @template T
 */
goog.array.every = function(arr, f, opt_obj) {};

/**
 * Removes all elements from array
 * @param {Array} arr - Array to clear
 */
goog.array.clear = function(arr) {};

/**
 * Inserts element if not already present
 * @param {Array<T>} arr - Array to insert into
 * @param {T} obj - Element to insert
 * @template T
 */
goog.array.insert = function(arr, obj) {};

/**
 * Inserts element at specific index
 * @param {Array<T>} arr - Array to insert into
 * @param {T} obj - Element to insert
 * @param {number=} opt_i - Index to insert at
 * @template T
 */
goog.array.insertAt = function(arr, obj, opt_i) {};

/**
 * Inserts array of elements at specific index
 * @param {Array<T>} arr - Array to insert into
 * @param {Array<T>} elementsToAdd - Elements to insert
 * @param {number=} opt_i - Index to insert at
 * @template T
 */
goog.array.insertArrayAt = function(arr, elementsToAdd, opt_i) {};

/**
 * Inserts element before another element
 * @param {Array<T>} arr - Array to insert into
 * @param {T} obj - Element to insert
 * @param {T=} opt_obj2 - Element to insert before
 * @template T
 */
goog.array.insertBefore = function(arr, obj, opt_obj2) {};

/**
 * Removes first occurrence of element
 * @param {Array<T>} arr - Array to remove from
 * @param {T} obj - Element to remove
 * @return {boolean} True if element was removed
 * @template T
 */
goog.array.remove = function(arr, obj) {};

/**
 * Removes element at specific index
 * @param {Array<T>} arr - Array to remove from
 * @param {number} i - Index to remove at
 * @return {boolean} True if element was removed
 * @template T
 */
goog.array.removeAt = function(arr, i) {};

/**
 * Removes first element matching predicate
 * @param {Array<T>} arr - Array to remove from
 * @param {function(T, number, Array<T>): boolean} f - Test function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {boolean} True if element was removed
 * @template T
 */
goog.array.removeIf = function(arr, f, opt_obj) {};

/**
 * Removes all elements matching predicate
 * @param {Array<T>} arr - Array to remove from
 * @param {function(T, number, Array<T>): boolean} f - Test function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {number} Number of elements removed
 * @template T
 */
goog.array.removeAllIf = function(arr, f, opt_obj) {};

/**
 * Concatenates multiple arrays
 * @param {...Array<T>} var_args - Arrays to concatenate
 * @return {Array<T>} Concatenated array
 * @template T
 */
goog.array.concat = function(var_args) {};

/**
 * Joins multiple arrays together (concatenates arrays, not string join!)
 * @param {...Array<T>} var_args - Arrays to concatenate
 * @return {Array<T>} Concatenated array
 * @template T
 */
goog.array.join = function(var_args) {};

/**
 * Converts array-like object to array
 * @param {Array<T>|Arguments|NodeList} object - Object to convert
 * @return {Array<T>} Converted array
 * @template T
 */
goog.array.toArray = function(object) {};

/**
 * Creates array by copying elements at specified indices
 * @param {Array<T>} arr - Source array
 * @param {Array<number>} index_arr - Array of indices
 * @return {Array<T>} New array with copied elements
 * @template T
 */
goog.array.copyByIndex = function(arr, index_arr) {};

/**
 * Maps and concatenates results
 * @param {Array<T>} arr - Array to process
 * @param {function(T, number, Array<T>): Array<R>} f - Map function returning arrays
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Array<R>} Flattened result
 * @template T,R
 */
goog.array.concatMap = function(arr, f, opt_obj) {};

/**
 * Counts elements matching a predicate
 * @param {Array<T>} arr - Array to count in
 * @param {function(T, number, Array<T>): boolean} f - Predicate function
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {number} Count of matching elements
 * @template T
 */
goog.array.count = function(arr, f, opt_obj) {};

/**
 * Removes last occurrence of element
 * @param {Array<T>} arr - Array to remove from
 * @param {T} obj - Element to remove
 * @return {boolean} True if element was removed
 * @template T
 */
goog.array.removeLast = function(arr, obj) {};

/**
 * Shallow copies array (alias for toArray)
 * @param {Array<T>} arr - Array to clone
 * @return {Array<T>} Cloned array
 * @template T
 */
goog.array.clone = function(arr) {};

/**
 * Extends array with other arrays/elements in-place
 * @param {Array<T>} arr1 - Array to extend
 * @param {...*} var_args - Arrays or elements to add
 * @template T
 */
goog.array.extend = function(arr1, var_args) {};

/**
 * Generic splice operation
 * @param {Array<T>} arr - Array to splice
 * @param {number|undefined} index - Start index
 * @param {number} howMany - Number of elements to remove
 * @param {...T} var_args - Elements to insert
 * @return {Array<T>} Array of removed elements
 * @template T
 */
goog.array.splice = function(arr, index, howMany, var_args) {};

/**
 * Generic slice operation
 * @param {Array<T>} arr - Array to slice
 * @param {number} start - Start index
 * @param {number=} opt_end - End index
 * @return {Array<T>} Sliced array
 * @template T
 */
goog.array.slice = function(arr, start, opt_end) {};

/**
 * Removes duplicate elements from array
 * @param {Array<T>} arr - Array to remove duplicates from
 * @param {Array=} opt_rv - Optional result array
 * @param {function(T): string=} opt_hashFn - Hash function for comparison
 * @template T
 */
goog.array.removeDuplicates = function(arr, opt_rv, opt_hashFn) {};

/**
 * Binary search in sorted array
 * @param {Array<T>} arr - Sorted array to search
 * @param {T} target - Target value
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @return {number} Index if found, negative insertion point if not
 * @template T
 */
goog.array.binarySearch = function(arr, target, opt_compareFn) {};

/**
 * Binary selection with evaluator function
 * @param {Array<T>} arr - Array to search
 * @param {function(T): number} evaluator - Function returning -1, 0, or 1
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {number} Index if found, negative insertion point if not
 * @template T
 */
goog.array.binarySelect = function(arr, evaluator, opt_obj) {};

/**
 * Inserts element maintaining sort order
 * @param {Array<T>} arr - Sorted array to insert into
 * @param {T} value - Value to insert
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @return {boolean} True if value was inserted
 * @template T
 */
goog.array.binaryInsert = function(arr, value, opt_compareFn) {};

/**
 * Removes element from sorted array
 * @param {Array<T>} arr - Sorted array to remove from
 * @param {T} value - Value to remove
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @return {boolean} True if value was removed
 * @template T
 */
goog.array.binaryRemove = function(arr, value, opt_compareFn) {};

/**
 * Groups elements into object buckets
 * @param {Array<T>} arr - Array to group
 * @param {function(T): string} func - Function returning bucket key
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Object<string, Array<T>>} Object with grouped arrays
 * @template T
 */
goog.array.bucket = function(arr, func, opt_obj) {};

/**
 * Groups elements into ES6 Map buckets
 * @param {Array<T>} arr - Array to group
 * @param {function(T): K} func - Function returning bucket key
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Map<K, Array<T>>} Map with grouped arrays
 * @template T,K
 */
goog.array.bucketToMap = function(arr, func, opt_obj) {};

/**
 * Creates object from array using key function
 * @param {Array<T>} arr - Array to convert
 * @param {function(T): string} func - Function returning object key
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Object<string, T>} Object with array elements as values
 * @template T
 */
goog.array.toObject = function(arr, func, opt_obj) {};

/**
 * Creates ES6 Map from array using key function
 * @param {Array<T>} arr - Array to convert
 * @param {function(T): K} func - Function returning map key
 * @param {Object=} opt_obj - Object to bind 'this' to
 * @return {Map<K, T>} Map with array elements as values
 * @template T,K
 */
goog.array.toMap = function(arr, func, opt_obj) {};

/**
 * Creates arithmetic sequence array
 * @param {number} startOrStop - Start value (or stop if only argument)
 * @param {number=} opt_stop - Stop value (exclusive)
 * @param {number=} opt_step - Step size (default 1)
 * @return {Array<number>} Array of numbers
 */
goog.array.range = function(startOrStop, opt_stop, opt_step) {};

/**
 * Creates array of repeated values
 * @param {T} value - Value to repeat
 * @param {number} n - Number of repetitions
 * @return {Array<T>} Array with repeated values
 * @template T
 */
goog.array.repeat = function(value, n) {};

/**
 * Recursively flattens nested arrays
 * @param {...*} var_args - Arrays or values to flatten
 * @return {Array} Flattened array
 */
goog.array.flatten = function(var_args) {};

/**
 * Rotates array elements in-place
 * @param {Array<T>} array - Array to rotate
 * @param {number} n - Number of positions to rotate (positive = right)
 * @return {Array<T>} The rotated array (same reference)
 * @template T
 */
goog.array.rotate = function(array, n) {};

/**
 * Moves element to new position within array
 * @param {Array<T>} arr - Array to modify
 * @param {number} fromIndex - Current index of element
 * @param {number} toIndex - Target index for element
 * @template T
 */
goog.array.moveItem = function(arr, fromIndex, toIndex) {};

/**
 * Combines multiple arrays element-wise
 * @param {...Array} var_args - Arrays to combine
 * @return {Array<Array>} Array of combined elements
 */
goog.array.zip = function(var_args) {};

/**
 * Randomizes array order using Fisher-Yates algorithm
 * @param {Array<T>} arr - Array to shuffle
 * @param {function(): number=} opt_randFn - Random function (default Math.random)
 * @template T
 */
goog.array.shuffle = function(arr, opt_randFn) {};

/**
 * Default comparison function for sorting
 * @param {*} a - First value
 * @param {*} b - Second value
 * @return {number} -1, 0, or 1 for less, equal, greater
 */
goog.array.defaultCompare = function(a, b) {};

/**
 * Inverse of default comparison function
 * @param {*} a - First value
 * @param {*} b - Second value
 * @return {number} 1, 0, or -1 for less, equal, greater
 */
goog.array.inverseDefaultCompare = function(a, b) {};

/**
 * Default equality comparison function
 * @param {*} a - First value
 * @param {*} b - Second value
 * @return {boolean} True if values are equal
 */
goog.array.defaultCompareEquality = function(a, b) {};

/**
 * Sorts array in place
 * @param {Array<T>} arr - Array to sort
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @template T
 */
goog.array.sort = function(arr, opt_compareFn) {};

/**
 * Stable sort that preserves order of equal elements
 * @param {Array<T>} arr - Array to sort
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @template T
 */
goog.array.stableSort = function(arr, opt_compareFn) {};

/**
 * Sorts array by key function
 * @param {Array<T>} arr - Array to sort
 * @param {function(T): K} keyFn - Key extraction function
 * @param {function(K, K): number=} opt_compareFn - Key comparison function
 * @template T,K
 */
goog.array.sortByKey = function(arr, keyFn, opt_compareFn) {};

/**
 * Sorts objects by property key
 * @param {Array<Object>} arr - Array of objects to sort
 * @param {string} key - Property name to sort by
 * @param {function(*, *): number=} opt_compareFn - Comparison function
 */
goog.array.sortObjectsByKey = function(arr, key, opt_compareFn) {};

/**
 * Tests if array is sorted
 * @param {Array<T>} arr - Array to test
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @param {boolean=} opt_strict - Whether to require strict ordering
 * @return {boolean} True if sorted
 * @template T
 */
goog.array.isSorted = function(arr, opt_compareFn, opt_strict) {};

/**
 * Compares two arrays for equality
 * @param {Array<T>} arr1 - First array
 * @param {Array<T>} arr2 - Second array
 * @param {function(T, T): boolean=} opt_equalsFn - Equality function
 * @return {boolean} True if arrays are equal
 * @template T
 */
goog.array.equals = function(arr1, arr2, opt_equalsFn) {};

/**
 * Three-way comparison of arrays
 * @param {Array<T>} arr1 - First array
 * @param {Array<T>} arr2 - Second array
 * @param {function(T, T): number=} opt_compareFn - Comparison function
 * @return {number} -1, 0, or 1 for less, equal, greater
 * @template T
 */
goog.array.compare3 = function(arr1, arr2, opt_compareFn) {};

// Array search and access
var numbers = [1, 2, 3, 4, 5];
var index = goog.array.indexOf(numbers, 3); // Returns 2
var contains = goog.array.contains(numbers, 4); // Returns true

// Array iteration
var doubled = goog.array.map(numbers, function(n) { return n * 2; });
var evens = goog.array.filter(numbers, function(n) { return n % 2 === 0; });

// Array modification
var fruits = ['apple', 'banana'];
goog.array.insert(fruits, 'cherry'); // ['apple', 'banana', 'cherry']
goog.array.remove(fruits, 'banana'); // ['apple', 'cherry']

// Array creation and manipulation
var sequence = goog.array.range(1, 6); // [1, 2, 3, 4, 5]
var repeated = goog.array.repeat('x', 3); // ['x', 'x', 'x']
var flattened = goog.array.flatten([1, [2, 3], [4, [5, 6]]]); // [1, 2, 3, 4, 5, 6]

// Binary search (requires sorted array)
var sorted = [1, 3, 5, 7, 9];
var position = goog.array.binarySearch(sorted, 5); // Returns 2
goog.array.binaryInsert(sorted, 6); // [1, 3, 5, 6, 7, 9]

// Data structure conversions
var users = [{name: 'Alice', age: 25}, {name: 'Bob', age: 30}];
var usersByName = goog.array.toObject(users, function(user) { return user.name; });
// Result: {Alice: {name: 'Alice', age: 25}, Bob: {name: 'Bob', age: 30}}

// Array sorting
var names = ['Charlie', 'Alice', 'Bob'];
goog.array.sort(names); // ['Alice', 'Bob', 'Charlie']
goog.array.shuffle(names); // Random order