مؤتمر آية اليوم

توضح هذه الصفحة كيفية اختيار آية اليوم من مجموعة البيانات verse-of-the-day ، بحيث يمكنك تنفيذها بأي لغة والحصول على نفس الآية كما في كل تطبيق آخر.

تتكون واجهة برمجة التطبيقات من ملفات ثابتة، لذا فهي لا تختار الآية تلقائيًا. الاصطلاح هو معيار افتراضي مشترك: التطبيقات التي تتبعه تعرض الآية نفسها في اليوم نفسه. للتطبيقات حرية اختيار آية مختلفة، ويوفر لها هذا المعيار طريقة سهلة للقيام بذلك مع الحفاظ على الضمانات نفسها.

الضمانات

• حتمية. نفس التاريخ (والبذرة) يعطي دائمًا نفس الآية، على كل جهاز وفي كل تطبيق.
• لا تتكرر الآيات خلال السنة. لكل سنة ترتيبها الخاص للآيات، وتمر أيام السنة عبر هذا الترتيب. تحتوي مجموعة البيانات دائمًا على 366 آية على الأقل لكل يوم مستخدم، لذا لا تظهر الآية مرتين في نفس السنة التقويمية.
• الأعياد. في الأعياد المسيحية (مثل عيد الميلاد أو أحد القيامة)، تكون آية اليوم إحدى آيات العيد. وتُستخدم آيات العيد بالتناوب سنويًا، لذا تختلف الآية كل عام حتى تُستخدم جميع آياته. أما الأعياد التي تستمر لعدة أيام (مثل الأيام الثلاثة التي تلي أحد القيامة)، فتختلف الآية في كل يوم. ولا تُستخدم آيات الأعياد في الأيام الأخرى.
• ترتيب جديد كل عام. لا يتكرر الترتيب بعد استخدام كل الآية. ولأن كل عام يُعاد ترتيبه بشكل منفصل، فقد تظهر الآية نفسها أحيانًا في 31 ديسمبر ومرة ​​أخرى في 1 يناير (حوالي مرة واحدة كل 650 عامًا جديدًا).
• تاريخ مستقر. لا تضيف مجموعة البيانات أو تحذف آيات من سنة لم تبدأ بعد (انظر addedIn و removedIn )، لذا فإن آية اليوم لتاريخ حدث بالفعل لا تتغير أبدًا.
• بغض النظر عن ترتيب القائمة. يأتي مكان كل آية في ترتيب السنة من مرجعها الخاص، لذا فإن ترتيب القائمة لا يهم.

المدخلات

الخوارزمية

الخطوة الأولى: تحديد السنة واليوم من السنة

خذ السنة والشهر واليوم من التاريخ، ويوم التاريخ من السنة، بدءًا من 0: 1 يناير هو اليوم 0، و31 ديسمبر هو اليوم 364 (أو اليوم 365 في السنة الكبيسة).

تستخدم التواريخ التقويم الغريغوري الاستباقي: السنة هي سنة كبيسة إذا كانت قابلة للقسمة على 4، باستثناء السنوات القابلة للقسمة على 100 والتي لا تقبل القسمة على 400 (2000 سنة كبيسة، 1900 ليست كذلك).

الخطوة الثانية: احتفظ بالآيات المستخدمة

احتفظ بالآيات المستخدمة في السنة:

• القيمة addedIn مفقودة (أو فارغة)، أو addedIn <= year ، و
• removedIn مفقود (أو فارغ)، أو year < removedIn .

الخطوة الثالثة: اختيار الآيات التي تريد الانتقاء منها

اختر الآيات التي ستختار منها، وبادئة رئيسية للخطوة 4، وموضعًا للخطوة 7:

