@maiyunnet/kebab 2.0.7 → 2.0.9

package/lib/text.d.ts

@@ -1,40 +1,171 @@
 import * as types from '../types';
+/**
+ * --- 将文件大小格式化为带单位的字符串 ---
+ * @param size 文件大小
+ * @param spliter 分隔符
+ */
 export declare function sizeFormat(size: number, spliter?: string): string;
+/**
+ * --- 格式化一段 URL ---
+ * @param url
+ */
 export declare function parseUrl(url: string): types.IUrlParse;
+/**
+ * --- 将相对路径根据基准路径进行转换 ---
+ * @param from 基准路径
+ * @param to 相对路径
+ */
 export declare function urlResolve(from: string, to: string): string;
+/**
+ * --- 将路径中的 ../ ./ 都按规范妥善处理 ---
+ * @param url 要处理的地址
+ */
 export declare function urlAtom(url: string): string;
 export declare const REGEXP_EMAIL: RegExp;
+/**
+ * --- 是否是邮件地址 ---
+ * @param email
+ */
 export declare function isEMail(email: string): boolean;
 export declare const REGEXP_IPV4: RegExp;
+/**
+ * --- 是否是 IPv4 ---
+ * @param ip
+ */
 export declare function isIPv4(ip: string): boolean;
 export declare const REGEXP_IPV6: RegExp;
+/**
+ * --- 是否是 IPv6 ---
+ * @param ip
+ */
 export declare function isIPv6(ip: string): boolean;
 export declare const REGEXP_DOMAIN: RegExp;
+/**
+ * --- 判断是否是域名 ---
+ * @param string $domain
+ * @return bool
+ */
 export declare function isDomain(domain: string): boolean;
 export declare const REGEXP_ASCII: RegExp;
+/**
+ * --- 判断是否在 ascii 字符集内，仅可输入部分 ---
+ * @param text 要判断的文本
+ */
 export declare function isAscii(text: string): boolean;
+/**
+ * --- 换行替换为别的 ---
+ * @param str 要替换的字符串
+ * @param to 换行替换符
+ */
 export declare function nlReplace(str: string, to?: string): string;
+/** 解析后的 domain */
 export interface IDomain {
     tld: string | null;
     sld: string | null;
     domain: string | null;
     sub: string | null;
 }
+/**
+ * --- 解析域名并获取 tld/sld/domain/sub ---
+ * @param domain 域名
+ */
 export declare function parseDomain(domain: string): Promise<IDomain>;
+/**
+ * --- 传入正则进行匹配 str 是否有一项满足 ---
+ * @param str 要检测的字符串
+ * @param regs 正则列表
+ */
 export declare function match(str: string, regs: RegExp[]): boolean;
+/**
+ * --- 判断手机号是否是 11 位，不做真实性校验 ---
+ * @param p 手机号
+ */
 export declare function isPhoneCN(p: string): boolean;
+/**
+ * --- 是否是中国大陆身份证号码 ---
+ * @param idcard 身份证号
+ */
 export declare function isIdCardCN(idcard: string): boolean;
+/**
+ * --- 将对象转换为 query string ---
+ * @param query 要转换的对象
+ * @param encode 是否转义
+ */
 export declare function queryStringify(query: Record<string, any>, encode?: boolean): string;
+/**
+ * --- 将 query string 转换为对象 ---
+ * @param query 要转换的字符串
+ */
 export declare function queryParse(query: string): Record<string, string | string[]>;
+/**
+ * --- HTML 特殊字符转换为实体字符 ---
+ * @param html 待转换的 HTML
+ */
 export declare function htmlescape(html: string): string;
+/**
+ * --- 判断是否是绝对路径，是返回 true，相对路径返回 false ---
+ * @param path 要判断的路径字符串
+ */
 export declare function isRealPath(path: string): boolean;
+/**
+ * --- 获取文件名 ---
+ * @param path 文件路径
+ */
 export declare function getFilename(path: string): string;
+/**
+ * --- 将普通的返回 JSON 对象序列化为字符串，Mutton 不能使用 ---
+ * @param o 返回 JSON 对象
+ */
 export declare function stringifyResult(rtn: types.Json): string;
+/**
+ * --- 将字符串解析为对象，返回 false 代表解析失败，支持 BigInt，Kebab true, Mutton false ---
+ * @param str 要解析的 json 字符串
+ */
 export declare function parseJson(str: string): any;
