/*! Sunrise Data Dictionary Library * * @brief a library for hashtable storage of arbitrary data objects * with built-in reference counting and guaranteed order iteration. * * @file dd_sorted_keys.h * alphabetically ordered lists of keys * * @author Benjamin Kowarsch * * @note The author's true email address is herewith specifically excluded * from the license of this software. You are _not permitted_ to make the * author's true email address available to any third party. You may only * pass on the modified version of the email address as presented above. * * (C) 2006 Sunrise Telephone Systems Ltd. All rights reserved. * * @cond LICENSE_TERMS * * 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. * * Under no circumstances is it permitted for any licensee to take credit for * the creation of the Software, to claim authorship or ownership in the * Software or in any other way give the impression that they have created * the Software. Credit to the true authors and copyright holders of the * Software is absolutely mandatory and must be given as follows: * * Software packages incorporating the Software or substantial portions of it * shall display a copyright notice for the Software in the same manner as * they display any other copyright notice; shall display an authorship * notice for the Software in the same manner as they display any other * authorship notice; and shall display the license terms or a reference to * the license terms of the Software in the same manner as they display any * other license or license reference. * * GUI-based or GUI-alike interactive installers installing the Software or * substantial portions of it, shall display the Software's copyright notice, * authorship notice and license terms in full during the installation * process. Other installers such as shell command driven package installers * on Unix systems shall display copyright, authorship and license in the * same manner as for any other software. Installers shall allow users to * install the license file for the Software along with the Software itself. * * Software which makes use of but does not incorporate, nor bundle, nor * install the Software or substantial portions of it, is NOT required to * display any copyright, authorship, license terms or license reference for * the Software. Static linking to the Software constitutes 'incorporating', * dynamic linking to the Software constitutes 'making use 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. * * In countries and territories where the above no-warranty disclaimer is * not permissible by applicable law, the following terms apply: * * NO PERMISSION TO USE THE SOFTWARE IS GRANTED AND THE SOFTWARE MUST NOT BE * USED AT ALL IN SUCH COUNTRIES AND TERRITORIES WHERE THE ABOVE NO-WARRANTY * DISCLAIMER IS NOT PERMISSIBLE AND INVALIDATED BY APPLICABLE LAW. HOWEVER, * THE COPYRIGHT HOLDERS HEREBY WAIVE THEIR RIGHT TO PURSUE OFFENDERS AS LONG * AS THEY OTHERWISE ABIDE BY THE TERMS OF THE LICENSE AS APPLICABLE FOR USE * OF THE SOFTWARE IN COUNTRIES AND TERRITORIES WHERE THE ABOVE NO-WARRANTY * DISCLAIMER IS PERMITTED BY APPLICABLE LAW. THIS WAIVER DOES NOT CONSTITUTE * A LICENSE TO USE THE SOFTWARE IN COUNTRIES AND TERRITORIES WHERE THE ABOVE * NO-WARRANTY DISCLAIMER IS NOT PERMISSIBLE AND INVALIDATED BY APPLICABLE * LAW. ANY LIABILITY OF ANY KIND IS CATEGORICALLY RULED OUT AT ALL TIMES. * * @endcond */ #ifndef _DD_SORTED_KEYS_H #define _DD_SORTED_KEYS_H #include "dd_data_dictionary" // -------------------------------------------------------------------------- // Opaque sorted key list type // -------------------------------------------------------------------------- // // WARNING: Objects of this opaque type should only be accessed through this // public interface. DO NOT EVER attempt to bypass the public interface. // // The internal data structure of this opaque type is HIDDEN and MAY CHANGE // at any time WITHOUT NOTICE. The meaning of some internal pointer fields // may change dynamically at runtime. Accessing this internal data structure // directly other than through the functions in this public interface is // UNSAFE and may result in an inconsistent program state or a crash. typedef void *dd_sorted_keys; // -------------------------------------------------------------------------- // function: dd_new_keylist_from_dictionary(dict) // -------------------------------------------------------------------------- // // Creates and returns a new alphabetically sorted key list from keys stored // in dictionary . // // Returns NULL if dictionary is NULL or empty. dd_sorted_keys dd_new_keylist_from_dictionary(dd_dictionary dict); // -------------------------------------------------------------------------- // function: dd_next_key_in_keylist(keylist) // -------------------------------------------------------------------------- // // Returns a pointer to the next key in keylist and moves the // key list's item pointer to the following key. // // Returns NULL if keylist is invalid or if the end of the list has // been reached. const char *dd_next_key_in_keylist(dd_sorted_keys keylist); // -------------------------------------------------------------------------- // function: dd_reset_keylist(keylist) // -------------------------------------------------------------------------- // // Resets the item pointer of keylist to point to the first item. dd_status dd_reset_keylist(dd_sorted_keys keylist); // -------------------------------------------------------------------------- // function: dd_dispose_keylist(keylist) // -------------------------------------------------------------------------- // // Disposes of keylist . void dd_dispose_keylist(dd_sorted_keys keylist); #endif // END OF FILE