1. تم تحديد فئة. احتفظ بالآيات المستخدمة التي تحتوي على الرقم categories البادئة هي {seed}|{year} والموقع هو يوم السنة.
2. لم تُحدد فئة، والتاريخ عطلة. يُعتبر التاريخ عطلة إذا كانت العطلة المذكورة في holidays تتضمن الرقمين month و day من نفس التاريخ، أو إذا كان التاريخ مُدرجًا في dates (يُكتب YYYY-MM-DD ، مع سنة مكونة من أربعة أرقام). في حال تطابق أكثر من عطلة، يُستخدم أول عطلة في القائمة (لا تحتوي مجموعة البيانات على عطلتين في نفس التاريخ). تُحفظ الآيات المستخدمة التي يحتوي categories على id من العطلة. إذا وُجدت أي عطلات، يكون البادئة {seed}|{id} (على سبيل المثال |christmas ) والموقع year × k + i ، حيث k هو عدد أيام الاحتفال بالعطلة في السنة (1 للعطلة التي تحتوي على الرقمين month و day ؛ وإلا عدد أيامها dates في سنة التاريخ)، و i هو عدد تلك الأيام التي تسبق التاريخ. بالنسبة للعطلة التي تُحتفل بها يومًا واحدًا في السنة، يكون الموقع هو السنة فقط. إذا لم تكن هناك أي عطلات، يُتابع مع الرقم 3.
3. بخلاف ذلك، احتفظ بالآيات المستخدمة التي لا يحتوي categories على الرقم id لأي ​​عطلة في holidays البادئة هي {seed}|{year} والموقع هو يوم السنة.

seed هو البذرة (السلسلة الفارغة افتراضيًا)، و year هو السنة من الخطوة 1 بالنظام العشري بدون أصفار بادئة (على سبيل المثال 2026 ، 1 ).

إذا لم يبقَ أي آيات، فلا توجد آية لليوم.

العطلات التي تتغير تواريخها سنويًا تُدرج فقط التواريخ المحسوبة مسبقًا (حاليًا من 2026 إلى 2125)، لذا فهي في السنوات الأخرى أيام عادية. لا تحسب التواريخ بنفسك.

الخطوة الرابعة: بناء مفتاح كل آية

لكل بيت شعري متبقٍ، قم ببناء هذه السلسلة:

{prefix}|{book} {chapter}:{verse}

• prefix هو البادئة من الخطوة 3.
• book هو الرقم book للآية تمامًا كما يظهر في مجموعة البيانات (معرف كتاب USFM بأحرف كبيرة مثل JHN أو 1JN ).
• chapter و verse هما في النظام العشري بدون أصفار بادئة.
• endVerse ليس جزءًا من المفتاح. يتم تحديد المقطع من خلال الآية الأولى منه.

على سبيل المثال، المفتاح الخاص بـ John 3:16 في يوم عادي في عام 2026 مع البذرة الافتراضية هو |2026|JHN 3:16 ، والمفتاح الخاص بـ Luke 2:7 في عيد الميلاد هو |christmas|LUK 2:7 .

الخطوة 5: تجزئة كل مفتاح

قم بتجزئة بايتات UTF-8 للمفتاح باستخدام تجزئة FNV-1a ذات 32 بت، ثم امزج النتيجة مع مُنهي MurmurHash3 fmix32 جميع العمليات الحسابية تتم على أعداد صحيحة غير مُوقّعة ذات 32 بت، لذا فإن عمليات الضرب تلتف (تُجرى بتردد 2³²) وعمليات الإزاحة إلى اليمين منطقية (تُضاف أصفار).

hash = 0x811C9DC5
for each byte b in UTF-8(key):
    hash = hash XOR b
    hash = (hash * 0x01000193) mod 2^32

hash = hash XOR (hash >> 16)
hash = (hash * 0x85EBCA6B) mod 2^32
hash = hash XOR (hash >> 13)
hash = (hash * 0xC2B2AE35) mod 2^32
hash = hash XOR (hash >> 16)

والنتيجة هي مفتاح فرز الآية، وهو رقم من 0 إلى 4,294,967,295.

الخطوة السادسة: فرز الآيات

قم بترتيب الآيات حسب مفتاح الترتيب الخاص بها، بدءًا من الأصغر، مع مقارنة المفاتيح كأرقام غير موقعة.

