From ec688b4723a041044226358bcd4dd6e2da39da49 Mon Sep 17 00:00:00 2001 From: Luca Muscariello Date: Thu, 23 Feb 2017 17:01:02 +0100 Subject: Initial commit: cframework. Longbow and Libparc Change-Id: I90378dbd30da6033b20fb1f829b3b822cf366c59 Signed-off-by: Luca Muscariello --- libparc/parc/algol/parc_BufferDictionary.h | 145 +++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100755 libparc/parc/algol/parc_BufferDictionary.h (limited to 'libparc/parc/algol/parc_BufferDictionary.h') diff --git a/libparc/parc/algol/parc_BufferDictionary.h b/libparc/parc/algol/parc_BufferDictionary.h new file mode 100755 index 00000000..60aa90cb --- /dev/null +++ b/libparc/parc/algol/parc_BufferDictionary.h @@ -0,0 +1,145 @@ +/* + * 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_BufferDictionary.h + * @ingroup datastructures + * @brief A key/value dictionary built around PARCBuffer as the Key and the Value. + * + * The key/value dictionary models the Java MAP interface. It is built around Put, Get, and Remove. + * The dictionary stores references to the Key and Value, so the caller may destroy its references + * if no longer needed. + * + */ +#ifndef libparc_parc_BufferDictionary_h +#define libparc_parc_BufferDictionary_h + +typedef struct parc_buffer_dictionary PARCBufferDictionary; + +#include + + +/** + * Creates an empty dictionary. You must use {@link parcBufferDictionary_Release} to destroy it. + * + * @return A pointer to the new `PARCBufferDictionary` + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBufferDictionary *parcBufferDictionary_Create(void); + +/** + * Increase the number of references to a `PARCBufferDictionary`. + * + * Note that a new `PARCBufferDictionary` is not created, + * only that the given `PARCBufferDictionary` reference count is incremented. + * Discard the reference by invoking {@link parcBufferDictionary_Release}. + * + * @param [in] dictionary is a pointer to a `PARCBufferDictionary` instance + * @return The pointer to the @p dictionary instance. + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBufferDictionary *parcBufferDictionary_Acquire(const PARCBufferDictionary *dictionary); + +/** + * Release a `PARCBufferDictionary` reference. + * + * Only the last invocation where the reference count is decremented to zero, + * will actually destroy the `PARCBufferDictionary`. + * + * @param [in,out] dictionaryPtr is a pointer to the `PARCBufferDictionary` reference. + * + * Example: + * @code + * <#example#> + * @endcode + */ +void parcBufferDictionary_Release(PARCBufferDictionary **dictionaryPtr); + +/** + * Add a key/value to the dictionary, returns previous value or NULL + * + * The Dictionary will store a reference (PARCBuffer::aquire) to the key and to the value. + * The Key and Value must be non-NULL. If a previous entry for the key is in the dictionary, + * the previous value is returned. THE CALLER MUST USE {@link parcBuffer_Release} on the returned + * value if it is non-NULL; + * + * @param [in,out] dictionary The dictionary to modify + * @param [in] key The dictionary key + * @param [in] value The value for the key + * + * @return NULL The inserted key is unique + * @return non-NULL Returns the previous value of the key, must use {@link parcBuffer_Release} + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBuffer *parcBufferDictionary_Put(PARCBufferDictionary *dictionary, PARCBuffer *key, PARCBuffer *value); + +/** + * Returns the value associated with the key, or NULL if does not exist + * + * The returned value is what's stored in the dictionary in a `PARCBuffer` instance. If the user wishes to keep the + * value beyond the current calling scope, she should use {@link parcBuffer_Acquire} on the + * returned value. + * + * @param [in] dictionary The dictionary to query + * @param [in] key The dictionary key + * + * @return NULL The key is not in the dictionary + * @return non-NULL Returns the current value of the key, DO NOT use {@link parcBuffer_Release} + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCBuffer *parcBufferDictionary_Get(PARCBufferDictionary *dictionary, PARCBuffer *key); + +/** + * Removes a key from the dictionary, returning the current value or NULL. The caller MUST + * call {@link parcBuffer_Release} on the returned value. + * + * @param [in,out] dictionary The dictionary to modify + * @param [in] key The dictionary key + * + * @return NULL The inserted key is not in the dictionary + * @return non-NULL Returns the current value of the key, DO NOT use {@link parcBuffer_Release} + * + * Example: + * @code + * { + * uint8_t phone[] = "6505551212"; + * PARCBufferDictionary *dict = parcBufferDictionary_Create(); + * + * parcBuffer *key = parcBuffer_Wrap(phone, sizeof(phone), 0); + * parcBuffer_Release(parcBufferDictionary_Remove(dict, key)); + * + * parcBuffer_Release(&key); + * parcBufferDictionary_Destroy(&dict); + * } + * @endcode + */ +PARCBuffer *parcBufferDictionary_Remove(PARCBufferDictionary *dictionary, PARCBuffer *key); +#endif // libparc_parc_BufferDictionary_h -- cgit 1.2.3-korg