دن کے کنونشن کی آیت

یہ صفحہ بتاتا ہے کہ verse-of-the-day ڈیٹاسیٹ سے دن کی آیت کو کیسے چننا ہے، تاکہ آپ اسے کسی بھی زبان میں نافذ کر سکیں اور ہر دوسرے نفاذ کی طرح وہی آیت حاصل کر سکیں۔

API جامد فائلوں سے بنا ہے، لہذا یہ آپ کے لیے کوئی آیت منتخب نہیں کرتا ہے۔ کنونشن ایک مشترکہ ڈیفالٹ ہے: اس کی پیروی کرنے والی ایپس اسی دن ایک ہی آیت دکھاتی ہیں۔ ایپس مختلف طریقے سے چننے کے لیے آزاد ہیں، اور بیج انہیں ایک ہی ضمانت کو برقرار رکھتے ہوئے ایسا کرنے کا ایک آسان طریقہ فراہم کرتا ہے۔

ضمانت دیتا ہے۔

• تعیین پسند۔ ایک ہی تاریخ (اور بیج) ہمیشہ ایک ہی آیت دیتا ہے، ہر آلے پر اور ہر عمل میں۔
• ایک سال کے اندر کوئی تکرار نہیں۔ ہر سال آیات کی اپنی بدلی ہوئی ترتیب ہوتی ہے، اور سال کے دن اس میں سے گزرتے ہیں۔ ڈیٹاسیٹ میں ہمیشہ استعمال میں ہر دن کے لیے کم از کم 366 آیات ہوتی ہیں، اس لیے ایک ہی کیلنڈر سال میں ایک آیت کبھی بھی دو بار ظاہر نہیں ہوتی۔
• چھٹیاں عیسائی تعطیل پر (جیسے کرسمس یا قیامت کا اتوار)، دن کی آیت چھٹی کی آیات میں سے ایک ہے۔ چھٹی ایک وقت میں ایک سال اپنی آیات سے گزرتی ہے، اس لیے ہر سال اس کی ایک الگ آیت ہوتی ہے جب تک کہ اس کی تمام آیات استعمال نہ ہو جائیں۔ ایک تعطیل جو کئی دنوں تک جاری رہتی ہے (جیسے قیامت کے اتوار کے تین دن بعد) ہر دن کی ایک الگ آیت ہوتی ہے۔ چھٹی کی آیات دوسرے دنوں میں استعمال نہیں کی جاتی ہیں۔
• ہر سال ایک نیا آرڈر۔ ہر آیت کے استعمال ہونے کے بعد ترتیب کو دہرایا نہیں جاتا ہے۔ چونکہ ہر سال الگ الگ بدلا جاتا ہے، اسی لیے ایک ہی آیت کبھی کبھار 31 دسمبر کو اور دوبارہ یکم جنوری کو ظاہر ہو سکتی ہے (650 نئے سالوں میں تقریباً 1)۔
• مستحکم تاریخ۔ ڈیٹا سیٹ صرف اس سال کی آیات کو جوڑتا یا ہٹاتا ہے جو ابھی شروع نہیں ہوا ہے ( addedIn اور removedIn دیکھیں)، اس لیے دن کی آیت اس تاریخ کے لیے جو پہلے سے ہو چکی ہے کبھی تبدیل نہیں ہوتی ہے۔
• فہرست ترتیب سے آزاد۔ ایک سال کی ترتیب میں ہر آیت کی جگہ اس کے اپنے حوالہ سے آتی ہے، لہذا فہرست کی ترتیب سے کوئی فرق نہیں پڑتا۔

ان پٹ

الگورتھم

مرحلہ 1: سال اور سال کا دن تلاش کریں۔

سال، مہینہ، اور تاریخ کا دن، اور سال کی تاریخ کا دن، 0 سے شمار کریں: یکم جنوری دن 0 ہے، 31 دسمبر دن 364 ہے (یا لیپ سال میں دن 365)۔

