跳转到内容
surrealdb.js

时间段

Duration 类用于表示时间段。

导入

import { Duration } from "@tai-kun/surrealdb/decodeonly-datatypes";
import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";
import { Duration } from "@tai-kun/surrealdb/standard-datatypes";

.constructor()

创建一个新的 Duration 对象。

new Duration(
  source:
    | [seconds?: number | bigint, nanoseconds?: undefined]
    | [seconds: number | bigint, nanoseconds?: number | undefined],
); // decode-only, encodable
new Duration(
  source:
    | [seconds?: number | bigint, nanoseconds?: undefined]
    | [seconds: number | bigint, nanoseconds?: number | undefined]
    | number
    | bigint
    | string
    | Duration,
); // standard

参数

source

秒和纳秒对。如果预设为 standard，则可以将更多值转换为 Duration 对象。

number 类型的输入将以毫秒为单位计算。这旨在用于将 Date 对象之间的差值转换为 Duration 对象：

const begin = new Date("2024-06-01T12:00:00.000Z");
const end = new Date("2024-06-01T21:00:00.000Z");
new Duration(end - begin);

bigint 类型的输入将以纳秒为单位计算。这旨在用于将例如 process.hrtime.bigint() 返回的纳秒等高精度时间转换为 Duration 对象：

const begin = process.hrtime.bigint();
await run();
const end = process.hrtime.bigint();
new Duration(end - begin);

string 类型的输入必须是时间段的字符串表示形式。时间段的字符串表示形式是指数字和单位成对出现，连续排列的格式。例如 1h4h30m20s1350ms 表示“1 天 4 小时 30 分 21 秒 350 毫秒”。可用的单位如下：

单位说明转换
ns纳秒
us微秒1us -> 1000ns
ms毫秒1ms -> 1000us
s秒1s -> 1000ms
m分1m -> 60s
h时1h -> 60m
d天1d -> 24h
w周1w -> 7d
y年1y -> 365d

us (0x75, 0x73) 也可以是 µs (0xc2, 0xb5, 0x73) 或 μs (0xce, 0xbc, 0x73)（括号中十六进制数是单位字符串的 UTF-8 编码结果）。

返回值

如果通过 new 调用，Duration 将返回其实例。

.seconds 实例 属性 >=decode-only

时间段的秒部分。在低于 standard 的预设中，它是只读的。值是 0 到 264-1 之间的整数。

.seconds: bigint;

.nanoseconds 实例 属性 >=decode-only

时间段的纳秒部分。在低于 standard 的预设中，它是只读的。值是 0 到 999999999 之间的整数。

.nanoseconds: number;

.parse() 实例 属性 >=encodable

将时间段映射到各个单位。每个单位的值都大于等于 0，小于该单位的最大值。如果时间段为 0，则返回仅具有 nanoseconds 属性为 0 的对象。

.parse(): {
  years?: number;
  weeks?: number;
  days?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
  microseconds?: number;
  nanoseconds?: number;
};

参数

无。

返回值

返回将时间段映射到各个单位的结果。如果单位的值为 0，则省略属性，但如果时间段为 0，则返回仅具有 nanoseconds 属性为 0 的对象。

例子

import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";


const duration = new Duration(0);
console.log(duration.parse());
//-> { nanoseconds: 0 }
import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";


const duration = new Duration(12_345_000n);
console.log(duration.parse());
//-> { milliseconds: 12, microseconds: 345 }

.valueOf() 实例 方法 >=encodable

以纳秒为单位获取时间段。

.valueOf(): bigint;

参数

无。

返回值

以纳秒为单位返回时间段。

import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";


const duration = new Duration(12_345_000n);
console.log(duration.valueOf());
//-> 12345000n

.toString() 实例 方法 >=encodable

获取时间段的字符串表示形式。

.toJSON() 和 .toSurql() 返回与该方法相同的结果。

.toString(): string;

参数

无。

返回值

获取毫秒精度时间的字符串表示形式。

例子

import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";


const duration = new Duration(12_345_000n);
console.log(duration.toString());
//-> 12ms345µs

.toISOString() 实例 方法 >=encodable

以 ISO 格式获取时间段的字符串。

.toISOString(): string;

参数

无。

返回值

以 ISO 格式返回时间段的字符串。

例子

import { Duration } from "@tai-kun/surrealdb/encodable-datatypes";


const duration = new Duration("2m3s456ms");
console.log(duration.toISOString());
//-> P2M3S

.getCompact() 实例 方法 =standard

获取秒和纳秒对。

.getCompact(): [seconds: bigint, nanoseconds: number];

参数

无。

返回值

返回秒和纳秒对。

.setCompact() 实例 方法 =standard

使用秒和纳秒对设置日期时间。

.setCompact(compact: [seconds: bigint, nanoseconds: number]): void;

参数

compact

秒和纳秒对。

返回值

无。

.getYears() 实例 方法 =standard

获取年数。如果结果不是 0 或更大的整数，则返回 0。

.getYears(): number;

参数

无。

返回值

返回表示年份的 0 或更大的整数。

.addYears() 实例 方法 =standard

从时间段中添加指定数量的年份。

.addYears(value: number): void;

参数

value

年份数。

返回值

无。

.subYears() 实例 方法 =standard

从时间段中减去指定数量的年份。

.subYears(value: number): void;

参数

value

年份数。

返回值

无。

.asYears() 实例 方法 =standard

获取年份的毫秒表示。

.asYears(): number;

参数

无。

返回值

年份的毫秒表示。

.getWeeks() 实例 方法 =standard

获取周数。如果结果不是 0 或更大的整数，则返回 0。

.getWeeks(): number;

参数

无。