إذا كان لبيتين نفس مفتاح الترتيب (وهو أمر نادر الحدوث)، فضع البيت الذي يأتي مفتاحه من الخطوة 4 أولاً في الترتيب الترتيبي (رمز الأحرف). تبدأ جميع مفاتيح الترتيب بنفس البادئة، لذا فهي تختلف فقط في مرجع ASCII الذي يليها.

الخطوة 7: اختر الآية

آية اليوم هي الآية الموجودة في الموضع p mod n في القائمة المرتبة (بدءًا من 0)، حيث يمثل p الموضع من الخطوة 3 (يوم السنة، أو year × k + i في أيام العطلات)، ويمثل n عدد الآيات في القائمة المرتبة. لا تكون نتيجة mod سالبة أبدًا (في حالة السنة السالبة، أضف n حتى تصبح سالبة).

في الأيام العادية، تحتوي مجموعة البيانات الكاملة على 366 آية على الأقل، لذا فإن day mod n يُعادل day أما الرقم mod فيُصبح مهمًا عند الاختيار من فئة أو قائمة خاصة بك تحتوي على عدد من الآيات أقل من عدد أيام السنة، وفي هذه الحالة تتكرر الآيات خلال السنة. في أيام الأعياد، يتم استعراض آيات العيد على مدار سنة (وفي حالة الأعياد التي تستمر لعدة أيام، يتم استعراضها يومًا بيوم).

الشفرة الزائفة

function verseOfTheDay(verses, holidays, date, seed = "", category = null):
    year = date.year
    day = dayOfYear(date)                 // 0 for January 1st
    inUse = [v for v in verses
             if (v.addedIn == null or v.addedIn <= year)
             and (v.removedIn == null or year < v.removedIn)]

    if category != null:
        return pick([v for v in inUse if category in v.categories], seed + "|" + year, day)

    holiday = first h in holidays where (h.month == date.month and h.day == date.day)
                                     or (h.dates contains format(date, "YYYY-MM-DD"))
    if holiday != null:
        holidayVerses = [v for v in inUse if holiday.id in v.categories]
        if holidayVerses is not empty:
            if holiday.dates == null:
                position = year
            else:
                datesInYear = [d for d in holiday.dates if d starts with year + "-"]
                position = year * length(datesInYear) + count of d in datesInYear where d < date
            return pick(holidayVerses, seed + "|" + holiday.id, position)

    holidayIds = [h.id for h in holidays]
    return pick([v for v in inUse if no category of v is in holidayIds], seed + "|" + year, day)

function pick(candidates, prefix, position):
    if candidates is empty: return null
    keyed = [(hash(key), key, v) for v in candidates
             where key = prefix + "|" + v.book + " " + v.chapter + ":" + v.verse]
    sort keyed by (hash, key)             // hash as an unsigned number, key in ordinal order
    return keyed[position mod length(keyed)].verse    // a mod that is never negative

يستخدم كل تاريخ عادي في السنة نفس القائمة المرتبة، لذلك إذا اخترت آيات للعديد من التواريخ، فقم بالفرز مرة واحدة في السنة وأعد استخدامها.

بذور

يُغيّر هذا الخيار مفتاح كل آية، مما يُعطي ترتيبًا مختلفًا تمامًا مع ضمانات ثابتة (عدم تكرار الآيات خلال السنة، وترتيب جديد كل عام، وسجل ثابت). استخدم خيارًا خاصًا بك، مثل اسم تطبيقك، إذا كنت ترغب في أن يعرض تطبيقك آية خاصة به بدلًا من الآية المشتركة. اتركه فارغًا لعرض نفس الآية التي يعرضها الجميع.

الأخطاء الشائعة

