1 /* CFArray.h
2 
3    Copyright (C) 2010 Free Software Foundation, Inc.
4 
5    Written by: Stefan Bidigaray
6    Date: January, 2010
7 
8    This file is part of CoreBase.
9 
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 2.1 of the License, or (at your option) any later version.
14 
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
18    Lesser General Public License for more details.
19 
20    You should have received a copy of the GNU Lesser General Public
21    License along with this library; see the file COPYING.LIB.
22    If not, see <http://www.gnu.org/licenses/> or write to the
23    Free Software Foundation, 51 Franklin Street, Fifth Floor,
24    Boston, MA 02110-1301, USA.
25 */
26 
27 
28 #ifndef __COREFOUNDATION_CFARRAY_H__
29 #define __COREFOUNDATION_CFARRAY_H__
30 
31 #include "CFBase.h"
32 
33 CF_EXTERN_C_BEGIN
34 /** \ingroup CFArrayRef
35     \brief Reference to an immutable array object.
36  */
37 typedef const struct __CFArray *CFArrayRef;
38 /**
39     \ingroup CFMutableArrayRef
40     \brief Reference to a mutable array object.
41  */
42 typedef struct __CFArray *CFMutableArrayRef;
43 
44 /** \defgroup CFArrayRef CFArray Reference
45     \brief A CFArray and its mutable type, \ref CFMutableArrayRef
46       "CFMutableArray", are simple, low overhead, ordered containers for
47       objects.
48     \details
49       <code>\#include <CoreFoundation/CFArray.h></code>
50     \{
51  */
52 
53 /** \name Callbacks
54     \{
55  */
56 typedef void (*CFArrayApplierFunction) (const void *value, void *context);
57 typedef CFStringRef (*CFArrayCopyDescriptionCallBack) (const void *value);
58 typedef void (*CFArrayReleaseCallBack) (CFAllocatorRef allocator,
59                                         const void *value);
60 typedef const void *(*CFArrayRetainCallBack) (CFAllocatorRef allocator,
61                                               const void *value);
62 typedef Boolean (*CFArrayEqualCallBack) (const void *value1,
63                                          const void *value2);
64 /** \} */
65 
66 /** \brief Structure with CFArray callbacks.
67  */
68 typedef struct _CFArrayCallBacks CFArrayCallBacks;
69 struct _CFArrayCallBacks
70 {
71   CFIndex version; /**< Structure's version number.  Current version is 0. */
72   CFArrayRetainCallBack retain;
73     /**< The callback used to retain values added to the array.  If NULL,
74 	 values are not retained. */
75   CFArrayReleaseCallBack release;
76   CFArrayCopyDescriptionCallBack copyDescription;
77   CFArrayEqualCallBack equal;
78 };
79 
80 /** \name Predefined Callback Structures
81     \{
82  */
83 CF_EXPORT const CFArrayCallBacks kCFTypeArrayCallBacks;
84 /** \} */
85 
86 
87 
88 /** \name Creating an Array
89     \{
90  */
91 CF_EXPORT CFArrayRef
92 CFArrayCreate (CFAllocatorRef allocator, const void **values,
93                CFIndex numValues, const CFArrayCallBacks * callBacks);
94 
95 CF_EXPORT CFArrayRef
96 CFArrayCreateCopy (CFAllocatorRef allocator, CFArrayRef theArray);
97 /** \} */
98 
99 /** \name Examining an Array
100     \{
101  */
102 CF_EXPORT CFIndex
103 CFArrayBSearchValues (CFArrayRef theArray, CFRange range, const void *value,
104                       CFComparatorFunction comparator, void *context);
105 
106 CF_EXPORT Boolean
107 CFArrayContainsValue (CFArrayRef theArray, CFRange range, const void *value);
108 
109 CF_EXPORT CFIndex CFArrayGetCount (CFArrayRef theArray);
110 
111 CF_EXPORT CFIndex
112 CFArrayGetCountOfValue (CFArrayRef theArray, CFRange range, const void *value);
113 
114 CF_EXPORT CFIndex
115 CFArrayGetFirstIndexOfValue (CFArrayRef theArray, CFRange range,
116                              const void *value);
117 
118 CF_EXPORT CFIndex
119 CFArrayGetLastIndexOfValue (CFArrayRef theArray, CFRange range,
120                             const void *value);
121 
122 CF_EXPORT void
123 CFArrayGetValues (CFArrayRef theArray, CFRange range, const void **values);
124 
125 CF_EXPORT const void *CFArrayGetValueAtIndex (CFArrayRef theArray, CFIndex idx);
126 /** \} */
127 
128 /** \name Applying a Function to Elements
129     \{
130  */
131 CF_EXPORT void
132 CFArrayApplyFunction (CFArrayRef theArray, CFRange range,
133                       CFArrayApplierFunction applier, void *context);
134 /** \} */
135 
136 /** \name Getting the CFArray Type ID
137     \{
138  */
139 CF_EXPORT CFTypeID CFArrayGetTypeID (void);
140 /** \} */
141 
142 /** \} */
143 
144 /** \defgroup CFMutableArrayRef CFMutableArray Reference
145     \details <code>\#include <CoreFoundation/CFArray.h></code>
146     \{
147  */
148 CF_EXPORT void
149 CFArrayAppendArray (CFMutableArrayRef theArray, CFArrayRef otherArray,
150                     CFRange otherRange);
151 
152 CF_EXPORT void
153 CFArrayAppendValue (CFMutableArrayRef theArray, const void *value);
154 
155 CF_EXPORT CFMutableArrayRef
156 CFArrayCreateMutable (CFAllocatorRef allocator, CFIndex capacity,
157                       const CFArrayCallBacks * callBacks);
158 
159 CF_EXPORT CFMutableArrayRef
160 CFArrayCreateMutableCopy (CFAllocatorRef allocator, CFIndex capacity,
161                           CFArrayRef theArray);
162 
163 CF_EXPORT void
164 CFArrayExchangeValuesAtIndices (CFMutableArrayRef theArray, CFIndex idx1,
165                                 CFIndex idx2);
166 
167 CF_EXPORT void
168 CFArrayInsertValueAtIndex (CFMutableArrayRef theArray, CFIndex idx,
169                            const void *value);
170 
171 CF_EXPORT void CFArrayRemoveAllValues (CFMutableArrayRef theArray);
172 
173 CF_EXPORT void
174 CFArrayRemoveValueAtIndex (CFMutableArrayRef theArray, CFIndex idx);
175 
176 CF_EXPORT void
177 CFArrayReplaceValues (CFMutableArrayRef theArray, CFRange range,
178                       const void **newValues, CFIndex newCount);
179 
180 CF_EXPORT void
181 CFArraySetValueAtIndex (CFMutableArrayRef theArray, CFIndex idx,
182                         const void *value);
183 
184 CF_EXPORT void
185 CFArraySortValues (CFMutableArrayRef theArray, CFRange range,
186                    CFComparatorFunction comparator, void *context);
187 
188 /** \} */
189 
190 CF_EXTERN_C_END
191 #endif /* __COREFOUNDATION_CFARRAY_H__ */
192