+/**
+ * --- 将对象转换为 json 字符串，返回 false 代表解析失败，支持 BigInt，Kebab true, Mutton false ---
+ * @param obj 要转换的 json 对象
+ * @param space 美化方式
+ */
 export declare function stringifyJson(obj: types.Json, space?: string | number): string;
+/**
+ * --- 输出文本格式的 buffer ---
+ * @param buf 原始 buffer
+ */
+export declare function stringifyBuffer(buf: Buffer): string;
 type TFalsy = false | '' | 0 | null | undefined | typeof NaN;
+/**
+ * --- 判断一个值是否是虚假的（为 null/undefined/空字符串/false/0） ---
+ * @param val 要判断的值
+ */
 export declare function isFalsy(val: any): val is TFalsy;
+/**
+ * --- 类似 || 运算符的效果 ---
+ * @param v1 比对值
+ * @param v2 比对值
+ */
 export declare function logicalOr<T, T2>(v1: T, v2: T2): [T] extends [TFalsy] ? T2 : T;
+/**
+ * --- 为解决精度问题，将字符串数字转换为整数显示 ---
+ * --- 以下几个示例都是当 digits 为 2 时 ---
+ * --- str 传入 '1.234'，返回 123 ---
+ * --- str 传入 '1.235'，返回 124 ---
+ * --- str 传入 '1.1'，返回 110 ---
+ * --- str 传入 '6'，返回 600 ---
+ * @param str 要转换的数字字符串
+ * @param digits 小数点右移位数
+ */
 export declare function str2int(str: string, digits?: number): number;
+/**
+ * --- 为解决精度问题，将整数转换为小数字符串 ---
+ * --- 以下几个示例都是当 digits 为 3、decimal 为 2 时 ---
+ * --- int 传入 2341，返回 '2.34' ---
+ * --- int 传入 2345，返回 '2.35' ---
+ * --- int 传入 23，返回 '0.02' ---
+ * --- int 传入 2，返回 '0.00' ---
+ * @param int 要转换的整数
+ * @param digits 小数点左移位数
+ * @param decimal 最终保留的小数位数
+ */
 export declare function int2str(int: number, digits?: number, decimal?: number): string;
 export {};

package/lib/text.js

@@ -56,12 +56,23 @@ exports.getFilename = getFilename;
 exports.stringifyResult = stringifyResult;
 exports.parseJson = parseJson;
 exports.stringifyJson = stringifyJson;
+exports.stringifyBuffer = stringifyBuffer;
 exports.isFalsy = isFalsy;
 exports.logicalOr = logicalOr;
 exports.str2int = str2int;
 exports.int2str = int2str;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-5-15 16:49:39
+ * Last: 2020-04-06 20:51:06, 2022-9-29 15:18:16, 2022-12-29 00:01:30, 2024-3-6 17:53:14, 2024-5-31 17:29:52, 2025-6-13 15:47:02
+ */
 const kebab = __importStar(require("../index"));
 const fs = __importStar(require("./fs"));
+/**
+ * --- 将文件大小格式化为带单位的字符串 ---
+ * @param size 文件大小
+ * @param spliter 分隔符
+ */
 function sizeFormat(size, spliter = ' ') {
     const units = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
     let i = 0;
@@ -70,7 +81,12 @@ function sizeFormat(size, spliter = ' ') {
     }
     return (Math.round(size * 100) / 100).toString() + spliter + units[i];
 }