• الأعداد الصحيحة الموقعة. في اللغات التي لا تدعم الأعداد الصحيحة غير الموقعة ذات 32 بت (مثل Java وKotlin وJavaScript)، تُجرى العمليات الحسابية على الأعداد الصحيحة الموقعة ذات 32 بت، ثم يُستخدم إزاحة منطقية لليمين ( >>> )، ثم تُحوّل النتيجة إلى قيمة غير موقعة (مثل hash.toLong() and 0xFFFFFFFF أو hash >>> 0 في JavaScript) قبل المقارنة. في JavaScript، يُستخدم Math.imul لعمليات الضرب؛ لأن * يُفقد الدقة.
• يتم تجزئة الأحرف بدلاً من البايتات. يتم تجزئة بايتات UTF-8 للمفتاح، وليس وحدات ترميز UTF-16 أو نقاط ترميز Unicode. هذا الأمر مهم فقط للبذور التي تحتوي على أحرف غير ASCII، ولكنها مسموحة.
• استخدام التوقيت العالمي المنسق (UTC) لعرض "اليوم". تتغير آية اليوم عند منتصف الليل بالتوقيت المحلي للمستخدم. أما استخدام التاريخ بتوقيت UTC فيعرض آية اليوم السابق أو التالي لجزء من اليوم في معظم المناطق الزمنية.
• بحساب أيام السنة من 1، يكون الأول من يناير هو اليوم 0.
• حساب مواعيد العطلات. استخدم القيمة dates المدرجة في مجموعة البيانات. تختلف الكنائس والتقاويم في حساب عيد الفصح، ولا تعرض مجموعة البيانات إلا التواريخ التي تم حسابها مسبقًا.
• باستثناء أيام العطلات. فبدون holidays ، تُعامل آيات العطلات كآيات عادية، مما يُغير آية كل يوم عادي أيضًا.
• مع استبعاد الآيات المحذوفة، تبقى الآيات التي تحمل تاريخ removedIn في مجموعة البيانات لأن السنوات السابقة تتطلبها. قم بتصفيتها في الخطوة الثانية؛ ولا تحذفها عند تنزيل القائمة.

متجهات الاختبار

استخدم هذه القيم للتحقق من التنفيذ.

التجزئة

أيام السنة

مختارات من قائمة صغيرة

تستخدم هذه القائمة المكونة من ستة عشر بيتاً شعرياً، ثمانية منها مخصصة للأعياد:

[
    { "book": "GEN", "chapter": 1, "verse": 1, "categories": ["praise"] },
    {
        "book": "PSA",
        "chapter": 23,
        "verse": 1,
        "categories": ["comfort", "provision"]
    },
    {
        "book": "PRO",
        "chapter": 3,
        "verse": 5,
        "endVerse": 6,
        "categories": ["faith", "guidance"]
    },
    {
        "book": "ISA",
        "chapter": 40,
        "verse": 31,
        "categories": ["strength", "hope"]
    },
    {
        "book": "JHN",
        "chapter": 3,
        "verse": 16,
        "categories": ["love", "salvation"]
    },
    {
        "book": "ROM",
        "chapter": 8,
        "verse": 28,
        "categories": ["hope"],
        "removedIn": 2027
    },
    { "book": "PHP", "chapter": 4, "verse": 13, "categories": ["strength"] },
    {
        "book": "1JN",
        "chapter": 4,
        "verse": 19,
        "categories": ["love"],
        "addedIn": 2027
    },
    { "book": "LUK", "chapter": 2, "verse": 7, "categories": ["christmas"] },
    {
        "book": "LUK",
        "chapter": 2,
        "verse": 10,
        "endVerse": 11,
        "categories": ["christmas"]
    },
    {
        "book": "MAT",
        "chapter": 1,
        "verse": 23,
        "categories": ["christmas"],
        "addedIn": 2027
    },
    {
        "book": "MAT",
        "chapter": 28,
        "verse": 6,
        "categories": ["resurrection-sunday"]
    },
    {
        "book": "ACT",
        "chapter": 2,
        "verse": 24,
        "categories": ["post-resurrection-sunday"]
    },
    {
        "book": "ROM",
        "chapter": 6,
        "verse": 9,
        "categories": ["post-resurrection-sunday"]
    },
    {
        "book": "1CO",
        "chapter": 15,
        "verse": 20,
        "categories": ["post-resurrection-sunday"]
    },
    {
        "book": "1TH",
        "chapter": 4,
        "verse": 14,
        "categories": ["post-resurrection-sunday"]
    }
]