تاریخیں پرولپٹک گریگورین کیلنڈر کا استعمال کرتی ہیں: ایک سال ایک لیپ سال ہے اگر اسے 4 سے تقسیم کیا جا سکتا ہے، سوائے 100 سے تقسیم ہونے والے سالوں کے جو 400 سے تقسیم نہیں ہوتے ہیں (2000 ایک لیپ سال ہے، 1900 نہیں ہے)۔

مرحلہ 2: استعمال میں آنے والی آیات کو رکھیں

سال میں استعمال میں آنے والی آیات کو رکھیں:

• addedIn غائب ہے (یا کالعدم)، یا addedIn <= year ، اور
• removedIn غائب ہے (یا null) یا year < removedIn ۔

مرحلہ 3: جن آیات کو چننا ہے ان کا انتخاب کریں۔

منتخب کرنے کے لیے آیات کا انتخاب کریں، مرحلہ 4 کے لیے ایک اہم سابقہ، اور مرحلہ 7 کے لیے ایک پوزیشن:

1. ایک زمرہ دیا گیا۔ ان آیات کو استعمال میں رکھیں جن کی categories پر مشتمل ہے۔ سابقہ {seed}|{year} ہے اور پوزیشن سال کا دن ہے۔
2. کوئی زمرہ نہیں دیا گیا، اور تاریخ چھٹی ہے۔ تاریخ چھٹی ہوتی ہے اگر holidays میں چھٹی کی تاریخ month اور day ہو، یا اس کے dates میں تاریخ درج ہو ( YYYY-MM-DD کے طور پر لکھا جاتا ہے، چار ہندسوں والے سال کے ساتھ)۔ اگر ایک سے زیادہ تعطیلات مماثل ہیں، تو فہرست میں پہلی چھٹی کا استعمال کریں (ڈیٹا سیٹ میں کبھی بھی ایک ہی تاریخ کو دو چھٹیاں نہیں ہوتی ہیں)۔ ان آیات کو استعمال میں رکھیں جن کے categories میں چھٹی کے id ہیں۔ اگر کوئی ہے تو، سابقہ {seed}|{id} ہے (مثال کے طور پر |christmas ) اور پوزیشن year × k + i ہے، جہاں k سال میں چھٹی منائے جانے والے دنوں کی تعداد ہے ( month اور day کے ساتھ چھٹی کے لیے 1؛ بصورت دیگر تاریخ کے سال میں اس کے dates کی تعداد) اور i ان دنوں کی تعداد ہے جو تاریخ سے پہلے آتے ہیں۔ چھٹی کے لیے جو سال میں ایک دن منایا جاتا ہے، پوزیشن صرف سال ہے۔ اگر کوئی نہیں ہے تو 3 کے ساتھ جاری رکھیں۔
3. ورنہ۔۔۔ ان آیات کو استعمال میں رکھیں جن کے categories میں holidays میں کسی بھی چھٹی کا id شامل نہ ہو۔ سابقہ {seed}|{year} ہے اور پوزیشن سال کا دن ہے۔

seed بیج ہے (بطور ڈیفالٹ خالی سٹرنگ)، اور year اعشاریہ میں مرحلہ 1 سے بغیر آگے صفر کے سال ہے (مثال کے طور پر 2026 ، 1 )۔

اگر کوئی آیت باقی نہ رہے تو دن کی کوئی آیت نہیں ہے۔

تعطیلات جن کی تاریخ ہر سال بدلتی ہے صرف ان تاریخوں کی فہرست بناتی ہے جن کی پہلے سے گنتی کی گئی ہے (فی الحال 2026 سے 2125)، اس لیے دوسرے سالوں میں وہ عام دن ہیں۔ خود تاریخوں کا حساب نہ لگائیں۔

مرحلہ 4: ہر آیت کی کلید بنائیں

باقی رہ جانے والی ہر آیت کے لیے یہ تار بنائیں:

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

