STAILQ(3)

الاسم
SIMPLEQ_EMPTY, SIMPLEQ_ENTRY, SIMPLEQ_FIRST, SIMPLEQ_FOREACH, SIMPLEQ_HEAD, SIMPLEQ_HEAD_INITIALIZER, SIMPLEQ_INIT, SIMPLEQ_INSERT_AFTER, SIMPLEQ_INSERT_HEAD, SIMPLEQ_INSERT_TAIL, SIMPLEQ_NEXT, SIMPLEQ_REMOVE, SIMPLEQ_REMOVE_HEAD, STAILQ_CONCAT, STAILQ_EMPTY, STAILQ_ENTRY, STAILQ_FIRST, STAILQ_FOREACH, STAILQ_HEAD, STAILQ_HEAD_INITIALIZER, STAILQ_INIT, STAILQ_INSERT_AFTER, STAILQ_INSERT_HEAD, STAILQ_INSERT_TAIL, STAILQ_NEXT, STAILQ_REMOVE, STAILQ_REMOVE_HEAD, - implementation of a singly linked tail queue

المكتبة
مكتبة سي المعيارية (libc، -lc)

موجز
#include <sys/queue.h>

STAILQ_ENTRY(TYPE);

STAILQ_HEAD(HEADNAME, TYPE);
STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD head);
void STAILQ_INIT(STAILQ_HEAD *head);

int STAILQ_EMPTY(STAILQ_HEAD *head);

void STAILQ_INSERT_HEAD(STAILQ_HEAD *head,
                         struct TYPE *elm, STAILQ_ENTRY NAME);
void STAILQ_INSERT_TAIL(STAILQ_HEAD *head,
                         struct TYPE *elm, STAILQ_ENTRY NAME);
void STAILQ_INSERT_AFTER(STAILQ_HEAD *head, struct TYPE *listelm,
                         struct TYPE *elm, STAILQ_ENTRY NAME);

struct TYPE *STAILQ_FIRST(STAILQ_HEAD *head);
struct TYPE *STAILQ_NEXT(struct TYPE *elm, STAILQ_ENTRY NAME);

STAILQ_FOREACH(struct TYPE *var, STAILQ_HEAD *head, STAILQ_ENTRY NAME);

void STAILQ_REMOVE(STAILQ_HEAD *head, struct TYPE *elm, TYPE,
                         STAILQ_ENTRY NAME);
void STAILQ_REMOVE_HEAD(STAILQ_HEAD *head,
                         STAILQ_ENTRY NAME);

void STAILQ_CONCAT(STAILQ_HEAD *head1, STAILQ_HEAD *head2);
ملاحظة: توجد وحدات ماكرو مطابقة مسبوقة بـ SIMPLEQ بدلاً من STAILQ؛ انظر VERSIONS.

الوصف
تُعرِّف وحدات الماكرو هذه وتُشغِّل طوابير ذيل موصولة وحيدة الاتجاه.

في تعريفات الماكرو، TYPE هو اسم بنية مُعرَّفة من قبل المستخدم، ويجب أن تحتوي على حقل من النوع STAILQ_ENTRY، مُسمى NAME. المُعامل HEADNAME هو اسم بنية مُعرَّفة من قبل المستخدم يجب أن تُصرَّح باستخدام الماكرو STAILQ_HEAD().

  الإنشاء
طابور الذيل الموصول وحيد الاتجاه يُرأَس ببنية مُعرَّفة بواسطة الماكرو STAILQ_HEAD(). تحتوي هذه البنية على زوج من المؤشرات، واحد إلى أول عنصر في طابور الذيل والآخر إلى آخر عنصر في طابور الذيل. العناصر موصولة وحيدة الاتجاه لتقليل المساحة والعبء في معالجة المؤشرات على حساب إزالة O(n) للعناصر العشوائية. يمكن إضافة عناصر جديدة إلى طابور الذيل بعد عنصر موجود، في رأس طابور الذيل، أو في نهاية طابور الذيل. تُصرَّح بنية STAILQ_HEAD كالتالي:

    STAILQ_HEAD(HEADNAME, TYPE) head;

حيث struct HEADNAME هي البنية التي سيتم تعريفها، و struct TYPE هو نوع العناصر التي سيتم وصلها في طابور الذيل. يمكن لاحقاً تعريف مؤشر إلى رأس طابور الذيل كالتالي:

    struct HEADNAME *headp;

(الاسمان head و headp يمكن للمستخدم اختيارهما.)

STAILQ_ENTRY() يُعرِّف بنية تصل العناصر في طابور الذيل.

STAILQ_HEAD_INITIALIZER() يُقيِّم إلى مُهيِّئ لطابور الذيل head.

STAILQ_INIT() يُهيِّئ طابور الذيل المُشار إليه بواسطة head.

