jh_queue: jh_queue是一个先进先出(FIFO)的队列(queue)。支持所有队列的基本功能，支持任意数据结构，本身没有内存的申请与释放，队列的空间由外部提供。jh_queue也是一个受限的双端队列，队尾支持先进后出(FILO)，可以从队尾弹出数据，变成一个栈(stack)。

# jh_queue

## 介绍

jh_queue是一个先进先出(FIFO)的队列(queue)。支持所有队列的基本功能，支持任意数据结构，本身没有内存的申请与释放，队列的空间由外部提供。jh_queue也是一个受限的双端队列，队尾支持先进后出(FILO)，可以从队尾弹出数据，变成一个栈(stack)。

## 使用说明

只需要包含jh_queue.c和jh_queue.h两个文件即可使用。

## 接口函数

提供以下接口用于队列的使用：

```c
/*判断队列是否为空*/
int jh_queue_is_empty(jh_queue_t* queue);
/*判断队列是否已满*/
int jh_queue_is_full(jh_queue_t* queue);
/*获取队列的数据数量*/
size_t jh_queue_count(jh_queue_t* queue);
/*数据入队*/
int jh_queue_push(jh_queue_t* queue, void* item);
/*数据出队*/
int jh_queue_pop(jh_queue_t* queue, void* item);
/*队尾数据出队*/
int jh_queue_pop_tail(jh_queue_t* queue, void* item);
/*查看队首的数据*/
int jh_queue_peek(jh_queue_t* queue, void* item);
/*查看队首的数据*/
int jh_queue_peek_head(jh_queue_t* queue, void* item);
/*查看队尾的数据*/
int jh_queue_peek_tail(jh_queue_t* queue, void* item);
/*清空队列*/
int jh_queue_clear(jh_queue_t* queue);
/*队列初始化*/
int jh_queue_init(jh_queue_t* queue, void* base, size_t num, size_t size);
```

另外还提供两个宏接口用于数据迭代：

```c
/*队列数据迭代*/
JH_QUEUE_ITER(jh_queue_t* queue, void* item)
/*队列数据反向迭代*/
JH_QUEUE_ITER_REVERSE(jh_queue_t* queue, void* item)
```

## 接口使用说明

### 1.队列初始化

调用接口`jh_queue_init`初始化队列。

```c
/*队列初始化*/
int jh_queue_init(jh_queue_t* queue, void* base, size_t num, size_t size);
```

函数参数含义：

| 参数    | 含义                          |
| ----- | --------------------------- |
| queue | 队列句柄，需要定义一个类型为jh_queue_t的参数 |
| base  | 指向用于队列的数组                   |
| num   | 数组中能存放的数据项数量                |
| size  | 数组中每个数据项的大小                 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

使用示例：

```c
//定义数据结构和用于存放数据的数组
jh_queue_t queue;
int buf[10];

//队列初始化
jh_queue_init(&queue, buf, 10, sizeof(int));
```

**注意**：初始化时传入值`num`，但实际可用于入队的数据数量为`num - 1`。例如上述的示例，定义用于存放数据的数组长度为10，但实际可以用于入队的数据数量为9。

### 2.数据入队

调用接口`jh_queue_push`将数据入队。

```c
/*数据入队*/
int jh_queue_push(jh_queue_t* queue, void* item);
```

函数参数含义：

| 参数    | 含义      |
| ----- | ------- |
| queue | 队列      |
| item  | 要入队的数据项 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 3.数据出队

调用接口`jh_queue_pop`将数据出队。

```c
/*数据出队*/
int jh_queue_pop(jh_queue_t* queue, void* item);
```

函数参数含义：

| 参数    | 含义      |
| ----- | ------- |
| queue | 队列      |
| item  | 要出队的数据项 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 4.队尾数据出队

调用接口`jh_queue_pop_tail`将队尾数据出队。

```c
/*队尾数据出队*/
int jh_queue_pop_tail(jh_queue_t* queue, void* item);
```

函数参数含义：

| 参数    | 含义      |
| ----- | ------- |
| queue | 队列      |
| item  | 要出队的数据项 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 5.查看队首的数据

调用接口`jh_queue_peek`查看队首的数据。

```c
/*查看队首的数据*/
int jh_queue_peek(jh_queue_t* queue, void* item);
```

函数参数含义：

| 参数    | 含义     |
| ----- | ------ |
| queue | 队列     |
| item  | 队首的数据项 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 6.查看队尾的数据

调用接口`jh_queue_peek_tail`查看队尾的数据。

```c
/*查看队尾的数据*/
int jh_queue_peek_tail(jh_queue_t* queue, void* item);
```

函数参数含义：

| 参数    | 含义     |
| ----- | ------ |
| queue | 队列     |
| item  | 队尾的数据项 |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 7.获取队列的数据数量

调用接口`jh_queue_count`查看队列中已有的数据数量。

```c
/*获取队列的数据数量*/
size_t jh_queue_count(jh_queue_t* queue);
```

函数参数含义：

| 参数    | 含义  |
| ----- | --- |
| queue | 队列  |

函数返回值：

| 返回值 | 含义           |
| ------ | -------------- |
| >=0    | 队列的数据数量 |

### 8.判断队列是否已满

调用接口`jh_queue_is_full`判断队列是否已满。

```c
/*判断队列是否已满*/
int jh_queue_is_full(jh_queue_t* queue);
```

函数参数含义：

| 参数    | 含义  |
| ----- | --- |
| queue | 队列  |

函数返回值：

| 返回值 | 含义   |
| --- | ---- |
| 1   | 队列已满 |
| 0   | 队列未满 |
| -1  | 失败   |

