From 8ae8196337d4e785b3d3903ebc1790e837f412cb Mon Sep 17 00:00:00 2001 From: Ashley //// Date: Thu, 1 Feb 2024 16:17:42 +0000 Subject: [PATCH] add jsdoc :3 --- src/libpoketube/ptutils/libpt-coreutils.js | 170 ++++++++++++++++++--- 1 file changed, 149 insertions(+), 21 deletions(-) diff --git a/src/libpoketube/ptutils/libpt-coreutils.js b/src/libpoketube/ptutils/libpt-coreutils.js index 013d8224..e4a9e853 100644 --- a/src/libpoketube/ptutils/libpt-coreutils.js +++ b/src/libpoketube/ptutils/libpt-coreutils.js @@ -2,7 +2,7 @@ PokeTube is a Free/Libre youtube front-end ! - Copyright (C) 2021-2022 POKETUBE + Copyright (C) 2021-2024 POKETUBE This file is Licensed under LGPL-3.0-or-later. Poketube itself is GPL, Only this file is LGPL. @@ -12,6 +12,11 @@ */ +/** + * Checks if a string is a valid JSON. + * @param {string} str - The string to be checked. + * @returns {boolean} - Returns true if the string is a valid JSON, otherwise false. + */ function IsJsonString(str) { try { JSON.parse(str); @@ -21,50 +26,87 @@ function IsJsonString(str) { return true; } +/** + * Converts a number into a compact string representation using the en-GB locale. + * @param {number} value - The number to be converted. + * @returns {string} - The compact string representation of the number. + */ function convert(value) { return new Intl.NumberFormat("en-GB", { notation: "compact", }).format(value); } +/** + * Extracts the first line of text before the first occurrence of "
". + * @param {string} text - The input text. + * @returns {string} - The first line of text before "
", or the entire text if no "
" is found. + */ function getFirstLine(text) { var index = text?.indexOf("
"); if (index === -1) index = undefined; return text?.substring(0, index); } +/** + * Capitalizes the first letter of a string. + * @param {string} string - The input string. + * @returns {string} - The string with the first letter capitalized. + */ function capitalizeFirstLetter(string) { return string.charAt(0).toUpperCase() + string.slice(1); } +/** + * Converts time in seconds to a formatted time string (hh:mm:ss or mm:ss). + * If time is 00:00, returns "LIVE". + * @param {number} time - The time in seconds. + * @returns {string} - The formatted time string. + */ function turntomins(time) { - var minutes = Math.floor(time / 60); - - var seconds = time - minutes * 60; + var hours = Math.floor(time / 3600); + var remainingSeconds = time - hours * 3600; + var minutes = Math.floor(remainingSeconds / 60); + var seconds = remainingSeconds - minutes * 60; function str_pad_left(string, pad, length) { return (new Array(length + 1).join(pad) + string).slice(-length); } - var finalTime = - str_pad_left(minutes, "0", 2) + ":" + str_pad_left(seconds, "0", 2); + if (hours > 0) { + var finalTime = + str_pad_left(hours, "0", 2) + + ":" + + str_pad_left(minutes, "0", 2) + + ":" + + str_pad_left(seconds, "0", 2); + } else { + if (minutes === 0 && seconds === 0) { + return "LIVE"; + } else { + var finalTime = + str_pad_left(minutes, "0", 2) + ":" + str_pad_left(seconds, "0", 2); + } + } return finalTime; -}; +} /** - * Returns a random number between min (inclusive) and max (exclusive) + * Returns a random floating point number within the specified range. + * @param {number} min - The minimum value of the range (inclusive). + * @param {number} max - The maximum value of the range (exclusive). + * @returns {number} - A random floating point number within the specified range. */ function getRandomArbitrary(min, max) { return Math.random() * (max - min) + min; } /** - * Returns a random integer between min (inclusive) and max (inclusive). - * The value is no lower than min (or the next integer greater than min - * if min isn't an integer) and no greater than max (or the next integer - * lower than max if max isn't an integer). - * Using Math.round() will give you a non-uniform distribution! + * Returns a random integer within the specified range. + * @param {number} min - The minimum value of the range (inclusive). + * @param {number} max - The maximum value of the range (inclusive). + * @returns {number} - A random integer within the specified range. */ function getRandomInt(min, max) { min = Math.ceil(min); @@ -72,6 +114,12 @@ function getRandomInt(min, max) { return Math.floor(Math.random() * (max - min + 1)) + min; } +/** + * Increases or decreases the brightness of a hexadecimal color code. + * @param {string} hex - The hexadecimal color code. + * @param {number} percent - The percentage by which to adjust the brightness (positive for increase, negative for decrease). + * @returns {string} - The modified hexadecimal color code. + */ function increase_brightness(hex, percent){ // strip the leading # if it's there hex = hex.replace(/^\s*#|\s*$/g, ''); @@ -91,12 +139,92 @@ function increase_brightness(hex, percent){ ((0|(1<<8) + b + (256 - b) * percent / 100).toString(16)).substr(1); } +/** + * Converts an array to an object with numeric keys. + * @param {Array} arr - The input array. + * @returns {Object} - The resulting object with numeric keys. + */ +function toObject(arr) { + var rv = {}; + for (var i = 0; i < arr.length; ++i) if (arr[i] !== undefined) rv[i] = arr[i]; + return rv; +} + +/** + * Determines if a color is light or dark. + * @param {string} color - The color code in hexadecimal or RGB format. + * @returns {string} - Returns "light" if the color is light, otherwise "dark". + */ +function lightOrDark(color) { + // Variables for red, green, blue values + var r, g, b, hsp; + + // Check the format of the color, HEX or RGB? + if (color.match(/^rgb/)) { + // If RGB --> store the red, green, blue values in separate variables + color = color.match( + /^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*(\d+(?:\.\d+)?))?\)$/ + ); + + r = color[1]; + g = color[2]; + b = color[3]; + } else { + // If hex --> Convert it to RGB: http://gist.github.com/983661 + color = +("0x" + color.slice(1).replace(color.length < 5 && /./g, "$&$&")); + + r = color >> 16; + g = (color >> 8) & 255; + b = color & 255; + } + + // HSP (Highly Sensitive Poo) equation from http://alienryderflex.com/hsp.html + hsp = Math.sqrt(0.299 * (r * r) + 0.587 * (g * g) + 0.114 * (b * b)); + + // Using the HSP value, determine whether the color is light or dark + if (hsp > 127.5) { + return "light"; + } else { + return "dark"; + } +} + +/** + * Checks if an element with a specific ID exists in an array of objects. + * @param {Array} array - The array of objects to be searched. + * @param {string} id - The ID to search for. + * @returns {boolean} - Returns true if the ID exists in the array, otherwise false. + */ +function IsInArray(array, id) { + for (var i = 0; i < array.length; i++) { + if (array[i].id === id) return true; + } + return false; +} + +/** + * Parses a JSON string into a JavaScript object. + * @param {string} str - The JSON string to be parsed. + * @returns {(Object|boolean)} - Returns the parsed JavaScript object if successful, otherwise false. + */ +function getJson(str) { + try { + return JSON.parse(str); + } catch { + return false; + } +} + module.exports = { -IsJsonString, -convert, -getFirstLine, -getRandomArbitrary, -getRandomInt, -capitalizeFirstLetter, -turntomins -}; \ No newline at end of file + IsJsonString, + convert, + getFirstLine, + getRandomArbitrary, + getJson, + lightOrDark, + toObject, + IsInArray, + getRandomInt, + capitalizeFirstLetter, + turntomins +};