Collections.subproj/CFStorage.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*      CFStorage.h
  26         Copyright (c) 1999-2003, Apple, Inc. All rights reserved.
  27 */
  28 /*!
  29         @header CFStorage
  30 CFStorage stores an array of arbitrary-sized values. There are no callbacks;
  31 all that is provided about the values is the size, and the appropriate number
  32 of bytes are copied in and out of the CFStorage.
  33
  34 CFStorage uses a balanced tree to store the values, and is most appropriate
  35 for situations where potentially a large number values (more than a hundred
  36 bytes' worth) will be stored and there will be a lot of editing (insertions and deletions).
  37
  38 Getting to an item is O(log n), although caching the last result often reduces this
  39 to a constant time.
  40
  41 The overhead of CFStorage is 48 bytes. There is no per item overhead; the
  42 non-leaf nodes in the tree cost 20 bytes each, and the worst case extra
  43 capacity (unused space in the leaves) is 12%, typically much less.
  44
  45 Because CFStorage does not necessarily use a single block of memory to store the values,
  46 when you ask for a value, you get back the pointer to the value and optionally
  47 the range of other values that are consecutive and thus reachable as if the
  48 storage was a single block.
  49 */
  50
  51 #if !defined(__COREFOUNDATION_CFSTORAGE__)
  52 #define __COREFOUNDATION_CFSTORAGE__ 1
  53
  54 #include <CoreFoundation/CFBase.h>
  55
  56 #if defined(__cplusplus)
  57 extern "C" {
  58 #endif
  59
  60 /*!
  61         @typedef CFStorageRef
  62         This is the type of a reference to a CFStorage instance.
  63 */
  64 typedef struct __CFStorage *CFStorageRef;
  65
  66 /*!
  67         @typedef CFStorageApplierFunction
  68         Type of the callback function used by the apply functions of
  69                 CFStorage.
  70         @param value The current value from the storage.
  71         @param context The user-defined context parameter given to the apply
  72                 function.
  73 */
  74 typedef void (*CFStorageApplierFunction)(const void *val, void *context);
  75
  76 /*!
  77         @function CFStorageGetTypeID
  78         Returns the type identifier of all CFStorage instances.
  79 */
  80 CF_EXPORT CFTypeID CFStorageGetTypeID(void);
  81
  82 /*!
  83         @function CFStorageCreate
  84         Creates a new mutable storage with elements of the given size.
  85         @param alloc The CFAllocator which should be used to allocate
  86                 memory for the set and its storage for values. This
  87                 parameter may be NULL in which case the current default
  88                 CFAllocator is used. If this reference is not a valid
  89                 CFAllocator, the behavior is undefined.
  90         @param valueSizeInBytes The size in bytes of each of the elements
  91                 to be stored in the storage.  If this value is zero or
  92                 negative, the result is undefined.
  93         @result A reference to the new CFStorage instance.
  94 */
  95 CF_EXPORT CFStorageRef CFStorageCreate(CFAllocatorRef alloc, CFIndex valueSizeInBytes);
  96
  97 /*!
  98         @function CFStorageInsertValues
  99         Allocates space for range.length values at location range.location.  Use
 100         CFStorageReplaceValues() to set those values.
 101         @param storage The storage to which the values are to be inserted.
 102                 If this parameter is not a valid CFStorage, the behavior is undefined.
 103         @param range The range of values within the storage to delete. If the
 104                 range location or end point (defined by the location plus
 105                 length minus 1) are outside the index space of the storage (0
 106                 to N inclusive, where N is the count of the storage), the
 107                 behavior is undefined. If the range length is negative, the
 108                 behavior is undefined. The range may be empty (length 0),
 109                 in which case the no values are inserted.
 110 */
 111 CF_EXPORT void CFStorageInsertValues(CFStorageRef storage, CFRange range);
 112
 113 /*!
 114         @function CFStorageDeleteValues
 115         Deletes the values of the storage in the specified range.
 116         @param storage The storage from which the values are to be deleted.
 117                 If this parameter is not a valid CFStorage, the behavior is undefined.
 118         @param range The range of values within the storage to delete. If the
 119                 range location or end point (defined by the location plus
 120                 length minus 1) are outside the index space of the storage (0
 121                 to N inclusive, where N is the count of the storage), the
 122                 behavior is undefined. If the range length is negative, the
 123                 behavior is undefined. The range may be empty (length 0),
 124                 in which case the no values are deleted.
 125 */
 126 CF_EXPORT void CFStorageDeleteValues(CFStorageRef storage, CFRange range);
 127
 128 /*!
 129         @function CFStorageGetCount
 130         Returns the number of values currently in the storage.
 131         @param storage The storage to be queried. If this parameter is not a valid
 132                 CFStorage, the behavior is undefined.
 133         @result The number of values in the storage.
 134 */
 135 CF_EXPORT CFIndex CFStorageGetCount(CFStorageRef storage);
 136
 137 /*!
 138         @function CFStorageGetValueAtIndex
 139         Returns a pointer to the specified value.  The pointer is mutable and may be used to
 140         get or set the value.
 141         @param storage The storage to be queried. If this parameter is not a
 142                 valid CFStorage, the behavior is undefined.
 143         @param idx The index of the value to retrieve. If the index is
 144                 outside the index space of the storage (0 to N-1 inclusive,
 145                 where N is the count of the storage), the behavior is
 146                 undefined.
 147         @param validConsecutiveValueRange This parameter is a C pointer to a CFRange.
 148                 If NULL is specified, this argument is ignored; otherwise, the range
 149                 is set to the range of values that may be accessed via an offset from the result pointer.
 150                 The range location is set to the index of the lowest consecutive
 151                 value and the range length is set to the count of consecutive values.
 152         @result The value with the given index in the storage.
 153 */
 154 CF_EXPORT void *CFStorageGetValueAtIndex(CFStorageRef storage, CFIndex idx, CFRange *validConsecutiveValueRange);
 155
 156 /*!
 157         @function CFStorageGetValues
 158         Fills the buffer with values from the storage.
 159         @param storage The storage to be queried. If this parameter is not a
 160                 valid CFStorage, the behavior is undefined.
 161         @param range The range of values within the storage to retrieve. If
 162                 the range location or end point (defined by the location
 163                 plus length minus 1) are outside the index space of the
 164                 storage (0 to N-1 inclusive, where N is the count of the
 165                 storage), the behavior is undefined. If the range length is
 166                 negative, the behavior is undefined. The range may be empty
 167                 (length 0), in which case no values are put into the buffer.
 168         @param values A C array of to be filled with values from the storage.
 169                 The values in the C array are ordered
 170                 in the same order in which they appear in the storage. If this
 171                 parameter is not a valid pointer to a C array of at least
 172                 range.length pointers, the behavior is undefined.
 173 */
 174 CF_EXPORT void CFStorageGetValues(CFStorageRef storage, CFRange range, void *values);
 175
 176 /*!
 177         @function CFStorageApplyFunction
 178         Calls a function once for each value in the set.
 179         @param storage The storage to be operated upon. If this parameter is not
 180                 a valid CFStorage, the behavior is undefined.
 181         @param range The range of values within the storage to operate on. If the
 182                 range location or end point (defined by the location plus
 183                 length minus 1) are outside the index space of the storage (0
 184                 to N inclusive, where N is the count of the storage), the
 185                 behavior is undefined. If the range length is negative, the
 186                 behavior is undefined. The range may be empty (length 0),
 187                 in which case the no values are operated on.
 188         @param applier The callback function to call once for each value in
 189                 the given storage. If this parameter is not a
 190                 pointer to a function of the correct prototype, the behavior
 191                 is undefined. If there are values in the storage which the
 192                 applier function does not expect or cannot properly apply
 193                 to, the behavior is undefined.
 194         @param context A pointer-sized user-defined value, which is passed
 195                 as the second parameter to the applier function, but is
 196                 otherwise unused by this function. If the context is not
 197                 what is expected by the applier function, the behavior is
 198                 undefined.
 199 */
 200 CF_EXPORT void CFStorageApplyFunction(CFStorageRef storage, CFRange range, CFStorageApplierFunction applier, void *context);
 201
 202 /*!
 203         @function CFStorageReplaceValues
 204         Replaces a range of values in the storage.
 205         @param storage The storage from which the specified values are to be
 206                 removed. If this parameter is not a valid CFStorage,
 207                 the behavior is undefined.
 208         @param range The range of values within the storage to replace. If the
 209                 range location or end point (defined by the location plus
 210                 length minus 1) are outside the index space of the storage (0
 211                 to N inclusive, where N is the count of the storage), the
 212                 behavior is undefined. If the range length is negative, the
 213                 behavior is undefined. The range may be empty (length 0),
 214                 in which case the new values are merely inserted at the
 215                 range location.
 216         @param values A C array of the values to be copied into the storage.
 217                 The new values in the storage are ordered in the same order
 218                 in which they appear in this C array. This parameter may be NULL
 219                 if the range length is 0.  This C array is not changed or freed by
 220                 this function. If this parameter is not a valid pointer to a C array of at least
 221                 range length pointers, the behavior is undefined.
 222 */
 223 CF_EXPORT void CFStorageReplaceValues(CFStorageRef storage, CFRange range, const void *values);
 224
 225 /* Private stuff...
 226 */
 227 CF_EXPORT CFIndex __CFStorageGetCapacity(CFStorageRef storage);
 228 CF_EXPORT CFIndex __CFStorageGetValueSize(CFStorageRef storage);
 229
 230
 231 #if defined(__cplusplus)
 232 }
 233 #endif
 234
 235 #endif /* ! __COREFOUNDATION_CFSTORAGE__ */
 236