Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(fmt): complete documentation #4165

Merged
merged 2 commits into from
Jan 11, 2024
Merged

docs(fmt): complete documentation #4165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22bc90b
docs(fmt): complete documentation
iuioiua Jan 11, 2024
f5235db
tweak
iuioiua Jan 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
84 changes: 50 additions & 34 deletions fmt/bytes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,57 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.

/** Pretty print bytes.
type LocaleOptions = {
minimumFractionDigits?: number;
maximumFractionDigits?: number;
};

/** Options for {@linkcode format}. */
export interface FormatOptions {
/**
* Uses bits representation.
*
* @default {false}
*/
bits?: boolean;
/**
* Uses binary bytes (e.g. kibibyte).
*
* @default {false}
*/
binary?: boolean;
/**
* Include plus sign for positive numbers.
*
* @default {false}
*/
signed?: boolean;
/**
* Uses localized number formatting. If it is set to true, uses default
* locale on the system. If it's set to string, uses that locale. The given
* string should be a
* {@link https://en.wikipedia.org/wiki/IETF_language_tag | BCP 47 language tag}.
* You can also give the list of language tags.
*/
locale?: boolean | string | string[];
/**
* The minimum number of fraction digits to display. If neither
* {@linkcode minimumFractionDigits} or {@linkcode maximumFractionDigits}
* are set, the default behavior is to round to 3 significant digits.
*/
minimumFractionDigits?: number;
/**
* The maximum number of fraction digits to display. If neither
* {@linkcode minimumFractionDigits} or {@linkcode maximumFractionDigits}
* are set, the default behavior is to round to 3 significant digits.
*/
maximumFractionDigits?: number;
}

/**
* Convert bytes to a human-readable string: 1337 → 1.34 kB
*
* Based on [pretty-bytes](https://github.com/sindresorhus/pretty-bytes).
* Based on {@link https://github.com/sindresorhus/pretty-bytes | pretty-bytes}.
* A utility for displaying file sizes for humans.
*
* This module is browser compatible.
Expand All @@ -33,38 +81,6 @@
* format(1337, { locale: "de" });
* //=> '1,34 kB'
* ```
*
* @module
*/

type LocaleOptions = {
minimumFractionDigits?: number;
maximumFractionDigits?: number;
};

/**
* The options for pretty printing the byte numbers.
*/
export interface FormatOptions {
/** Uses bits representation. Default is false. */
bits?: boolean;
/** Uses binary bytes (e.g. kibibyte). Default is false. */
binary?: boolean;
/** Include plus sign for positive numbers. */
signed?: boolean;
/** Uses localized number formatting. If it is set to true, uses default locale on the system. If it's set to string, uses that locale. The given string should be BCP 47 language tag (ref: https://en.wikipedia.org/wiki/IETF_language_tag). You can also give the list of language tags. */
locale?: boolean | string | string[];
/** The minimum number of fraction digits to display. If neither minimumFractionDigits or maximumFractionDigits are set, the default behavior is to round to 3 significant digits. */
minimumFractionDigits?: number;
/** The maximum number of fraction digits to display. If neither minimumFractionDigits or maximumFractionDigits are set, the default behavior is to round to 3 significant digits. */
maximumFractionDigits?: number;
}

/**
* Convert bytes to a human-readable string: 1337 → 1.34 kB
*
* @param num The number to format
* @param options The options
*/
export function format(
num: number,
Expand Down
28 changes: 17 additions & 11 deletions fmt/colors.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
* if `NO_COLOR` is set.
*
* @example
* ```typescript
* ```ts
* import {
* bgBlue,
* bgRgb24,
Expand Down Expand Up @@ -63,9 +63,12 @@ interface Code {
}

/** RGB 8-bits per channel. Each in range `0->255` or `0x00->0xff` */
interface Rgb {
export interface Rgb {
/** Red component value */
r: number;
/** Green component value */
g: number;
/** Blue component value */
b: number;
}

Expand Down Expand Up @@ -113,7 +116,7 @@ function run(str: string, code: Code): string {
}

/**
* Reset the text modified
* Reset the text modified.
* @param str text to reset
*/
export function reset(str: string): string {
Expand Down Expand Up @@ -480,9 +483,10 @@ export function bgRgb8(str: string, color: number): string {
* To produce the color magenta:
*
* ```ts
* import { rgb24 } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
* rgb24("foo", 0xff00ff);
* rgb24("foo", {r: 255, g: 0, b: 255});
* import { rgb24 } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
*
* rgb24("foo", 0xff00ff);
* rgb24("foo", {r: 255, g: 0, b: 255});
* ```
* @param str text color to apply 24bit rgb to
* @param color code
Expand Down Expand Up @@ -520,9 +524,10 @@ export function rgb24(str: string, color: number | Rgb): string {
* To produce the color magenta:
*
* ```ts
* import { bgRgb24 } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
* bgRgb24("foo", 0xff00ff);
* bgRgb24("foo", {r: 255, g: 0, b: 255});
* import { bgRgb24 } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
*
* bgRgb24("foo", 0xff00ff);
* bgRgb24("foo", {r: 255, g: 0, b: 255});
* ```
* @param str text color to apply 24bit rgb to
* @param color code
Expand Down Expand Up @@ -562,15 +567,16 @@ const ANSI_PATTERN = new RegExp(
);

/**
* @deprecated (will be removed in 1.0.0) Use {@linkcode stripAnsiCode} instead.
*
* Remove ANSI escape codes from the string.
* @param string to remove ANSI escape codes from
*
* @deprecated (will be removed in 1.0.0) Use {@linkcode stripAnsiCode} instead.
*/
export const stripColor: typeof stripAnsiCode = stripAnsiCode;

/**
* Remove ANSI escape codes from the string.
*
* @param string to remove ANSI escape codes from
*/
export function stripAnsiCode(string: string): string {
Expand Down
13 changes: 13 additions & 0 deletions fmt/duration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ function durationArray(
];
}

/** Options for {@linkcode format}. */
export interface PrettyDurationOptions {
/**
* "narrow" for "0d 0h 0m 0s 0ms..."
Expand All @@ -91,6 +92,18 @@ export interface PrettyDurationOptions {
ignoreZero: boolean;
}

/**
* Format milliseconds to time duration.
*
* ```ts
* import { format } from "https://deno.land/std@$STD_VERSION/fmt/duration.ts";
*
* format(99674, { style: "digital" }); // "00:00:01:39:674:000:000"
* format(99674); // "0d 0h 1m 39s 674ms 0µs 0ns"
* format(99674, { ignoreZero: true }); // "1m 39s 674ms"
* format(99674, { style: "full", ignoreZero: true }); // "1 minutes, 39 seconds, 674 milliseconds"
* ```
*/
export function format(
ms: number,
options: Partial<PrettyDurationOptions> = {},
Expand Down