From af9108f82491cebebad59f988594332169fac4ec Mon Sep 17 00:00:00 2001 From: Assayyaad Date: Mon, 15 Jul 2024 18:00:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=D8=A5=D8=B6=D8=A7=D9=81=D8=A9=20=D8=A3?= =?UTF-8?q?=D9=85=D8=AB=D9=84=D8=A9=20=D8=A5=D8=B3=D8=AA=D8=AE=D8=AF=D8=A7?= =?UTF-8?q?=D9=85=20=D9=84=D9=84=D8=AF=D9=88=D8=A7=D9=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/line/func/create.js | 22 +++++++++++ src/line/func/point.js | 28 ++++++++++++- src/line/func/time.js | 87 +++++++++++++++++++++++++++++++++++------ 3 files changed, 122 insertions(+), 15 deletions(-) diff --git a/src/line/func/create.js b/src/line/func/create.js index 330c958..6d89998 100644 --- a/src/line/func/create.js +++ b/src/line/func/create.js @@ -7,6 +7,22 @@ * إنشاء كائن مستقيم بناءً على الخيارات المقدمة * @param {LineOptions} options @defaultValue { dis: 1, end: 1, spacing: 1, count: 2, neg: false } * @returns {Line} + * @throws إذا كانت الخيارات غير صالحة + * @example + * const line = Line.create.one({ end: -10 }) + * // line = { neg: true, count: 2, dis: 10, spacing: 10, end: -10, min: -10, max: 0, points: [0, -10] } + * @example + * const line = Line.create.one({ end: -10, count: 3 }) + * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] } + * @example + * const line = Line.create.one({ dis: 10, neg: true }) + * // line = { neg: true, count: 2, dis: 10, spacing: 10, end: -10, min: -10, max: 0, points: [0, -10] } + * @example + * const line = Line.create.one({ dis: 10, count: 3, neg: true }) + * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] } + * @example + * const line = Line.create.one({ spacing: 5, count: 3, neg: true }) + * // line = { neg: true, count: 3, dis: 10, spacing: 5, end: -10, min: -10, max: 0, points: [0, -5, -10] } */ export function one({ dis = 1, end = 1, spacing = 1, count = 2, neg = false }) { // التحقق من القيم المقدمة @@ -71,6 +87,12 @@ export function one({ dis = 1, end = 1, spacing = 1, count = 2, neg = false }) { * حساب مواضع جميع النقاط على الخط، مع ضبط اختياري للفواصل * @param {PointsOptions} options عدد النقاط @defaultValue { spacing: 1, count: 2, sort: zero } * @returns {Point[]} مصفوفة من المواضع لكل نقطة على المستقيم + * @throws إذا كان الخيار المقدم للترتيب غير صالح + * @example + * const points = Line.create.points({ count: 5, spacing: 2, sort: 'zero'}) + * // points = [0, 2, -2, 4, -4] ('zero' sort) + * // points = [-4, -2, 0, 2, 4] ('neg' sort) + * // points = [4, 2, 0, -2, -4] ('pos' sort) */ export function points({ count = 2, spacing = 1, sort = 'zero' }) { // تهيئة مصفوفة لتخزين المواضع المحسوبة لكل نقطة diff --git a/src/line/func/point.js b/src/line/func/point.js index 95ae60e..7ae62af 100644 --- a/src/line/func/point.js +++ b/src/line/func/point.js @@ -6,6 +6,14 @@ * @param {Line} line - المستقيم المراد التحقق عليه * @param {Point} point - النقطة المراد التحقق منها * @returns {boolean} - يعيد صحيح إذا كانت النقطة داخل المستقيم، خلاف ذلك يعيد خطأ + * @example + * const line = Line.create.one({ end: 10 }) + * const pointInLine = inside(line, 5) + * // pointInLine = true + * @example + * const line = Line.create.one({ end: 10 }) + * const pointInLine = inside(line, 15) + * // pointInLine = false */ export function inside({ min, max }, point) { // أعد صحيح إذا كانت النقطة داخل النطاق @@ -17,8 +25,24 @@ export function inside({ min, max }, point) { * @param {Line} line - المستقيم المراد التحرك عليه * @param {Point} current - الموضع الحالي * @param {Point} step - مقدار الخطوة الواحدة للتحرك بها - * @param {boolean} [inverse=false] - عكس إتجاه الحركة على المستقيم. @default false - * @returns {Point} - يعيد الموضع الجديد بعد التحرك + * @param {boolean} [inverse=false] - عكس إتجاه الحركة على المستقيم. @defaultValue false + * @returns {Point} يعيد الموضع الجديد بعد التحرك + * @example تحريك النقطة للأمام على مستقيم موجب + * const line = Line.create.one({ end: 10 }) + * const newCurrent = move(line, 3, 2) + * // newCurrent = 5 + * @example تحريك النقطة للخلف على مستقيم موجب + * const line = Line.create.one({ end: 10 }) + * const newCurrent = move(line, 3, 2, true) + * // newCurrent = 1 + * @example تحريك النقطة للأمام على مستقيم سالب + * const line = Line.create.one({ end: -10 }) + * const newCurrent = move(line, -3, 2) + * // newCurrent = -1 + * @example تحريك النقطة للخلف على مستقيم سالب + * const line = Line.create.one({ end: -10 }) + * const newCurrent = move(line, -3, 2, true) + * // newCurrent = -5 */ export function move({ min, max, neg }, current, step, inverse = false) { // إذا كانت الخطوة تساوي صفرًا، أعد الموضع الحالي دون تغييره diff --git a/src/line/func/time.js b/src/line/func/time.js index 2a91bad..8ba9f4d 100644 --- a/src/line/func/time.js +++ b/src/line/func/time.js @@ -2,18 +2,26 @@ /** @typedef {import("../imports.js").Point} Point */ /** - * تحويل قيمة نقطة إلى نسبة مئوية على مستقيم + * تحويل قيمة نقطة إلى نسبة أحادية على مستقيم * @param {Line} line * @param {Point} point * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.to(line, 5) + * // t = 0.5 + * @example + * const line = Line.create.one({ end: -10 }) + * const t = Line.time.to(line, -5) + * // t = 0.5 */ export function to({ dis, neg, end }, point) { // إذا كانت النقطة عند البداية، إرجاع 0 إذا لم يكن سالباً، وإرجاع 1 إذا كان سالباً if (point === 0) return neg ? 1 : 0 // إذا كانت النقطة عند النهاية، إرجاع 1 إذا لم يكن سالباً، وإرجاع 0 إذا كان سالباً if (point === end) return neg ? 0 : 1 - // حساب النسبة المئوية للنقطة على المستقيم - return (point / dis) * (neg ? -1 : 1) + // حساب النسبة الأحادية للنقطة على المستقيم + return neg ? -(point / dis) : point / dis } /** @@ -21,13 +29,21 @@ export function to({ dis, neg, end }, point) { * @param {Line} line * @param {Point} point * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.to(line, 15) + * // t = 1 + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.to.clamp(line, -5) + * // t = 0 */ to.clamp = function (line, point) { // إذا كانت النقطة أكبر من الحد الأقصى، إرجاع 1 if (point >= line.max) return 1 // إذا كانت النقطة أقل من الحد الأدنى، إرجاع 0 if (point <= line.min) return 0 - // حساب النسبة المئوية المقيدة للنقطة على المستقيم + // حساب النسبة الأحادية المقيدة للنقطة على المستقيم return to(line, point) } @@ -36,11 +52,15 @@ to.clamp = function (line, point) { * @param {Line} line * @param {Point} point * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.to.clamp.min(line, -5) + * // t = 0 */ to.clamp.min = function (line, point) { // إذا كانت النقطة أقل من الحد الأدنى، إرجاع 0 if (point <= line.min) return 0 - // حساب النسبة المئوية المقيدة للنقطة على المستقيم + // حساب النسبة الأحادية المقيدة للنقطة على المستقيم return to(line, point) } @@ -49,19 +69,31 @@ to.clamp.min = function (line, point) { * @param {Line} line * @param {Point} point * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.to.clamp.max(line, 15) + * // t = 1 */ to.clamp.max = function (line, point) { // إذا كانت النقطة أكبر من الحد الأقصى، إرجاع 1 if (point >= line.max) return 1 - // حساب النسبة المئوية المقيدة للنقطة على المستقيم + // حساب النسبة الأحادية المقيدة للنقطة على المستقيم return to(line, point) } /** - * تحويل نسبة مئوية إلى نقطة على المستقيم + * تحويل نسبة أحادية إلى نقطة على المستقيم * @param {Line} line * @param {Point} t بين 0 و 1، شامل ال1 * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from(line, 0.5) + * // t = 5 + * @example + * const line = Line.create.one({ end: -10 }) + * const t = Line.time.from(line, 0.5) + * // t = -5 */ export function from(line, t) { // إذا كانت النسبة 1، إرجاع الحد الأقصى @@ -70,49 +102,66 @@ export function from(line, t) { if (t === 0) return from.min(line) const { dis, neg } = line + // حساب النقطة بناءً على النسبة المئوية if (neg) return -(dis - dis * t) else return dis * t } /** - * تقييد النسبة المئوية بين 0 و 1 + * تقييد النسبة الأحادية بين 0 و 1 * @param {Line} line * @param {Point} t بين 0 و 1، شامل ال1 * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.clamp(line, 1.5) + * // t = 10 + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.clamp(line, -0.5) + * // t = 0 */ from.clamp = function (line, t) { // إذا كانت النسبة أكبر من أو تساوي 1، إرجاع الحد الأقصى if (t >= 1) return from.max(line) // إذا كانت النسبة أقل من أو تساوي 0، إرجاع الحد الأدنى if (t <= 0) return from.min(line) - // حساب النقطة بناءً على النسبة المئوية المقيدة + // حساب النقطة بناءً على النسبة الأحادية المقيدة return from(line, t) } /** - * تقييد النسبة المئوية لتكون أقل من أو تساوي 1 + * تقييد النسبة الأحادية لتكون أقل من أو تساوي 1 * @param {Line} line * @param {Point} t بين 0 و 1، شامل ال1 * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.clamp.max(line, 1.5) + * // t = 10 */ from.clamp.max = function (line, t) { // إذا كانت النسبة أكبر من أو تساوي 1، إرجاع الحد الأقصى if (t >= 1) return from.max(line) - // حساب النقطة بناءً على النسبة المئوية + // حساب النقطة بناءً على النسبة الأحادية return from(line, t) } /** - * تقييد النسبة المئوية لتكون أكبر من أو تساوي 0 + * تقييد النسبة الأحادية لتكون أكبر من أو تساوي 0 * @param {Line} line * @param {Point} t بين 0 و 1، شامل ال1 * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.clamp.min(line, -0.5) + * // t = 0 */ from.clamp.min = function (line, t) { // إذا كانت النسبة أقل من أو تساوي 0، إرجاع الحد الأدنى if (t <= 0) return from.min(line) - // حساب النقطة بناءً على النسبة المئوية + // حساب النقطة بناءً على النسبة الأحادية return from(line, t) } @@ -120,6 +169,10 @@ from.clamp.min = function (line, t) { * إرجاع النقطة عند منتصف المستقيم * @param {Line} line * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.center(line) + * // t = 5 */ from.center = function (line) { return from(line, 0.5) @@ -129,6 +182,10 @@ from.center = function (line) { * إرجاع الحد الأدنى للنقطة على المستقيم * @param {Line} line * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.min(line) + * // t = 0 */ from.min = function ({ dis, neg }) { // note: أسرع من استدعاء `from(line, 0)` @@ -139,6 +196,10 @@ from.min = function ({ dis, neg }) { * إرجاع الحد الأقصى للنقطة على المستقيم * @param {Line} line * @returns {Point} + * @example + * const line = Line.create.one({ end: 10 }) + * const t = Line.time.from.max(line) + * // t = 10 */ from.max = function ({ dis, neg }) { // note: أسرع من استدعاء `from(line, 1)`