1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
/*
* Copyright (c) 2017 Cisco and/or its affiliates.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file parc_Stack.h
* @ingroup datastructures
* @brief PARC (Generic) Stack
*
* A stack interface implementation.
*
* Example
* @code
* #include <parc/algol/parc_Deque.h>
*
* int
* main(int argc, char *argv[])
* {
* PARCStackInterface dequeAsStack = {
* .parcStack_Release = parcDeque_Release,
* .parcStack_IsEmpty = parcDeque_IsEmpty,
* .parcStack_Peek = parcDeque_PeekLast,
* .parcStack_Pop = parcDeque_RemoveLast,
* .parcStack_Push = parcDeque_Append,
* .parcStack_Search = NULL
* };
*
* PARCStack *stack = parcStack(parcDeque_Create(), &dequeAsStack);
*
* parcStack_IsEmpty(stack);
* }
* @endcode
*
*
*/
#ifndef libparc_parc_Stack_h
#define libparc_parc_Stack_h
#include <stdbool.h>
struct parc_stack;
typedef struct parc_stack PARCStack;
typedef struct parc_stack_interface {
/**
* Release the instance
*
*
* @param [in,out] instancePtr A pointer to the pointer of the instance to release.
*
* Example:
* @code
* <#example#>
* @endcode
*/
void (*parcStack_Release)(void **instancePtr);
/**
* Tests if this stack is empty.
*
* @param [in] instance A pointer to the instance to test.
* @return true if the stack is empty
* @return false if the stack is not empty
*
* Example:
* @code
* <#example#>
* @endcode
*/
bool (*parcStack_IsEmpty)(const void *instance);
/**
* Looks at the object at the top of this stack without removing it from the stack.
*
* @param [in] instance A pointer to the instance to look at.
* @return The object at the top of the @p instance.
*
* Example:
* @code
* <#example#>
* @endcode
*/
void * (*parcStack_Peek)(const void *instance);
/**
* Removes the object at the top of this stack and returns that object as the value of this function.
*
*
* @param [in,out] instance A pointer to the instance to check and modify.
* @return The object at the top of the @p instance.
*
* Example:
* @code
* <#example#>
* @endcode
*/
void * (*parcStack_Pop)(void *instance);
/**
* Pushes an item onto the top of this stack.
*
*
* @param [in,out] instance A pointer to the instance to modify.
* @param [in] item A pointer to the object to push on the @p instance.
* @return A pointer to the object that was pushed on the @p instance.
*
* Example:
* @code
* <#example#>
* @endcode
*/
void * (*parcStack_Push)(void *instance, void *item);
/**
* Returns the 1-based position where an object is on this stack.
*
*
* @param [in] instance A pointer to the instance.
* @param [in] element A pointer to the element to find on the @p instance.
* @return The index of the position where @p element is found in the @p instance.
*
* Example:
* @code
* <#example#>
* @endcode
*/
int (*parcStack_Search)(void *instance, void *element);
} PARCStackInterface;
#endif // libparc_parc_Stack_h
|