• prefix مرحلہ 3 کا سابقہ ​​ہے۔
• book آیت کا book بالکل اسی طرح ہے جیسا کہ ڈیٹاسیٹ میں ظاہر ہوتا ہے (بڑے کیس میں USFM کتاب کی ID جیسے JHN یا 1JN )۔
• chapter اور verse پہلے صفر کے بغیر اعشاریہ میں ہیں۔
• endVerse کلید کا حصہ نہیں ہے۔ ایک عبارت کی پہچان اس کی پہلی آیت سے ہوتی ہے۔

مثال کے طور پر، 2026 میں ایک عام دن جان 3:16 کے لیے پہلے سے طے شدہ بیج کے ساتھ کلید |2026|JHN 3:16 ہے، اور کرسمس پر لوقا 2:7 کے لیے کلید |christmas|LUK 2:7 ہے۔

مرحلہ 5: ہر کلید کو ہیش کریں۔

کلید کے UTF-8 بائٹس کو 32-bit FNV-1a ہیش کے ساتھ ہیش کریں، پھر نتیجہ کو 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 تک کا نمبر۔

مرحلہ 6: آیات کو ترتیب دیں۔

آیات کو ان کی ترتیب کی کلید کے مطابق ترتیب دیں، پہلے سب سے چھوٹی، چابیاں کا غیر دستخط شدہ نمبروں سے موازنہ کریں۔

اگر دو آیات میں ایک ہی ترتیب کی کلید ہے (جو کہ بہت نایاب ہے)، جس کی کلید 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 بٹ انٹیجرز (جاوا، کوٹلن، جاوا اسکرپٹ) والی زبانوں میں، دستخط شدہ 32 بٹ انٹیجرز پر ریاضی کریں اور ایک منطقی دائیں شفٹ ( >>> ) کا استعمال کریں، پھر موازنہ کرنے سے پہلے نتیجہ کو غیر دستخط شدہ قدر (مثلاً hash.toLong() and 0xFFFFFFFF ، یا hash >>> 0 جاوا اسکرپٹ میں) میں تبدیل کریں۔ جاوا اسکرپٹ میں، ضرب کے لیے Math.imul استعمال کریں۔ * درستگی کھو دیتا ہے۔
• بائٹس کے بجائے حروف کو ہیش کرنا۔ کلید کے UTF-8 بائٹس کو ہیش کریں، نہ کہ اس کے UTF-16 کوڈ یونٹس یا یونیکوڈ کوڈ پوائنٹس۔ یہ صرف غیر ASCII حروف والے بیجوں کے لیے اہمیت رکھتا ہے، لیکن ان کی اجازت ہے۔
• "آج" کے لیے UTC کا استعمال دن کی آیت صارف کی مقامی آدھی رات کو بدل جاتی ہے۔ UTC میں تاریخ کا استعمال زیادہ تر ٹائم زونز میں دن کے کچھ حصے کے لیے پچھلے یا اگلے دن کی آیت دکھاتا ہے۔
• 1 سے سال کے دن کی گنتی۔ 1 جنوری دن 0 ہے۔
• چھٹی کی تاریخوں کا حساب لگانا۔ ڈیٹاسیٹ میں درج dates کا استعمال کریں۔ مختلف گرجا گھر اور کیلنڈر ایسٹر کا مختلف طریقے سے حساب لگاتے ہیں، اور ڈیٹاسیٹ صرف ان تاریخوں کی فہرست دیتا ہے جو اس نے پہلے سے مرتب کی ہیں۔
• چھٹیاں چھوڑ کر۔ holidays کے بغیر، چھٹی والی آیات کو عام آیات سمجھا جاتا ہے، جو ہر عام دن کی آیت کو بھی بدل دیتی ہے۔
• حذف شدہ آیات کو چھوڑنا۔ removedIn سال والی آیات اب بھی ڈیٹاسیٹ میں ہیں کیونکہ پچھلے سالوں کو ان کی ضرورت ہے۔ انہیں مرحلہ 2 کے ساتھ فلٹر کریں۔ جب آپ فہرست ڈاؤن لوڈ کرتے ہیں تو انہیں نہ چھوڑیں۔

