1 | import type {
|
2 | NearestHours,
|
3 | NearestToUnitOptions,
|
4 | RoundingOptions,
|
5 | } from "./types.js";
|
6 | /**
|
7 | * The {@link roundToNearestHours} function options.
|
8 | */
|
9 | export interface RoundToNearestHoursOptions
|
10 | extends NearestToUnitOptions<NearestHours>,
|
11 | RoundingOptions {}
|
12 | /**
|
13 | * @name roundToNearestHours
|
14 | * @category Hour Helpers
|
15 | * @summary Rounds the given date to the nearest hour
|
16 | *
|
17 | * @description
|
18 | * Rounds the given date to the nearest hour (or number of hours).
|
19 | * Rounds up when the given date is exactly between the nearest round hours.
|
20 | *
|
21 | * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
|
22 | *
|
23 | * @param date - The date to round
|
24 | * @param options - An object with options.
|
25 | *
|
26 | * @returns The new date rounded to the closest hour
|
27 | *
|
28 | * @example
|
29 | * // Round 10 July 2014 12:34:56 to nearest hour:
|
30 | * const result = roundToNearestHours(new Date(2014, 6, 10, 12, 34, 56))
|
31 | * //=> Thu Jul 10 2014 13:00:00
|
32 | *
|
33 | * @example
|
34 | * // Round 10 July 2014 12:34:56 to nearest half hour:
|
35 | * const result = roundToNearestHours(new Date(2014, 6, 10, 12, 34, 56), { nearestTo: 6 })
|
36 | * //=> Thu Jul 10 2014 12:00:00
|
37 |
|
38 | * @example
|
39 | * // Round 10 July 2014 12:34:56 to nearest half hour:
|
40 | * const result = roundToNearestHours(new Date(2014, 6, 10, 12, 34, 56), { nearestTo: 8 })
|
41 | * //=> Thu Jul 10 2014 16:00:00
|
42 |
|
43 | * @example
|
44 | * // Floor (rounds down) 10 July 2014 12:34:56 to nearest hour:
|
45 | * const result = roundToNearestHours(new Date(2014, 6, 10, 1, 23, 45), { roundingMethod: 'ceil' })
|
46 | * //=> Thu Jul 10 2014 02:00:00
|
47 | *
|
48 | * @example
|
49 | * // Ceil (rounds up) 10 July 2014 12:34:56 to nearest quarter hour:
|
50 | * const result = roundToNearestHours(new Date(2014, 6, 10, 12, 34, 56), { roundingMethod: 'floor', nearestTo: 8 })
|
51 | * //=> Thu Jul 10 2014 08:00:00
|
52 | */
|
53 | export declare function roundToNearestHours<DateType extends Date>(
|
54 | date: DateType | number | string,
|
55 | options?: RoundToNearestHoursOptions,
|
56 | ): Date;
|