C3 AI Documentation Home

Num

The Num Type is a comprehensive utility for handling various numeric formats and transformations. The Num Type is designed for formatting and parsing numeric values in different forms, such as counts, percentages, bytes, and timings. Its versatility lies in its ability to format numbers into readable strings and parse those strings back into numeric values. This functionality is vital in scenarios like data visualization, user interfaces, and processing large datasets where readability and correct data representation are crucial.

Format numbers

Formats large numbers into a more readable form using suffixes like K (thousands), and M (millions).

Num.formatCount(1000000) returns "1.00M", indicating it converts a seven-digit number into a million format with two decimal places.

Num.formatCount(1147) returns "1.15K", showcasing rounding off functionality for thousands.

Num.formatCount(11) returns "11", implying that small numbers remain unformatted. Custom precision, units, and scaling are also supported, enhancing the method's versatility.

Decimal to fraction conversion

Converts decimal fractions to percentage values.

Num.formatPercent(0.5) yields "50.0%", turning a fractional value into a percentage with one decimal place. The method can handle small fractions and values greater than 1, offering flexibility in percentage formatting.

You can pass in an int32 value as a second argument to formatPercent. The second argument indicates the number of digits to include after the decimal place.

Num.formatPercent(0.543, 2) returns "54.30%".

Format bytes

Formats byte values into larger units like KB, MB for better readability.

Num.formatBytes(1000000) results in "1.00MB", demonstrating the conversion of bytes into megabytes. The function can also round numbers and support custom precision and units, making it useful for displaying file sizes or memory usage.

Format timing values

These functions format timing values in nanoseconds, milliseconds, and seconds, respectively.

They handle various units like microseconds, milliseconds, and seconds, and provide custom formatting options. For instance, Num.formatTimingNs(1000000) converts nanoseconds to milliseconds.

Parse timing values

Parses formatted timing strings back into numeric values.

Num.parseTiming("1.00ms") returns 1000000, showcasing the ability to reverse the format operation.

Predicates

Consists of various methods to check the type and nature of numeric values, such as isDouble or isFinite.

Num.isDouble(null) returns false, indicating that null is not considered a double. These methods are crucial for validating and understanding the nature of data before processing.

Parsing and converting numeric values

These methods provide functionality for parsing and converting numeric values into different formats or data types.

Num.parseCount("1.2M") returns 1200000, illustrating the ability to parse formatted counts back to numeric values. Conversion functions like toDouble, toFloat, toInt are essential for data type transformations.

Display file size in user-friendly format

This function takes a file size in bytes and formats it into a human-readable string using formatBytes. Ideal for a file management system where file sizes must be presented in an understandable format.

JavaScript
function displayFileSize(bytes) {
    // Use the formatBytes method from the Num Type to format the file size
    return Num.formatBytes(bytes);
}

Convert server response time to readable format

The code snippet below converts server response time from nanoseconds to a more readable format using formatTimingNs. This use case is helpful in performance monitoring tools for displaying server response times.

JavaScript
function formatServerResponseTime(responseTimeNs) {
    // Convert nanoseconds to a human-readable format like milliseconds or seconds
    return Num.formatTimingNs(responseTimeNs);
}

Display download progress as percentage

showDownloadProgress calculates and displays the download progress of a file as a percentage using formatPercent. This function is ideal for download managers or any application showing download progress.

JavaScript
function showDownloadProgress(completedBytes, totalBytes) {
    // Calculate the download progress as a fraction
    const progress = completedBytes / totalBytes;
    // Format the fraction as a percentage for display
    return Num.formatPercent(progress);
}

Format large user counts

The JavaScript function below formats large user counts (like followers or views) in a compact, readable format using formatCount. This use case is suitable for social media platforms or analytics dashboards where large numbers should be displayed concisely.

JavaScript
function formatUserCount(count) {
    // Format large numbers (like user count) into a readable format with suffixes
    return Num.formatCount(count);
}

Parse and validate server timing data

Parses a string representing server timing (like "1.2s") back into nanoseconds and validates the result using parseTiming and predicate methods. The use case for this function is useful in server log analysis tools where timing data must be processed and validated.

JavaScript
function parseServerTiming(timingStr) {
    // Parse a timing string back into numeric value (nanoseconds)
    const timingNs = Num.parseTiming(timingStr);
    // Validate the parsed value to ensure it's a finite number
    if (!Num.isFinite(timingNs)) {
        throw new Error("Invalid timing data");
    }
    return timingNs;
}

These functions demonstrate how to apply the Num Type in various domains such as file management, performance monitoring, social media platforms, and more. The versatility of the Num Type methods enables easy and effective handling of numeric data in diverse formats.

Was this page helpful?