**注意**：队列可用于入队的最大数据数量为`num - 1`，`num`指的是在初始化时调用接口`jh_queue_init`时设置的`num`。

### 9.判断队列是否为空

调用接口`jh_queue_is_empty`判断队列是否为空。

```c
/*判断队列是否为空*/
int jh_queue_is_empty(jh_queue_t* queue);
```

函数参数含义：

| 参数    | 含义  |
| ----- | --- |
| queue | 队列  |

函数返回值：

| 返回值 | 含义    |
| --- | ----- |
| 1   | 队列为空  |
| 0   | 队列不为空 |
| -1  | 失败    |

### 10.清空队列

调用接口`jh_queue_clear`清空队列内的数据。

```c
/*清空队列*/
int jh_queue_clear(jh_queue_t* queue);
```

函数参数含义：

| 参数    | 含义  |
| ----- | --- |
| queue | 队列  |

函数返回值：

| 返回值 | 含义  |
| --- | --- |
| 0   | 成功  |
| -1  | 失败  |

### 11.队列数据迭代

调用接口`JH_QUEUE_ITER`或者`JH_QUEUE_ITER_REVERSE`进行数据迭代。

```c
/*队列数据迭代*/
JH_QUEUE_ITER(jh_queue_t* queue, void* item)
/*队列数据反向迭代*/
JH_QUEUE_ITER_REVERSE(jh_queue_t* queue, void* item)
```

函数参数含义：

| 参数    | 含义  |
| ----- | --- |
| queue | 队列  |
| item  | 数据项 |

使用示例，打印出当前队列中的所有数据：

```c
//从队首到队尾的顺序遍历
JH_QUEUE_ITER(&queue, &val) {
    printf("val : %d\n", val);
}

//从队尾到队首的顺序遍历
JH_QUEUE_ITER_REVERSE(&queue, &val) {
    printf("val : %d\n", val);
}
```

## 使用示例

队列的基础用法：

```c
int main(int argc, char* argv[])
{
    //定义数据结构和用于存放数据的数组
    jh_queue_t queue;
    int buf[10];

//队列初始化
    jh_queue_init(&queue, buf, 10, sizeof(int));

//定义要用于传入的数据
    int items[] = {81, 13, 16, 38, 49, 67};
    int i, val;

//数据入队
    printf("push :\n");
    for(i = 0; i < sizeof(items)/sizeof(int); i++) {
        if(!jh_queue_push(&queue, &items[i]))
            printf("%d ", items[i]);
    }
    printf("\n");

//查看当前的状态
    printf("\nsize : %d empty : %d full : %d\n", jh_queue_count(&queue), jh_queue_is_empty(&queue), jh_queue_is_full(&queue));

//查看队首的数据
    jh_queue_peek(&queue, &val);
    printf("peek %d\n", val);

//查看队尾的数据
    jh_queue_peek_tail(&queue, &val);
    printf("peek tail %d\n", val);

//数据出队
    printf("\npop:\n");
    for(i = 0; i < sizeof(items)/sizeof(int); i++) {
        if(!jh_queue_pop(&queue, &val))
            printf("%d ", val);
    }
    printf("\n");

//查看当前的状态
    printf("\nsize : %d empty : %d full : %d\n", jh_queue_count(&queue), jh_queue_is_empty(&queue), jh_queue_is_full(&queue));

//数据入队
    printf("\npush :\n");
    for(i = 0; i < sizeof(items)/sizeof(int); i++) {
        if(!jh_queue_push(&queue, &items[i]))
            printf("%d ", items[i]);
    }
    printf("\n");

//可以查看当前所有数据，从队首到队尾的顺序遍历
    printf("\niter:\n");
    JH_QUEUE_ITER(&queue, &val) {
        printf("%d ", val);
    }
    printf("\n");

//可以查看当前所有数据，从队尾到队首的顺序遍历
    printf("\niter reverse:\n");
    JH_QUEUE_ITER_REVERSE(&queue, &val) {
        printf("%d ", val);
    }
    printf("\n");

//将队尾数据出队，可以作为栈使用
    printf("\npop tail:\n");
    for(i = 0; i < sizeof(items)/sizeof(int); i++) {
        if(!jh_queue_pop_tail(&queue, &val))
            printf("%d ", val);
    }
    printf("\n");

//查看当前的状态
    printf("\nsize : %d empty : %d full : %d\n", jh_queue_count(&queue), jh_queue_is_empty(&queue), jh_queue_is_full(&queue));

//数据入队
    printf("\npush :\n");
    for(i = 0; i < sizeof(items)/sizeof(int); i++) {
        if(!jh_queue_push(&queue, &items[i]))
            printf("%d ", items[i]);
    }
    printf("\n");

//清空队列
    printf("\nclear\n");
    jh_queue_clear(&queue);

//查看当前的状态
    printf("\nsize : %d empty : %d full : %d\n", jh_queue_count(&queue), jh_queue_is_empty(&queue), jh_queue_is_full(&queue));

return 0;
}
```

运行结果如下：

```shell
push :
81 13 16 38 49 67

size : 6 empty : 0 full : 0
peek 81
peek tail 67

pop:
81 13 16 38 49 67

size : 0 empty : 1 full : 0

push :
81 13 16 38 49 67

iter:
81 13 16 38 49 67

iter reverse:
67 49 38 16 13 81

pop tail:
67 49 38 16 13 81

size : 0 empty : 1 full : 0

push :
81 13 16 38 49 67

clear

size : 0 empty : 1 full : 0
```

## License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Jason_Huang/jh_queue

简介

发行版

贡献者

近期动态

Jason_Huang/jh_queue .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Jason_Huang/jh_queue