STAILQ_EMPTY() يُقيِّم إلى صحيح إذا لم تكن هناك عناصر في طابور الذيل.

  إدراج
STAILQ_INSERT_HEAD() يُدرج العنصر الجديد elm في رأس طابور الذيل.

تدرج STAILQ_INSERT_TAIL() العنصر الجديد elm في نهاية طابور الذيل.

تدرج STAILQ_INSERT_AFTER() العنصر الجديد elm بعد العنصر listelm.

  اجتياز
تُرجع STAILQ_FIRST() أول عنصر في طابور الذيل أو NULL إذا كان طابور الذيل فارغًا.

تُرجع STAILQ_NEXT() العنصر التالي في طابور الذيل، أو NULL إذا كان هذا العنصر هو الأخير.

تعبر STAILQ_FOREACH() طابور الذيل المشار إليه بـ head في الاتجاه الأمامي، مع تخصيص كل عنصر بدوره إلى var.

  إزالة
تزيل STAILQ_REMOVE() العنصر elm من طابور الذيل.

تزيل STAILQ_REMOVE_HEAD() العنصر الموجود في رأس طابور الذيل. لتحقيق الكفاءة المثلى، يجب أن تستخدم العناصر التي تُزال من رأس طابور الذيل هذه الكلية (macro) صراحةً بدلاً من الكلية العامة STAILQ_REMOVE().

  ميزات أخرى
تسلسل STAILQ_CONCAT() طابور الذيل الذي يرأسه head2 إلى نهاية الطابور الذي يرأسه head1 مع إزالة جميع المدخلات من الأول.

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

تُرجع STAILQ_FIRST() و STAILQ_NEXT() مؤشرًا إلى بنية TYPE الأولى أو التالية، على التوالي.

تُرجع STAILQ_HEAD_INITIALIZER() مُهيئًا يمكن تخصيصه للطابور head.

الإصدارات
توفر بعض أنظمة BSD الماكرو SIMPLEQ بدلاً من STAILQ. وهما متطابقان، لكن لأسباب تاريخية سُمِّيَا بشكل مختلف في أنظمة BSD المختلفة. نشأ STAILQ في FreeBSD، ونشأ SIMPLEQ في NetBSD. لأسباب تتعلق بالتوافق، توفر بعض الأنظمة كلا المجموعتين من الماكروهات. توفر glibc كلاً من STAILQ و SIMPLEQ، وهما متطابقان باستثناء عدم وجود مكافئ في SIMPLEQ لـ STAILQ_CONCAT().

العلل
لا تسمح STAILQ_FOREACH() بإزالة var أو تحريره داخل الحلقة، لأن ذلك سيتداخل مع العبور. تعالج STAILQ_FOREACH_SAFE()، الموجودة في أنظمة BSD ولكنها غير موجودة في glibc، هذا القيد بالسماح بإزالة var بأمان من القائمة وتحريره من داخل الحلقة دون التداخل مع العبور.

المعايير
BSD.

التاريخ
4.4BSD.

أمثلة
    #include <stddef.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <sys/queue.h>

    struct entry {
        int data;
        STAILQ_ENTRY(entry) entries;        /* Singly linked tail queue */
    };

    STAILQ_HEAD(stailhead, entry);

    int
    main(void)
    {
        struct entry *n1, *n2, *n3, *np;
        struct stailhead head;                  /* Singly linked tail queue
                                                   head */

        STAILQ_INIT(&head);                     /* Initialize the queue */

        n1 = malloc(sizeof(struct entry));      /* Insert at the head */
        STAILQ_INSERT_HEAD(&head, n1, entries);

        n1 = malloc(sizeof(struct entry));      /* Insert at the tail */
        STAILQ_INSERT_TAIL(&head, n1, entries);

        n2 = malloc(sizeof(struct entry));      /* Insert after */
        STAILQ_INSERT_AFTER(&head, n1, n2, entries);

        STAILQ_REMOVE(&head, n2, entry, entries); /* Deletion */
        free(n2);

        n3 = STAILQ_FIRST(&head);
        STAILQ_REMOVE_HEAD(&head, entries);     /* Deletion from the head */
        free(n3);

        n1 = STAILQ_FIRST(&head);
        n1->data = 0;
        for (unsigned int i = 1; i < 5; i++) {
            n1 = malloc(sizeof(struct entry));
            STAILQ_INSERT_HEAD(&head, n1, entries);
            n1->data = i;
        }
                                                /* Forward traversal */
        STAILQ_FOREACH(np, &head, entries)
            printf("%i\n", np->data);
                                                /* TailQ deletion */
        n1 = STAILQ_FIRST(&head);
        while (n1 != NULL) {
            n2 = STAILQ_NEXT(n1, entries);
            free(n1);
            n1 = n2;
        }
        STAILQ_INIT(&head);

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
insque(3)، queue(7)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.