1/*
2 * Copyright (c) 2014 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24/*	CFBurstTrie.h
25        Copyright (c) 2008-2013, Apple Inc. All rights reserved.
26*/
27
28#if !defined(__COREFOUNDATION_CFBURSTTRIE__)
29#define __COREFOUNDATION_CFBURSTTRIE__ 1
30
31#include <CoreFoundation/CFString.h>
32#include <CoreFoundation/CFDictionary.h>
33
34CF_EXTERN_C_BEGIN
35
36typedef struct _CFBurstTrie *CFBurstTrieRef;
37typedef struct _CFBurstTrieCursor *CFBurstTrieCursorRef;
38
39typedef CF_OPTIONS(CFOptionFlags, CFBurstTrieOpts) {
40        /*!
41         BurstTrie Options
42         Use one or more of these options with CFBurstTrieCreate to tailor optimizations to the data
43         structure for a specific kind of application. Default is no read-write, no compression.
44         */
45
46    /*  kCFBurstTrieReadOnly
47        When specified, the dictionary file will be serialized in an optimized format so as to be
48        memory-mapped on the next read. Once a trie is serialized as read-only, insertions can no
49        longer occur.
50    */
51    kCFBurstTrieReadOnly            = 1<<1,
52
53    /*  kCFBurstTrieBitmapCompression
54        This option can only be used with a read-only trie, and can be used to reduce on disk file size.
55    */
56    kCFBurstTrieBitmapCompression   = 1<<2,
57
58    /*
59        kCFBurstTriePrefixCompression
60        This option can only be used with a read-only trie, and can be used to reduce on-disk file size.
61        It is important to note that any optimizations based on word frequency will be lost; recommended
62        for applications that often search for infrequent or uncommon words. This also allow you to use
63        cursor interface.
64    */
65    kCFBurstTriePrefixCompression   = 1<<3,
66
67    /*
68        kCFBurstTriePrefixCompression
69        By default, keys at list level are sorted by weight. Use this option to sort them by key value.
70        This allow you to use cursor interface.
71     */
72    kCFBurstTrieSortByKey = 1 << 4
73};
74
75// Value for this option should be a CFNumber which contains an int.
76#define kCFBurstTrieCreationOptionNameContainerSize CFSTR("ContainerSize")
77
78typedef void (*CFBurstTrieTraversalCallback)(void* context, const UInt8* key, uint32_t keyLength, uint32_t payload, Boolean *stop);
79
80CF_EXPORT
81CFBurstTrieRef CFBurstTrieCreate() CF_AVAILABLE(10_7, 4_2);
82
83CF_EXPORT
84CFBurstTrieRef CFBurstTrieCreateWithOptions(CFDictionaryRef options) CF_AVAILABLE(10_8, 6_0);
85
86CF_EXPORT
87CFBurstTrieRef CFBurstTrieCreateFromFile(CFStringRef path) CF_AVAILABLE(10_7, 4_2);
88
89CF_EXPORT
90CFBurstTrieRef CFBurstTrieCreateFromMapBytes(char *mapBase) CF_AVAILABLE(10_7, 4_2);
91
92CF_EXPORT
93Boolean CFBurstTrieInsert(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
94
95CF_EXPORT
96Boolean CFBurstTrieAdd(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
97
98
99CF_EXPORT
100Boolean CFBurstTrieInsertCharacters(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
101
102CF_EXPORT
103Boolean CFBurstTrieAddCharacters(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
104
105
106CF_EXPORT
107Boolean CFBurstTrieInsertUTF8String(CFBurstTrieRef trie, UInt8 *chars, CFIndex numChars, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
108
109CF_EXPORT
110Boolean CFBurstTrieAddUTF8String(CFBurstTrieRef trie, UInt8 *chars, CFIndex numChars, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
111
112
113CF_EXPORT
114Boolean CFBurstTrieInsertWithWeight(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, CFIndex weight, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
115
116CF_EXPORT
117Boolean CFBurstTrieAddWithWeight(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, uint32_t weight, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
118
119
120CF_EXPORT
121Boolean CFBurstTrieInsertCharactersWithWeight(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, CFIndex weight, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
122
123CF_EXPORT
124Boolean CFBurstTrieAddCharactersWithWeight(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, uint32_t weight, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
125
126
127CF_EXPORT
128Boolean CFBurstTrieInsertUTF8StringWithWeight(CFBurstTrieRef trie, UInt8 *chars, CFIndex numChars, CFIndex weight, CFIndex payload) CF_AVAILABLE(10_7, 4_2);
129
130CF_EXPORT
131Boolean CFBurstTrieAddUTF8StringWithWeight(CFBurstTrieRef trie, UInt8 *chars, CFIndex numChars, uint32_t weight, uint32_t payload) CF_AVAILABLE(10_7, 5_0);
132
133
134CF_EXPORT
135Boolean CFBurstTrieFind(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, CFIndex *payload) CF_AVAILABLE(10_7, 4_2);
136
137CF_EXPORT
138Boolean CFBurstTrieContains(CFBurstTrieRef trie, CFStringRef term, CFRange termRange, uint32_t *payload) CF_AVAILABLE(10_7, 5_0);
139
140
141CF_EXPORT
142Boolean CFBurstTrieFindCharacters(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, CFIndex *payload) CF_AVAILABLE(10_7, 4_2);
143
144CF_EXPORT
145Boolean CFBurstTrieContainsCharacters(CFBurstTrieRef trie, UniChar *chars, CFIndex numChars, uint32_t *payload) CF_AVAILABLE(10_7, 5_0);
146
147
148CF_EXPORT
149Boolean CFBurstTrieFindUTF8String(CFBurstTrieRef trie, UInt8 *key, CFIndex length, CFIndex *payload) CF_AVAILABLE(10_7, 4_2);
150
151CF_EXPORT
152Boolean CFBurstTrieContainsUTF8String(CFBurstTrieRef trie, UInt8 *key, CFIndex length, uint32_t *payload) CF_AVAILABLE(10_7, 5_0);
153
154
155CF_EXPORT
156Boolean CFBurstTrieSerialize(CFBurstTrieRef trie, CFStringRef path, CFBurstTrieOpts opts) CF_AVAILABLE(10_7, 4_2);
157
158CF_EXPORT
159Boolean CFBurstTrieSerializeWithFileDescriptor(CFBurstTrieRef trie, int fd, CFBurstTrieOpts opts) CF_AVAILABLE(10_7, 4_2);
160
161CF_EXPORT
162void CFBurstTrieTraverse(CFBurstTrieRef trie, void *ctx, void (*callback)(void*, const UInt8*, uint32_t, uint32_t)) CF_AVAILABLE(10_7, 4_2);
163
164CF_EXPORT
165CFIndex CFBurstTrieGetCount(CFBurstTrieRef trie) CF_AVAILABLE(10_7, 4_2);
166
167CF_EXPORT
168CFBurstTrieRef CFBurstTrieRetain(CFBurstTrieRef trie) CF_AVAILABLE(10_7, 4_2);
169
170CF_EXPORT
171void CFBurstTrieRelease(CFBurstTrieRef trie) CF_AVAILABLE(10_7, 4_2);
172
173CF_EXPORT
174CFBurstTrieCursorRef CFBurstTrieCreateCursorForBytes(CFBurstTrieRef trie, const UInt8* bytes, CFIndex length) CF_AVAILABLE(10_8, 6_0);
175
176CF_EXPORT
177CFBurstTrieCursorRef CFBurstTrieCursorCreateByCopy(CFBurstTrieCursorRef cursor) CF_AVAILABLE(10_8, 6_0);
178
179CF_EXPORT
180Boolean CFBurstTrieSetCursorForBytes(CFBurstTrieRef trie, CFBurstTrieCursorRef cursor, const UInt8* bytes, CFIndex length) CF_AVAILABLE(10_8, 6_0);
181
182CF_EXPORT
183Boolean CFBurstTrieCursorIsEqual(CFBurstTrieCursorRef lhs, CFBurstTrieCursorRef rhs) CF_AVAILABLE(10_8, 6_0);
184
185CF_EXPORT
186Boolean CFBurstTrieCursorAdvanceForBytes(CFBurstTrieCursorRef cursor, const UInt8* bytes, CFIndex length) CF_AVAILABLE(10_8, 6_0);
187
188CF_EXPORT
189Boolean CFBurstTrieCursorGetPayload(CFBurstTrieCursorRef cursor, uint32_t *payload) CF_AVAILABLE(10_8, 6_0);
190
191CF_EXPORT
192void CFBurstTrieTraverseFromCursor(CFBurstTrieCursorRef cursor, void *ctx, CFBurstTrieTraversalCallback callback) CF_AVAILABLE(10_8, 6_0);
193
194CF_EXPORT
195void CFBurstTrieCursorRelease(CFBurstTrieCursorRef cursor) CF_AVAILABLE(10_8, 6_0);
196
197CF_EXTERN_C_END
198
199#endif /* __COREFOUNDATION_CFBURSTTRIE__ */
200