وهذه الأعياد (ليلة عيد الميلاد لا تحتوي على آيات، لذا فهي يوم عادي):

[
    { "id": "christmas-eve", "month": 12, "day": 24 },
    { "id": "christmas", "month": 12, "day": 25 },
    { "id": "resurrection-sunday", "dates": ["2026-04-05", "2027-03-28"] },
    {
        "id": "post-resurrection-sunday",
        "dates": [
            "2026-04-06",
            "2026-04-07",
            "2026-04-08",
            "2027-03-29",
            "2027-03-30",
            "2027-03-31"
        ]
    }
]

بالنسبة لتاريخ 2026-01-01 مع البذرة الافتراضية، تم استبعاد آيات الأعياد الأربعة و1 يوحنا 4:19 (التي لم تُستخدم بعد)، لذا تبقى سبع آيات. وهي مرتبة حسب مفاتيح الفرز الخاصة بها:

اليوم الأول من يناير هو اليوم صفر، لذا فإن آية اليوم هي المزمور 23:1. أما اليوم الخامس عشر من مارس فهو اليوم 73، و73 باقي قسمة 7 على 3، لذا فإن آية اليوم هي يوحنا 3:16.

في عيد الميلاد، لا يتبقى سوى ترانيم الميلاد المستخدمة. في عام 2027، هناك ثلاث ترانيم، مرتبة حسب مفاتيح الترتيب الخاصة بها:

بما أن باقي قسمة 2027 على 3 يساوي 2، فإن آية اليوم في عيد الميلاد عام 2027 هي لوقا 2:7. أما في عام 2026، فإن متى 1:23 لم يُستخدم بعد، لذا يوجد آية واحدة فقط، وباقي قسمة 2026 على 2 يساوي 0، مما يعطي لوقا 2:10-11.

يستمر العيد الذي يلي أحد القيامة ثلاثة أيام. أما آياته الأربع، مرتبة حسب مفاتيحها، فهي:

في عام ٢٠٢٦، يُحتفل به على ثلاثة أيام، لذا فإن k = ٣، ومواقع ٦ و٧ و٨ أبريل هي ٢٠٢٦ × ٣ + ٠ = ٦٠٧٨ و٦٠٧٩ و٦٠٨٠. ٦٠٧٨ mod ٤ = ٢، و٦٠٧٩ mod ٤ = ٣، و٦٠٨٠ mod ٤ = ٠، تُعطينا الآية ١ كورنثوس ١٥: ٢٠، وأعمال الرسل ٢: ٢٤، و١ تسالونيكي ٤: ١٤. في عام ٢٠٢٧، تستمر المواقع من ٦٠٨١، لذا فإن الآية التالية هي رومية ٦: ٩.

يوم 2028-04-16 هو أحد القيامة، لكنه ليس مدرجًا في قائمة dates هذه، لذا فهو يوم عادي.

اختيارات من مجموعة البيانات

لا تقوم مجموعة البيانات بتغيير آيات السنة التي بدأت، لذا فإن آيات اليوم لعام 2026 تبقى كما هي:

التطبيقات

تتبع هذه التطبيقات الاتفاقية، وتتحقق اختباراتها من القيم الموجودة في هذه الصفحة:

• JavaScript/TypeScript: pickVerseOfTheDay() و FreeUseBibleApi.getVerseOfTheDay() في الحزمة free-use-bible-api ( المصدر ).
• Kotlin: pickVerseOfTheDay() و FreeUseBibleApi.getVerseOfTheDay() في Kotlin SDK ( المصدر ).
• Swift: pickVerseOfTheDay(_:date:seed:category:holidays:) و FreeUseBibleAPI.getVerseOfTheDay(date:seed:category:dataset:endpoint:) في Swift SDK ( المصدر ).
• الأداة getVerseOfTheDay لخادم MCP ( المصدر ).
• getVerseOfTheDay() من @helloao/tools ( المصدر )، والذي يستخدم القائمة المضمنة في الحزمة.