varch/doc/cQueue.en.md

Introduction

A queue is a special data structure with the characteristic of First In First Out (FIFO). Generally, it has only one entrance and one exit. Data enters from the rear of the queue and exits from the front. The operations of adding an element to the queue is called "push", and removing an element from the queue is called "pop".

cQueue is a queue control entity. It is not a container by itself and is different from the queue in varch, but its usage is quite similar.

Interface

Defining the Queue Type

Since cQueue itself is not a data container, a new data structure needs to be defined for the data type it stores. Here is an example:

typedef struct 
{
    cQueue queue;               // The first member, which is default and usually doesn't need to be changed
    int data[10];               // The second member, defining the actual data array to be stored. The array type can be any type, and the array name is always "data". The capacity depends on the actual requirements.
} intQueueType;                 // Defining a new data structure type
intQueueType intQueue;          // Defining a new structure variable

There is also a simpler definition method. This method defines an anonymous structure type and defines a variable based on this structure. Therefore, this method can only be used locally.

cQueue(int, 64) queue;

Initializing the Queue

#define cQueue_init(qObject)

It is a macro definition method and can be adapted to various data types.

void test_int(void)
{
    typedef struct 
    {
        cQueue queue;
        int data[10];
    } intQueueType;
    intQueueType intQueue;

    cQueue_init(intQueue);
}

Checking if the Queue is Empty or Full

#define cQueue_empty(qObject)
#define cQueue_full(qObject)

These two methods are actually related to the size of the queue's size. If it equals 0, the queue is empty. If it equals the capacity, the queue is full.

Pushing and Popping Data in the Queue

#define cQueue_push(qObject, d)
#define cQueue_pop(qObject, d)

These two methods are used to push data d into the queue and pop data from the queue to d respectively.

void test_int(void)
{
    typedef struct 
    {
        cQueue queue;
        int data[10];
    } intQueueType;
    intQueueType intQueue;

    cQueue_init(intQueue);

    for (int i = 0; i < intQueue.queue.cap; i++)
    {
        cQueue_push(intQueue, i);
    }

    while (intQueue.queue.size > 0)
    {
        int data;
        cQueue_pop(intQueue, data);
        printf("cQueue_pop %d\r\n", data);
    }
}

Result:

cQueue_pop 0
cQueue_pop 1
cQueue_pop 2
cQueue_pop 3
cQueue_pop 4
cQueue_pop 5
cQueue_pop 6
cQueue_pop 7
cQueue_pop 8
cQueue_pop 9

Accessing Data in the Queue

#define cQueue_at(qObject, i)

It is used to randomly access data in the queue.

void test_int(void)
{
    typedef struct 
    {
        cQueue queue;
        int data[10];
    } intQueueType;
    intQueueType intQueue;

    cQueue_init(intQueue);

    for (int i = 0; i < intQueue.queue.cap; i++)
    {
        cQueue_push(intQueue, i);
    }

    printf("cQueue[5] = %d\r\n", cQueue_at(intQueue, 5));
}

Result:

cQueue[5] = 5

Example of Special Data Structure

void test_struct(void)
{
    typedef struct 
    {
        char *name;
        int age;
    } Stu;
    typedef struct 
    {
        cQueue queue;
        Stu data[10];
    } StuQueueType;
    StuQueueType StuQueue;

    Stu s = {"Zhang", 18};

    cQueue_init(StuQueue);

    for (int i = 0; i < StuQueue.queue.cap; i++)
    {
        s.age = 18 + i;
        cQueue_push(StuQueue, s);
    }

    while (StuQueue.queue.size > 0)
    {
        cQueue_pop(StuQueue, s);
        printf("cQueue_pop name: %s age %d\r\n", s.name, s.age);
    }
}

Result:

cQueue_pop name: Zhang age 18
cQueue_pop name: Zhang age 19
cQueue_pop name: Zhang age 20
cQueue_pop name: Zhang age 21
cQueue_pop name: Zhang age 22
cQueue_pop name: Zhang age 23
cQueue_pop name: Zhang age 24
cQueue_pop name: Zhang age 25
cQueue_pop name: Zhang age 26
cQueue_pop name: Zhang age 27