ٹیسٹ ویکٹرز

عمل درآمد کو چیک کرنے کے لیے ان اقدار کا استعمال کریں۔

ہیشس

سال کے دن

ایک چھوٹی فہرست سے چنتا ہے۔

یہ سولہ آیات کی اس فہرست کو استعمال کرتے ہیں، جن میں سے آٹھ تعطیلات کے لیے ہیں:

[
    { "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 (جو ابھی استعمال میں نہیں ہے) کو چھوڑ دیا گیا ہے، اس لیے سات آیات باقی ہیں۔ ان کی ترتیب کی چابیاں کے مطابق ترتیب دی گئی، وہ ہیں:

یکم جنوری کا دن 0 ہے، اس لیے دن کی آیت زبور 23:1 ہے۔ 15 مارچ دن 73 ہے، اور 73 موڈ 7 = 3، تو یہ جان 3:16 ہے۔

کرسمس پر، صرف کرسمس کی آیات باقی رہ جاتی ہیں جو زیر استعمال ہیں۔ 2027 میں تین ہیں، ان کی ترتیب کی چابیاں کے مطابق:

2027 موڈ 3 = 2، تو کرسمس 2027 کے دن کی آیت لوقا 2:7 ہے۔ 2026 میں، میتھیو 1:23 ابھی تک استعمال میں نہیں ہے، لہذا صرف دو ہیں، اور 2026 موڈ 2 = 0 لیوک 2:10-11 دیتا ہے۔

قیامت کے بعد اتوار کی چھٹی تین دن تک رہتی ہے۔ اس کی چار آیات، ان کی ترتیب کی چابیاں کے مطابق، یہ ہیں:

2026 میں یہ تین دن پر منایا جاتا ہے، لہذا k = 3، اور اپریل 6th، 7th، اور 8th کی پوزیشنیں 2026 × 3 + 0 = 6078, 6079، اور 6080 ہیں۔ 6078 mod 4 = 2، 6079 mod 4 = 4 modians = 60 mod = 3، 80 میں دیتے ہیں 15:20، اعمال 2:24، اور 1 تھیسلنیکیوں 4:14۔ 2027 میں پوزیشنیں 6081 سے جاری رہیں، لہذا اگلی آیت رومیوں 6:9 ہے۔

2028-04-16 کو قیامت کا اتوار ہے، لیکن یہ اس فہرست کے dates میں نہیں ہے، اس لیے یہ ایک عام دن ہے۔

ڈیٹا سیٹ سے چنتا ہے۔

ڈیٹا سیٹ کبھی بھی شروع ہونے والے سال کی آیات کو تبدیل نہیں کرتا ہے، لہذا دن کی یہ 2026 آیات ایک جیسی رہتی ہیں:

نفاذ

یہ نفاذ کنونشن کی پیروی کرتے ہیں، اور ان کے ٹیسٹ اس صفحہ پر موجود اقدار کی جانچ کرتے ہیں:

• JavaScript/TypeScript: free-use-bible-api پیکج میں pickVerseOfTheDay() اور FreeUseBibleApi.getVerseOfTheDay() ( ذریعہ )۔
• کوٹلن: کوٹلن SDK ( ذریعہ ) میں pickVerseOfTheDay() اور FreeUseBibleApi.getVerseOfTheDay() ۔
• Swift: Swift SDK میں pickVerseOfTheDay(_:date:seed:category:holidays:) اور FreeUseBibleAPI.getVerseOfTheDay(date:seed:category:dataset:endpoint:) ( ذریعہ )۔
• MCP سرور کا getVerseOfTheDay ٹول ( ذریعہ )۔
• getVerseOfTheDay() میں @helloao/tools ( source )، جو اس فہرست کو استعمال کرتا ہے جو پیکیج میں شامل ہے۔