diff options
Diffstat (limited to 'libparc/parc/algol/parc_BitVector.h')
-rwxr-xr-x | libparc/parc/algol/parc_BitVector.h | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_BitVector.h b/libparc/parc/algol/parc_BitVector.h new file mode 100755 index 00000000..7e72ac70 --- /dev/null +++ b/libparc/parc/algol/parc_BitVector.h @@ -0,0 +1,426 @@ +/* + * 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_BitVector.h + * @ingroup types + * + */ +#ifndef libparc_parc_BitVector_h +#define libparc_parc_BitVector_h + +#include <stdbool.h> + +/** + * @typedef PARCBitVector + * @brief A structure containing private bit vector state data variables + */ +struct PARCBitVector; +typedef struct PARCBitVector PARCBitVector; + +/** + * Create a new bit vector instance. + * + * @returns NULL on error, pointer to new vector on success. + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_Create(void); + +/** + * Create a copy of a bit vector instance. + * + * @param [in] parcBitVector to duplicate + * @returns NULL on error, pointer to new copy on success. + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * PARCBitVector *copy = parcBitVector_Copy(parcBitVector); + * assertTrue(parcBitVector_Equals(parcBitVector, copy), "Duplicate vector is unequal"); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_Copy(const PARCBitVector *parcBitVector); + +/** + * Obtain a reference to a bit vector instance. + * + * @param [in] parcBitVector to obtain reference to + * @returns pointer to BitVector + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * PARCBitVector *reference = parcBitVector_Acquire(parcBitVector); + * parcBitVector_Release(&reference); + * parcBitVector_Release(&parcBitVector); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_Acquire(const PARCBitVector *parcBitVector); + +/** + * Release a reference to a bit vector instance. + * + * @param [in] parcBitVector to release reference to + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * PARCBitVector *reference = parcBitVector_Acquire(parcBitVector); + * parcBitVector_Release(&reference); + * parcBitVector_Release(&parcBitVector); + * } + * @endcode + * + */ +void parcBitVector_Release(PARCBitVector **parcBitVector); + +/** + * Determine equality of a pair of bit vectors + * + * @param [in] a bit vector to compare + * @param [in] b bit vector to compare + * @returns true if equal, false if unequal + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * PARCBitVector *copy = parcBitVector_Copy(parcBitVector); + * parcBitVector_Set(copy, 1); + * assertTrue(parcBitVector_Equals(parcBitVector, copy) == false, "Vector should have been unequal"); + * } + * @endcode + * + */ +bool parcBitVector_Equals(const PARCBitVector *a, const PARCBitVector *b); + + +/** + * Determine equality of a pair of bit vectors + * + * @param [in] parcBitVector bit vector to search + * @param [in] testVector bit vector to test + * @returns true if parcBitVector contains all bits in testVector, false otherwise + * + * Example: + * @code + * { + * PARCBitVector *superSet = parcBitVector_Create(); + * parcBitVector_Set(superSet, 10); + * parcBitVector_Set(superSet, 11); + * PARCBitVector *subSet = parcBitVector_Create(); + * parcBitVector_Set(subSet, 10); + * assertTrue(parcBitVector_Contains(superSet, subSet), "Expect superSet to contain subSet"); + * } + * @endcode + * + */ +bool parcBitVector_Contains(const PARCBitVector *parcBitVector, const PARCBitVector *testVector); + +/** + * Get the current value of a bit in a vector + * + * @param [in] parcBitVector to obtain value from + * @param [in] bit in vector to get value of + * @returns value of bit in vector, 1 or 0 + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 1, "Vector should have been set"); + * } + * @endcode + * + */ +int parcBitVector_Get(const PARCBitVector *parcBitVector, unsigned bit); + +/** + * Set a bit in a vector + * + * @param [in] parcBitVector to set bit in + * @param [in] bit in vector to set + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 1, "Vector should have been set"); + * } + * @endcode + * + */ +void parcBitVector_Set(PARCBitVector *parcBitVector, unsigned bit); + +/** + * Right shift a vector contents + * + * @param [in] parcBitVector + * @param [in] rightShift count + * @param [out] input vector + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 0); + * + * parcBitVector_RightShift(parcBitVector, 1); + * assertTrue(parcBitVector_FirstBitSet(parcBitVector) == 1, + * "First vector element should have moved up"); + * + * parcBitVector_Release(&parcBitVector); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_RightShift(PARCBitVector *parcBitVector, size_t rightShift); + +/** + * Left shift a vector contents + * + * @param [in] parcBitVector + * @param [in] leftShift count + * @param [out] input vector + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * parcBitVector_Set(parcBitVector, 0); + * + * parcBitVector_LeftShift(parcBitVector, 1); + * assertTrue(parcBitVector_NumberOfBitsSet(parcBitVector) == 1, + * "First vector element should have rolled off"); + * + * parcBitVector_Release(&parcBitVector); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_LeftShift(PARCBitVector *parcBitVector, size_t leftShift); + +/** + * Logical And of a vector contents with another vector + * + * @param [in] a vector + * @param [in] b vector + * @param [out] allocated vector with result of And operation + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * PARCBitVector *andVector = parcBitVector_Create(); + * parcBitVector_Set(andVector, 11); + * + * PARCBitVector *result = parcBitVector_And(parcBitVector, andVector); + * assertTrue(parcBitVector_NumberOfBitsSet(result) == 0, "Vector should have been empty"); + * + * parcBitVector_Release(&parcBitVector); + * parcBitVector_Release(&andVector); + * parcBitVector_Release(&result); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_And(const PARCBitVector *a, const PARCBitVector *b); + +/** + * Logical Or of a vector contents with another vector + * + * @param [in] a vector + * @param [in] b vector + * @param [out] allocated vector with result of Or operation + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * PARCBitVector *orVector = parcBitVector_Create(); + * parcBitVector_Set(orVector, 11); + * + * PARCBitVector *result = parcBitVector_Or(parcBitVector, orVector); + * assertTrue(parcBitVector_NumberOfBitsSet(result) == 2, "Vector should have been set"); + * + * parcBitVector_Release(&parcBitVector); + * parcBitVector_Release(&orVector); + * parcBitVector_Release(&result); + * } + * @endcode + * + */ +PARCBitVector *parcBitVector_Or(const PARCBitVector *a, const PARCBitVector *b); + +/** + * Set a vector of bits in a vector + * + * @param [in] parcBitVector to set bits in + * @param [in] bitsToSet vector of bits to set + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * PARCBitVector *bitsToSet = parcBitVector_Create(); + * parcBitVector_Set(bitsToSet, 10); + * parcBitVector_SetVector(parcBitVector, bitsToSet); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 1, "Vector should have been set"); + * } + * @endcode + * + */ +void parcBitVector_SetVector(PARCBitVector *parcBitVector, const PARCBitVector *bitsToSet); + +/** + * Reset the bits of bit vector to 0 + * + * @param [in] parcBitVector to set bits in + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * parcBitVector_Set(parcBitVector, 42); + * parcBitVector_Reset(parcBitVector); + * assertTrue(parcBitVector_NumberOfBitsSet(parcBitVector) == 0, "Vector should have 0 bits set"); + * } + * @endcode + * + */ +void parcBitVector_Reset(PARCBitVector *parcBitVector); + +/** + * Clear a bit in a vector + * + * @param [in] parcBitVector to clear bit in + * @param [in] bit in vector to clear + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 1, "Vector should have been set"); + * parcBitVector_Clear(parcBitVector, 10); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 0, "Vector should have been cleared"); + * } + * @endcode + * + */ +void parcBitVector_Clear(PARCBitVector *parcBitVector, unsigned bit); + +/** + * Clear a vector of bits in a vector + * + * @param [in] parcBitVector to clear bits in + * @param [in] bitsToClear vector of bits to clear + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * PARCBitVector *bitsToClear = parcBitVector_Create(); + * parcBitVector_Set(bitsToClear, 10); + * parcBitVector_SetVector(parcBitVector, bitsToClear); + * assertTrue(parcBitVector_Get(parcBitVector, 10) == 0, "Vector should have been cleared"); + * } + * @endcode + * + */ +void parcBitVector_ClearVector(PARCBitVector *parcBitVector, const PARCBitVector *bitsToClear); + +/** + * Return number of bits set in a vector + * + * @param [in] parcBitVector to return number of bits set from + * @returns number of bits currently set in bit vector + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * assertTrue(parcBitVector_NumberOfBitsSet(parcBitVector) == 1, "One bit should have been set"); + * } + * @endcode + * + */ +unsigned parcBitVector_NumberOfBitsSet(const PARCBitVector *parcBitVector); + +/** + * Return index if next set bit in vector + * + * @param [in] parcBitVector to inspect + * @param [in] startFrom bit position to start inspection from + * @returns index of next bit set in vector after startFrom or -1 if none + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 10); + * parcBitVector_Set(parcBitVector, 12); + * assertTrue(parcBitVector_NextBitSet(parcBitVector, 0) == 10, "Bit 10 should have been found first"); + * assertTrue(parcBitVector_NextBitSet(parcBitVector, 11) == 12, "Bit 12 should have been found next"); + * } + * @endcode + * + */ +unsigned parcBitVector_NextBitSet(const PARCBitVector *parcBitVector, unsigned startFrom); + +/** + * Return text representation of a bit vector + * + * @param [in] parcBitVector to represent + * @returns allocated character string representing bit vector which must be released by parcMemory_Deallocate + * + * Example: + * @code + * { + * PARCBitVector *parcBitVector = parcBitVector_Create(); + * parcBitVector_Set(parcBitVector, 1); + * const char *bitVectorString = parcBitVector_ToString(parcBitVector); + * printf("Vector contents: %s\n", bitVectorString); + * parcMemory_Deallocate(&bitVectorString); + * } + * @endcode + * + */ +char *parcBitVector_ToString(const PARCBitVector *parcBitVector); +#endif // libparc_parc_BitVector_h |