date-vir/dist/formatting/simple-strings.d.ts

Easy and explicit dates and times.

import type { SetOptionalAndNullable } from '@augment-vir/common';
import { FullDate } from '../full-date/full-date-shape.js';
import { JustDateString, JustTimeString, JustTimeWithSecondsString } from './string-format-types.js';
/**
 * Create a string based on just the date parts of a FullDate.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * Example output: `'2023-12-05'`
 *
 * @category Internal
 */
export declare function toSimpleDatePartString(fullDate: Pick<FullDate, 'year' | 'month' | 'day'>): JustDateString;
/**
 * Creates a string based on just the time parts of a FullDate.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * Example output: `'05:32:21'`
 *
 * @category Internal
 */
export declare function toSimpleTimePartString(fullDate: Pick<FullDate, 'hour' | 'minute' | 'second'> | Pick<FullDate, 'hour' | 'minute'>, includeSeconds: boolean): JustTimeWithSecondsString | JustTimeString;
/**
 * The parts of {@link FullDate} required for {@link toDatePartStrings}.
 *
 * @category Internal
 */
export type FullDateForParts = SetOptionalAndNullable<FullDate, 'millisecond'>;
/**
 * Splits a FullDate up into multiple formatted string representations.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * This uses numbers for everything.
 *
 * @category Formatting
 * @example
 *
 * ```ts
 * import {toDatePartStrings, utcTimezone} from 'date-vir';
 *
 * let result = toDatePartStrings(
 *     {
 *         year: 2024,
 *         month: 4,
 *         day: 24,
 *         hour: 6,
 *         minute: 4,
 *         second: 9,
 *         millisecond: 123,
 *         timezone: utcTimezone,
 *     },
 *     {includeSeconds: true},
 * );
 * // outputs:
 * result = {
 *     date: '2024-04-24',
 *     time: '06:04:09',
 *     timezone: 'UTC',
 * };
 * ```
 */
export declare function toDatePartStrings(fullDate: FullDateForParts, options: {
    includeSeconds: true;
}): {
    date: JustDateString;
    time: JustTimeWithSecondsString;
    timezone: string;
};
/**
 * Splits a FullDate up into multiple formatted string representations.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * This uses numbers for everything.
 *
 * @category Formatting
 * @example
 *
 * ```ts
 * import {toDatePartStrings, utcTimezone} from 'date-vir';
 *
 * let result = toDatePartStrings(
 *     {
 *         year: 2024,
 *         month: 4,
 *         day: 24,
 *         hour: 6,
 *         minute: 4,
 *         second: 9,
 *         millisecond: 123,
 *         timezone: utcTimezone,
 *     },
 *     {includeSeconds: true},
 * );
 * // outputs:
 * result = {
 *     date: '2024-04-24',
 *     time: '06:04:09',
 *     timezone: 'UTC',
 * };
 * ```
 */
export declare function toDatePartStrings(fullDate: SetOptionalAndNullable<FullDateForParts, 'second'>, options: {
    includeSeconds: false;
}): {
    date: JustDateString;
    time: JustTimeString;
    timezone: string;
};
/**
 * Splits a FullDate up into multiple formatted string representations.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * This uses numbers for everything.
 *
 * @category Formatting
 * @example
 *
 * ```ts
 * import {toDatePartStrings, utcTimezone} from 'date-vir';
 *
 * let result = toDatePartStrings(
 *     {
 *         year: 2024,
 *         month: 4,
 *         day: 24,
 *         hour: 6,
 *         minute: 4,
 *         second: 9,
 *         millisecond: 123,
 *         timezone: utcTimezone,
 *     },
 *     {includeSeconds: true},
 * );
 * // outputs:
 * result = {
 *     date: '2024-04-24',
 *     time: '06:04:09',
 *     timezone: 'UTC',
 * };
 * ```
 */
export declare function toDatePartStrings(fullDate: FullDateForParts, options: {
    includeSeconds: boolean;
}): {
    date: JustDateString;
    time: JustTimeWithSecondsString | JustTimeString;
    timezone: string;
};
/**
 * Converts a date into a simple, unambiguous date string.
 *
 * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
 *
 * @category Formatting
 * @example
 *
 * ```ts
 * import {toSimpleString} from 'date-vir';
 *
 * let result = toSimpleString(
 *     {
 *         year: 2024,
 *         month: 4,
 *         day: 24,
 *         hour: 6,
 *         minute: 4,
 *         second: 9,
 *         millisecond: 123,
 *         timezone: utcTimezone,
 *     },
 *     {
 *         includeSeconds: false,
 *         includeTimezone: false,
 *     },
 * );
 * // outputs:
 * result = '2024-04-24 06:04';
 * ```
 */
export declare function toSimpleString(fullDate: FullDateForParts, options: {
    includeSeconds: boolean;
    includeTimezone: boolean;
}): string;