返回值

返回表示周数的 0 或更大的整数。

.addWeeks() 实例 方法 =standard

从时间段中添加指定数量的周数。

.addWeeks(value: number): void;

参数

value

周数。

返回值

无。

.subWeeks() 实例 方法 =standard

从时间段中减去指定数量的周数。

.subWeeks(value: number): void;

参数

value

周数。

返回值

无。

.asWeeks() 实例 方法 =standard

获取周数的毫秒表示。

.asWeeks(): number;

参数

无。

返回值

周数的毫秒表示。

.getDays() 实例 方法 =standard

获取天数。如果结果不是 0 或更大的整数，则返回 0。

.getDays(): number;

参数

无。

返回值

返回表示天数的 0 或更大的整数。

.addDays() 实例 方法 =standard

从时间段中添加指定数量的天数。

.addDays(value: number): void;

参数

value

天数。

返回值

无。

.subDays() 实例 方法 =standard

从时间段中减去指定数量的天数。

.subDays(value: number): void;

参数

value

天数。

返回值

无。

.asDays() 实例 方法 =standard

获取天数的毫秒表示。

.asDays(): number;

参数

无。

返回值

天数的毫秒表示。

.getHours() 实例 方法 =standard

获取小时数。如果结果不是 0 或更大的整数，则返回 0。

.getHours(): number;

参数

无。

返回值

返回表示小时数的 0 或更大的整数。

.addHours() 实例 方法 =standard

从时间段中添加指定数量的小时数。

.addHours(value: number): void;

参数

value

小时数。

返回值

无。

.subHours() 实例 方法 =standard

从时间段中减去指定数量的小时数。

.subHours(value: number): void;

参数

value

小时数。

返回值

无。

.asHours() 实例 方法 =standard

获取小时数的毫秒表示。

.asHours(): number;

参数

无。

返回值

小时数的毫秒表示。

.getMinutes() 实例 方法 =standard

获取分钟数。如果结果不是 0 或更大的整数，则返回 0。

.getMinutes(): number;

参数

无。

返回值

返回表示分钟数的 0 或更大的整数。

.addMinutes() 实例 方法 =standard

从时间段中添加指定数量的分钟数。

.addMinutes(value: number): void;

参数

value

分钟数。

返回值

无。

.subMinutes() 实例 方法 =standard

从时间段中减去指定数量的分钟数。

.subMinutes(value: number): void;

参数

value

分钟数。

返回值

无。

.asMinutes() 实例 方法 =standard

获取分钟数的毫秒表示。

.asMinutes(): number;

参数

无。

返回值

分钟数的毫秒表示。

.getSeconds() 实例 方法 =standard

获取秒数。如果结果不是 0 或更大的整数，则返回 0。

.getSeconds(): number;

参数

无。

返回值

返回表示秒数的 0 或更大的整数。

.addSeconds() 实例 方法 =standard

从时间段中添加指定数量的秒数。

.addSeconds(value: number): void;

参数

value

秒数。

返回值

无。

.subSeconds() 实例 方法 =standard

从时间段中减去指定数量的秒数。

.subSeconds(value: number): void;

参数

value

秒数。

返回值

无。

.asSeconds() 实例 方法 =standard

获取秒数的毫秒表示。

.asSeconds(): number;

参数

无。

返回值

秒数的毫秒表示。

.getMilliseconds() 实例 方法 =standard

获取毫秒数。如果结果不是 0 或更大的整数，则返回 0。

.getMilliseconds(): number;

参数

无。

返回值

返回表示毫秒数的 0 或更大的整数。

.addMilliseconds() 实例 方法 =standard

从时间段中添加指定数量的毫秒数。

.addMilliseconds(value: number): void;

参数

value

毫秒数。

返回值

无。

.subMilliseconds() 实例 方法 =standard

从时间段中减去指定数量的毫秒数。

.subMilliseconds(value: number): void;

参数

value

毫秒数。

返回值

无。

.asMilliseconds() 实例 方法 =standard

获取毫秒数的毫秒表示。

.asMilliseconds(): number;

参数

无。

返回值

毫秒数的毫秒表示。

.getMicroseconds() 实例 方法 =standard

获取微秒数。如果结果不是 0 或更大的整数，则返回 0。

.getMicroseconds(): number;

参数

无。

返回值

返回表示微秒数的 0 或更大的整数。

.addMicroseconds() 实例 方法 =standard

从时间段中添加指定数量的微秒数。

.addMicroseconds(value: number): void;

参数

value

微秒数。

返回值

无。

.subMicroseconds() 实例 方法 =standard

从时间段中减去指定数量的微秒数。

.subMicroseconds(value: number): void;

参数

value

微秒数。

返回值

无。

.asMicroseconds() 实例 方法 =standard

获取微秒数的毫秒表示。

.asMicroseconds(): number;

参数

无。

返回值

微秒数的毫秒表示。

.getNanoseconds() 实例 方法 =standard

获取纳秒数。如果结果不是 0 或更大的整数，则返回 0。

.getNanoseconds(): number;

参数

无。

返回值

返回表示纳秒数的 0 或更大的整数。

.addNanoseconds() 实例 方法 =standard

从时间段中添加指定数量的纳秒数。

.addNanoseconds(value: number): void;

参数

value

纳秒数。

返回值

无。

.subNanoseconds() 实例 方法 =standard

从时间段中减去指定数量的纳秒数。

.subNanoseconds(value: number): void;

参数

value

纳秒数。

返回值

无。

.asNanoseconds() 实例 方法 =standard

获取纳秒数的毫秒表示。

.asNanoseconds(): number;

参数

无。

返回值

纳秒数的毫秒表示。