+/**
+ * --- 格式化一段 URL ---
+ * @param url
+ */
 function parseUrl(url) {
+    // --- test: https://ab-3dc:aak9()$@github.com:80/nodejs/node/blob/master/lib/url.js?mail=abc@def.com#223 ---
     const rtn = {
         'protocol': null,
         'auth': null,
@@ -114,6 +130,7 @@ function parseUrl(url) {
             const authStr = url.slice(0, auth);
             const authSplit = authStr.indexOf(':');
             if (authSplit > -1) {
+                // --- 有密码 ---
                 rtn['user'] = authStr.slice(0, authSplit);
                 rtn['pass'] = authStr.slice(authSplit + 1);
                 rtn['auth'] = rtn['user'] + ':' + rtn['pass'];
@@ -138,28 +155,43 @@ function parseUrl(url) {
         }
     }
     else {
+        // --- 没有 protocol ---
         rtn['pathname'] = url;
     }
+    // --- 组合 ---
     rtn['path'] = rtn['pathname'] + (rtn['query'] ? '?' + rtn['query'] : '');
     return rtn;
 }
+/**
+ * --- 将相对路径根据基准路径进行转换 ---
+ * @param from 基准路径
+ * @param to 相对路径
+ */
 function urlResolve(from, to) {
     from = from.replace('\\', '/');
     to = to.replace('\\', '/');
+    // --- to 为空，直接返回 form ---
     if (to === '') {
         return urlAtom(from);
     }
+    // --- 获取 from 的 scheme, host, path ---
     const f = parseUrl(from);
+    // --- 以 // 开头的，加上 from 的 protocol 返回 ---
     if (to.startsWith('//')) {
         return urlAtom(f.protocol ? f.protocol + to : to);
     }
     if (f.protocol) {
+        // --- 获取小写的 protocol ---
         from = f.protocol + from.slice(f.protocol.length);
     }
+    // --- 获取 to 的 scheme, host, path ---
     const t = parseUrl(to);
+    // --- 已经是绝对路径，直接返回 ---
     if (t.protocol) {
+        // --- 获取小写的 protocol ---
         return urlAtom(t.protocol + to.slice(t.protocol.length));
     }
+    // --- # 或 ? 替换后返回 ---
     if (to.startsWith('#') || to.startsWith('?')) {
         const sp = from.indexOf(to[0]);
         if (sp !== -1) {
@@ -169,25 +201,39 @@ function urlResolve(from, to) {
             return urlAtom(from + to);
         }
     }
+    // --- 处理后面的尾随路径 ---
     let abs = (f.auth ? f.auth + '@' : '') + (f.host ?? '');
     if (to.startsWith('/')) {
+        // -- abs 类似是 /xx/xx ---
         abs += to;
     }
     else {
+        // --- to 是 xx/xx 这样的 ---
+        // --- 移除基准 path 不是路径的部分，如 /ab/c 变成了 /ab，/ab 变成了 空 ---
         const path = f.pathname.replace(/\/[^/]*$/g, '');
+        // --- abs 是 /xx/xx 了，因为如果 path 是空，则跟上了 /，如果 path 不为空，也是 / 开头 ---
         abs += path + '/' + to;
     }
+    // --- 返回最终结果 ---
     if (f.protocol && (f.protocol !== 'file:') && !f.host) {
+        // --- 类似 c:/ ---
         return urlAtom(f.protocol + abs);
     }
     else {
+        // --- 类似 http:// ---
         return urlAtom((f.protocol ? f.protocol + '//' : '') + abs);
     }
 }
+/**
+ * --- 将路径中的 ../ ./ 都按规范妥善处理 ---
+ * @param url 要处理的地址
+ */
 function urlAtom(url) {
+    // --- 删掉 ./ ---
     while (url.includes('/./')) {
         url = url.replace(/\/\.\//g, '/');
     }
+    // --- 删掉 ../ ---
     while (/\/(?!\.\.)[^/]+\/\.\.\//.test(url)) {
         url = url.replace(/\/(?!\.\.)[^/]+\/\.\.\//g, '/');
     }
@@ -195,25 +241,51 @@ function urlAtom(url) {
     return url;
 }
 exports.REGEXP_EMAIL = /^[-_\w.]+@[-_\w.]+\.([a-zA-Z]+)$/i;
+/**
+ * --- 是否是邮件地址 ---
+ * @param email
+ */
 function isEMail(email) {
     return exports.REGEXP_EMAIL.test(email);
 }
 exports.REGEXP_IPV4 = /^[0-9]{1,3}(\.[0-9]{1,3}){3}$/i;
+/**
+ * --- 是否是 IPv4 ---
+ * @param ip
+ */
 function isIPv4(ip) {
     return exports.REGEXP_IPV4.test(ip);
 }
 exports.REGEXP_IPV6 = /^(\w*?:){2,7}[\w.]*$/i;
+/**
+ * --- 是否是 IPv6 ---
+ * @param ip
+ */
 function isIPv6(ip) {
     return exports.REGEXP_IPV6.test(ip + ':');
 }
 exports.REGEXP_DOMAIN = /^.+?\.((?![0-9]).)+$/i;
+/**
+ * --- 判断是否是域名 ---
+ * @param string $domain
+ * @return bool
+ */
 function isDomain(domain) {
     return exports.REGEXP_DOMAIN.test(domain);
 }
 exports.REGEXP_ASCII = /^[\x20-\x7E]*$/;
+/**
+ * --- 判断是否在 ascii 字符集内，仅可输入部分 ---
+ * @param text 要判断的文本
+ */
 function isAscii(text) {
     return exports.REGEXP_ASCII.test(text);
 }
+/**
+ * --- 换行替换为别的 ---
+ * @param str 要替换的字符串
+ * @param to 换行替换符
+ */
 function nlReplace(str, to = '\n') {
     str = str.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
     if (to !== '\n') {
@@ -221,7 +293,12 @@ function nlReplace(str, to = '\n') {
     }
     return str;
 }
+/** Tld 列表 */
 let tldList;
+/**
+ * --- 解析域名并获取 tld/sld/domain/sub ---
+ * @param domain 域名
+ */
 async function parseDomain(domain) {
     const rtn = {
         tld: null,
@@ -243,13 +320,16 @@ async function parseDomain(domain) {
         }
         const last2 = (arr[arr.length - 2] + '.' + arr[arr.length - 1]).toLowerCase();
         if (tldList.includes(last2)) {
+            // --- last2 就是 tld ---
             rtn.tld = last2;
             if (arr.length === 2) {
+                // --- 没有 sld ---
                 rtn.domain = last2;
                 return rtn;
             }
             rtn.sld = arr[arr.length - 3].toLowerCase();
             rtn.domain = rtn.sld + '.' + rtn.tld;
+            // --- 判断是否有 sub ---
             if (arr.length === 3) {
                 return rtn;
             }
@@ -260,6 +340,7 @@ async function parseDomain(domain) {
             rtn.tld = arr[arr.length - 1].toLowerCase();
             rtn.sld = arr[arr.length - 2].toLowerCase();
             rtn.domain = rtn.sld + '.' + rtn.tld;
+            // --- 判断是否有 sub ---
             if (arr.length === 2) {
                 return rtn;
             }
@@ -269,6 +350,11 @@ async function parseDomain(domain) {
     }
     return rtn;
 }
+/**
+ * --- 传入正则进行匹配 str 是否有一项满足 ---
+ * @param str 要检测的字符串
+ * @param regs 正则列表
+ */
 function match(str, regs) {
     for (const reg of regs) {
         if (reg.test(str)) {
@@ -277,22 +363,38 @@ function match(str, regs) {
     }
     return false;
 }
+// --- 以下是适用于中国大陆的方法 ---
+/**
+ * --- 判断手机号是否是 11 位，不做真实性校验 ---
+ * @param p 手机号
+ */
 function isPhoneCN(p) {
     return /^1[0-9]{10}$/.test(p);
 }
+/**
+ * --- 是否是中国大陆身份证号码 ---
+ * @param idcard 身份证号
+ */
 function isIdCardCN(idcard) {
     if (idcard.length !== 18) {
         return false;
     }
+    // --- 取出本码 ---
     const idcardBase = idcard.slice(0, 17);
+    // --- 取出校验码 ---
     const verifyCode = idcard.slice(17, 18);
+    // --- 加权因子 ---
     const factor = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+    // --- 校验码对应值 ---
     const verifyCodeList = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
+    // --- 根据前17位计算校验码 ---
     let total = BigInt(0);
     for (let i = 0; i < 17; i++) {
         total += BigInt(idcardBase.slice(i, i + 1)) * BigInt(factor[i]);
     }
+    // --- 取模 ---
     const mod = total % BigInt(11);
+    // --- 比较校验码 ---
     if (verifyCode === verifyCodeList[Number(mod)]) {
         return true;
     }
@@ -300,6 +402,12 @@ function isIdCardCN(idcard) {
         return false;
     }
 }
+// --- 以下 Mutton: false, Kebab: true ---
+/**
+ * --- 将对象转换为 query string ---
+ * @param query 要转换的对象
+ * @param encode 是否转义
+ */
 function queryStringify(query, encode = true) {
     if (encode) {
         return Object.entries(query).map(([k, v]) => {
@@ -316,6 +424,10 @@ function queryStringify(query, encode = true) {
         return `${k}=${v}`;
     }).join('&');
 }
+/**
+ * --- 将 query string 转换为对象 ---
+ * @param query 要转换的字符串
+ */
 function queryParse(query) {
     const ret = {};
     const arrayKeys = {};
@@ -346,6 +458,10 @@ function queryParse(query) {
     }
     return ret;
 }
+/**
+ * --- HTML 特殊字符转换为实体字符 ---
+ * @param html 待转换的 HTML
+ */
 function htmlescape(html) {
     const type = typeof html;
     if (type !== 'string') {
@@ -353,6 +469,10 @@ function htmlescape(html) {
     }
     return html.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/'/g, '&quot;');
 }
+/**
+ * --- 判断是否是绝对路径，是返回 true，相对路径返回 false ---
+ * @param path 要判断的路径字符串
+ */
 function isRealPath(path) {
     path = path.replace(/\\/g, '/');
     if (path.startsWith('/')) {
@@ -360,6 +480,10 @@ function isRealPath(path) {
     }
     return /[a-z]+:/i.test(path.split('/')[0]) ? true : false;
 }
+/**
+ * --- 获取文件名 ---
+ * @param path 文件路径
+ */
 function getFilename(path) {
     path = path.replace(/\\/g, '/');
     const lio = path.lastIndexOf('/');
@@ -368,8 +492,13 @@ function getFilename(path) {
     }
     return path.slice(lio + 1);
 }
+/**
+ * --- 将普通的返回 JSON 对象序列化为字符串，Mutton 不能使用 ---
+ * @param o 返回 JSON 对象
+ */
 function stringifyResult(rtn) {
     if (Array.isArray(rtn)) {
+        // --- [0, 'xxx'] 模式 ---
         if (rtn.length === 0) {
             return JSON.stringify({
                 'result': 0,
@@ -377,14 +506,17 @@ function stringifyResult(rtn) {
             });
         }
         if (typeof rtn[0] === 'number') {
+            // --- 1. ---
             const json = { 'result': rtn[0] };
             if (rtn[1] !== undefined) {
                 if (typeof rtn[1] === 'object') {
+                    // --- [0, ...{'xx': 'xx'}] ---
                     for (let i = 1; i < rtn.length; ++i) {
                         Object.assign(json, rtn[i]);
                     }
                 }
                 else {
+                    // --- [0, 'xxx'], [0, 'xxx', ...{'xx': 'xx'}] ---
                     json['msg'] = rtn[1];
                     for (let i = 2; i < rtn.length; ++i) {
                         Object.assign(json, rtn[i]);
@@ -393,10 +525,16 @@ function stringifyResult(rtn) {
             }
             return JSON.stringify(json);
         }
+        // --- 直接是个 json 对象 ---
         return JSON.stringify(rtn);
     }
+    // --- 直接是个 json 对象 ---
     return JSON.stringify(rtn);
 }
+/**
+ * --- 将字符串解析为对象，返回 false 代表解析失败，支持 BigInt，Kebab true, Mutton false ---
+ * @param str 要解析的 json 字符串
+ */
 function parseJson(str) {
     try {
         str = str.replace(/("[\w-]+?" *: *)([-+0-9]+)([ \r\n]*[,}]|$)/g, (v, v1, v2, v3) => {
@@ -421,6 +559,11 @@ function parseJson(str) {
         return false;
     }
 }
+/**
+ * --- 将对象转换为 json 字符串，返回 false 代表解析失败，支持 BigInt，Kebab true, Mutton false ---
+ * @param obj 要转换的 json 对象
+ * @param space 美化方式
+ */
 function stringifyJson(obj, space) {
     return JSON.stringify(obj, (k, v) => {
         if (typeof v === 'bigint') {
@@ -429,27 +572,72 @@ function stringifyJson(obj, space) {
         return v;
     }, space).replace(/"-mybigint-([-+0-9]+?)"/g, '$1');
 }
+/**
+ * --- 输出文本格式的 buffer ---
+ * @param buf 原始 buffer
+ */
+function stringifyBuffer(buf) {
+    const arr = buf.toString('hex').match(/.{1,2}/g);
+    return `<Buffer ${arr ? arr.join(' ') : ''}>`;
+}
+/**
+ * --- 判断一个值是否是虚假的（为 null/undefined/空字符串/false/0） ---
+ * @param val 要判断的值
+ */
 function isFalsy(val) {
     return (val === null) || (val === undefined) || (val === '') || (val === false) || (val === 0);
 }
+/**
+ * --- 类似 || 运算符的效果 ---
+ * @param v1 比对值
+ * @param v2 比对值
+ */
 function logicalOr(v1, v2) {
     return (isFalsy(v1) ? v2 : v1);
 }
+/**
+ * --- 为解决精度问题，将字符串数字转换为整数显示 ---
+ * --- 以下几个示例都是当 digits 为 2 时 ---
+ * --- str 传入 '1.234'，返回 123 ---
+ * --- str 传入 '1.235'，返回 124 ---
+ * --- str 传入 '1.1'，返回 110 ---
+ * --- str 传入 '6'，返回 600 ---
+ * @param str 要转换的数字字符串
+ * @param digits 小数点右移位数
+ */
 function str2int(str, digits = 3) {
     const num = parseFloat(str);
+    /** --- 位数，如 1000 --- */
     const factor = Math.pow(10, digits);
     return Math.round(num * factor);
 }
+/**
+ * --- 为解决精度问题，将整数转换为小数字符串 ---
+ * --- 以下几个示例都是当 digits 为 3、decimal 为 2 时 ---
+ * --- int 传入 2341，返回 '2.34' ---
+ * --- int 传入 2345，返回 '2.35' ---
+ * --- int 传入 23，返回 '0.02' ---
+ * --- int 传入 2，返回 '0.00' ---
+ * @param int 要转换的整数
+ * @param digits 小数点左移位数
+ * @param decimal 最终保留的小数位数
+ */
 function int2str(int, digits = 4, decimal = 2) {
+    /** --- 正负符号 --- */
     const sign = int < 0 ? '-' : '';
     const absInt = Math.abs(int);
     let intStr = absInt.toString();
+    // --- 补前导零至长度 digits + 1 ---
     while (intStr.length < digits + 1) {
         intStr = '0' + intStr;
     }
+    /** --- 整数部分字符串 --- */
     const intPart = intStr.slice(0, intStr.length - digits);
+    /** --- 小数部分字符串 --- */
     const decPart = intStr.slice(intStr.length - digits);
+    /** --- 小数部分数字 --- */
     const decNum = parseInt(decPart);
+    /** --- 要除的数 --- */
     const div = Math.pow(10, digits - decimal);
     const round = Math.round(decNum / div);
     const carry = Math.floor(round / Math.pow(10, decimal));

package/lib/time.d.ts

@@ -1,22 +1,75 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-6 12:04:15
+ * Last: 2020-3-29 23:41:21, 2024-1-18 17:16:50, 2024-8-5 10:55:21
+ */
 import * as sCtr from '../sys/ctr';
 export interface IOptions {
+    /** --- 时区 --- */
     'zone'?: number;
+    /** --- 字符串、时间戳（秒或毫秒） --- */
     'data'?: string | number;
 }
+/** --- 一小时的秒数 --- */
 export declare const HOUR = 3600;
+/** --- 一天的秒数 --- */
 export declare const DAY = 86400;
+/** --- 一年（365 天） */
 export declare const YEAR = 31536000;
 export declare class Time {
+    /** --- 当前 date --- */
     private readonly _date;
+    /** --- 当前时区 --- */
     private _zone;
+    /**
+     * --- 构造函数 ---
+     * @param opt
+     */
     constructor(ctr: sCtr.Ctr, opt: IOptions);
+    /**
+     * --- 设置时区 ---
+     * @param zone 北京时间如 8
+     */
     setZone(zone: number): void;
+    /**
+     * --- 获取时区 ---
+     */
     getZone(): number;
+    /**
+     * --- 获取 UTC 字符串 ---
+     */
     toUTCString(): string;
+    /**
+     * --- 获取格式化的字符串 ---
+     * @param f 格式化字符串
+     * @param zone 时区小时，如 8
+     */
     format(f: string, zone?: number): string;
+    /**
+     * --- 获取秒级时间戳 ---
+     */
     stamp(): number;
 }
+/**
+ * --- 创建获取一个时间对象 ---
+ * @param opt
+ */
 export declare function get(ctr: sCtr.Ctr, opt?: IOptions): Time;
+/**
+ * --- 获取秒级时间戳 ---
+ * @param date Date 对象可选
+ * @param zone 时区小时或 ctr 对象，如 8，设置 null 则以系统时区为准
+ */
 export declare function stamp(date?: Date | string, zone?: number | sCtr.Ctr | null): number;
+/**
+ * --- 是否是毫秒 ---
+ * @param time 要判断的时间戳
+ */
 export declare function isMs(time: number): boolean;
+/**
+ * --- 将时间对象转换为时间字符串 ---
+ * @param zone 时区小时或 ctr 对象，如 8，设置 null 则以系统时区为准
+ * @param f 转换格式
+ * @param date 时间对象或秒/毫秒级数字，如果是秒请乘以 1000
+ */
 export declare function format(zone: number | sCtr.Ctr | null, f: string, date?: Date | number): string;