feat: add null checks & comments to all commmon C bindings (#91)

Author: cwaldren-ld

libs/common/include/launchdarkly/bindings/c/array_builder.h

@@ -34,8 +34,9 @@ LD_EXPORT(void) LDArrayBuilder_Free(LDArrayBuilder array_builder);
  * After calling this method the provider LDValue is consumed. It should not
  * be accessed, and the caller doesn't need to call LDValue_Free.
  *
- * @param array_builder The array builder to add the value to.
- * @param val The value to add.
+ * @param array_builder The array builder to add the value to.  Must not be
+ * NULL.
+ * @param val The value to add. Must not be NULL.
  */
 LD_EXPORT(void) LDArrayBuilder_Add(LDArrayBuilder array_builder, LDValue val);
 
@@ -45,8 +46,9 @@ LD_EXPORT(void) LDArrayBuilder_Add(LDArrayBuilder array_builder, LDValue val);
  * After calling this method the array builder is consumed. It should not be
  * used and the caller does not need to call LDArrayBuilder_Free.
  *
- * @param array_builder The array builder to build an LDValue from.
- * @return The built LDValue.
+ * @param array_builder The array builder to build an LDValue from. Must not be
+ * NULL.
+ * @return The built LDValue. Must not be NULL.
  */
 LD_EXPORT(LDValue) LDArrayBuilder_Build(LDArrayBuilder array_builder);
 

libs/common/include/launchdarkly/bindings/c/context.h

@@ -19,7 +19,7 @@ typedef struct _LDContext_PrivateAttributesIter*
 /**
  * Check if the context is valid.
  *
- * @param context The context to check.
+ * @param context The context to check. Must not be NULL.
  * @return True if the context is valid.
  */
 LD_EXPORT(bool) LDContext_Valid(LDContext context);
@@ -40,10 +40,12 @@ LD_EXPORT(void) LDContext_Free(LDContext context);
  * Do not access a returned LDValue from a context after the context has been
  * freed.
  *
- * @param context The context to get an attribute from
- * @param kind The kind within the context to get the attribute from.
- * @param ref An attribute reference representing the attribute to get.
- * @return The attribute value or a null pointer.
+ * @param context The context to get an attribute from. Must not be NULL.
+ * @param kind The kind within the context to get the attribute from. Must not
+ * be NULL.
+ * @param ref An attribute reference representing the attribute to get. Must not
+ * be NULL.
+ * @return The attribute value or a NULL pointer.
  */
 LD_EXPORT(LDValue)
 LDContext_Get(LDContext context, char const* kind, char const* ref);
@@ -54,7 +56,7 @@ LDContext_Get(LDContext context, char const* kind, char const* ref);
  *
  * The lifetime of the returned string is tied to the LDContext.
  *
- * @param context The context to check for validity.
+ * @param context The context to check for validity. Must not be NULL.
  * @return A string explaining why the context is not valid.
  */
 LD_EXPORT(char const*) LDContext_Errors(LDContext context);
@@ -64,38 +66,38 @@ LD_EXPORT(char const*) LDContext_Errors(LDContext context);
  * context kind. If there is no such context kind, then a null pointer will
  * be returned.
  *
- * The iterator must be destroyed with LDContext_DestroyPrivateAttributesIter.
+ * The iterator must be destroyed with LDContext_PrivateAttributesIter_Free.
  *
  * An iterator must not be used after the associated Context has been
  * freed.
  *
- * @param context The context containing the kind.
- * @param kind The kind to iterate private attributes for.
+ * @param context The context containing the kind. Must not be NULL.
+ * @param kind The kind to iterate private attributes for. Must not be NULL.
  * @return A private attributes iterator.
  */
 LD_EXPORT(LDContext_PrivateAttributesIter)
-LDContext_CreatePrivateAttributesIter(LDContext context, char const* kind);
+LDContext_PrivateAttributesIter_New(LDContext context, char const* kind);
 
 /**
  * Destroy the iterator.
  *
  * @param iter The iterator to destroy.
  */
 LD_EXPORT(void)
-LDContext_DestroyPrivateAttributesIter(LDContext_PrivateAttributesIter iter);
+LDContext_PrivateAttributesIter_Free(LDContext_PrivateAttributesIter iter);
 
 /**
  * Move the iterator to the next item.
  *
- * @param iter The iterator to increment.
+ * @param iter The iterator to increment. Must not be NULL.
  */
 LD_EXPORT(void)
 LDContext_PrivateAttributesIter_Next(LDContext_PrivateAttributesIter iter);
 
 /**
  * Check if the iterator is at the end.
  *
- * @param iter The iterator to check.
+ * @param iter The iterator to check. Must not be NULL.
  * @return True if the iterator is at the end.
  */
 LD_EXPORT(bool)
@@ -106,7 +108,7 @@ LDContext_PrivateAttributesIter_End(LDContext_PrivateAttributesIter iter);
  *
  * The lifetime of the returned value is the same as the Context.
  *
- * @param iter The iterator to get a value for.
+ * @param iter The iterator to get a value for. Must not be NULL.
  * @return The attribute reference as a string.
  */
 LD_EXPORT(char const*)

libs/common/include/launchdarkly/bindings/c/context_builder.h

@@ -41,7 +41,7 @@ LD_EXPORT(void) LDContextBuilder_Free(LDContextBuilder builder);
  * When building a context using LDContextBuilder_Build the builder will be
  * consumed and you do not need to call LDContextBuilder_Free.
  *
- * @param builder The builder to build a context from.
+ * @param builder The builder to build a context from. Must not be NULL.
  * @return The built context.
  */
 LD_EXPORT(LDContext) LDContextBuilder_Build(LDContextBuilder builder);
@@ -58,9 +58,9 @@ LD_EXPORT(LDContext) LDContextBuilder_Build(LDContextBuilder builder);
  * If you call LDContextBuilder_AddKind a second time, with an already specified
  * kind, but a different key, then the key for that kind will be updated.
  *
- * @param builder The builder to add the kind to.
- * @param kind The kind to add.
- * @param key The key for that kind.
+ * @param builder The builder to add the kind to. Must not be NULL.
+ * @param kind The kind to add. Must not be NULL.
+ * @param key The key for that kind. Must not be NULL.
  */
 LD_EXPORT(void)
 LDContextBuilder_AddKind(LDContextBuilder builder,
@@ -74,9 +74,9 @@ LDContextBuilder_AddKind(LDContextBuilder builder,
  * You should not access the value after adding it to the builder, and you
  * do not need to call LDValue_Free on the value.
  *
- * @param kind The kind to add the attribute to.
- * @param attr_key The key of the attribute to add.
- * @param val The value of the attribute to add.
+ * @param kind The kind to add the attribute to. Must not be NULL.
+ * @param attr_key The key of the attribute to add. Must not be NULL.
+ * @param val The value of the attribute to add. Must not be NULL.
  */
 LD_EXPORT(bool)
 LDContextBuilder_Attributes_Set(LDContextBuilder builder,
@@ -99,9 +99,9 @@ LDContextBuilder_Attributes_Set(LDContextBuilder builder,
  * convenience which also adds the attribute to the private attributes list,
  * as if using LDContextBuilder_Attributes_AddPrivateAttribute.
  *
- * @param kind The kind to set the private attribute for.
- * @param attr_key The key of the private attribute.
- * @param val The value of the private attribute.
+ * @param kind The kind to set the private attribute for. Must not be NULL.
+ * @param attr_key The key of the private attribute. Must not be NULL.
+ * @param val The value of the private attribute. Must not be NULL.
  */
 LD_EXPORT(bool)
 LDContextBuilder_Attributes_SetPrivate(LDContextBuilder builder,
@@ -117,8 +117,8 @@ LDContextBuilder_Attributes_SetPrivate(LDContextBuilder builder,
  * This method will make a copy of the name string, and the caller remains
  * responsible for the original name string.
  *
- * @param kind The kind to set the name for.
- * @param name The name to set.
+ * @param kind The kind to set the name for. Must not be NULL.
+ * @param name The name to set. Must not be NULL.
  */
 LD_EXPORT(bool)
 LDContextBuilder_Attributes_SetName(LDContextBuilder builder,
@@ -131,7 +131,7 @@ LDContextBuilder_Attributes_SetName(LDContextBuilder builder,
  * If true, the context will _not_ appear on the Contexts page in the
  * LaunchDarkly dashboard.
  *
- * @param kind The kind to set the anonymous attribute for.
+ * @param kind The kind to set the anonymous attribute for. Must not be NULL.
  * @param anonymous The value to set the anonymous attribute to.
  */
 LD_EXPORT(bool)
@@ -182,8 +182,8 @@ LDContextBuilder_Attributes_SetAnonymous(LDContextBuilder builder,
  * This method will make a copy of the attr_ref string, and the caller remains
  * responsible for the original name string.
  *
- * @param kind The kind to set the attribute as private for.
- * @param attr_ref An attribute reference.
+ * @param kind The kind to set the attribute as private for. Must not be NULL.
+ * @param attr_ref An attribute reference. Must not be NULL.
  */
 LD_EXPORT(bool)
 LDContextBuilder_Attributes_AddPrivateAttribute(LDContextBuilder builder,

libs/common/include/launchdarkly/bindings/c/object_builder.h

@@ -2,8 +2,8 @@
 
 #pragma once
 
-#include <launchdarkly/bindings/c/value.h>
 #include <launchdarkly/bindings/c/export.h>
+#include <launchdarkly/bindings/c/value.h>
 
 #ifdef __cplusplus
 extern "C" {  // only need to export C interface if
@@ -36,8 +36,8 @@ LD_EXPORT(void) LDObjectBuilder_Free(LDObjectBuilder builder);
  * be copied.
  *
  * @param array_builder The object builder to add the value to.
- * @param key The key for the value being added.
- * @param val The value to add.
+ * @param key The key for the value being added. Must not be NULL.
+ * @param val The value to add. Must not be NULL.
  */
 LD_EXPORT(void)
 LDObjectBuilder_Add(LDObjectBuilder builder, char const* key, LDValue val);
@@ -48,7 +48,7 @@ LDObjectBuilder_Add(LDObjectBuilder builder, char const* key, LDValue val);
  * After calling this method the object builder is consumed. It should not be
  * used and the caller does not need to call LDObjectBuilder_Free.
  *
- * @param builder The object builder to build an LDValue from.
+ * @param builder The object builder to build an LDValue from. Must not be NULL.
  * @return The built LDValue.
  */
 LD_EXPORT(LDValue) LDObjectBuilder_Build(LDObjectBuilder builder);

libs/common/include/launchdarkly/bindings/c/value.h

@@ -109,7 +109,7 @@ LD_EXPORT(LDValue) LDValue_NewNumber(double val);
  * The input string will be copied. To avoid the copy, see
  * LDValue_ConstantString.
  *
- * @param val Constant reference to a string. The string is copied. Cannot be
+ * @param val Constant reference to a string. The string is copied. Must not be
  * NULL.
  * @return New LDValue.
  */
@@ -118,7 +118,7 @@ LD_EXPORT(LDValue) LDValue_NewString(char const* val);
 /**
  * Allocates an LDValue by cloning an existing LDValue.
  *
- * @param source Source LDValue. Must not be `NULL`.
+ * @param source Source LDValue. Must not be NULL.
  * @return New LDValue.
  */
 LD_EXPORT(LDValue) LDValue_NewValue(LDValue val);
@@ -129,13 +129,13 @@ LD_EXPORT(LDValue) LDValue_NewValue(LDValue val);
  * An LDValue should only be freed when directly owned by the caller, i.e.,
  * it was never moved into an LDArray or LDObject.
  *
- * @param value LDValue to free. No-op if NULL.
+ * @param value LDValue to free.
  */
 LD_EXPORT(void) LDValue_Free(LDValue val);
 
 /**
  * Returns the type of an LDValue.
- * @param value LDValue to inspect. Cannot be NULL.
+ * @param value LDValue to inspect. Must not be NULL.
  * @return Type of the LDValue, or LDValueType_Unrecognized if the type is
  * unrecognized.
  */
@@ -144,14 +144,14 @@ LD_EXPORT(enum LDValueType) LDValue_Type(LDValue val);
 /**
  * Obtain value of a boolean-type LDValue, otherwise returns LDBooleanFalse.
  *
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return Boolean value, or false if not boolean-type.
  */
 LD_EXPORT(bool) LDValue_GetBool(LDValue val);
 
 /**
  * Obtain value of a number-type LDValue, otherwise return 0.
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return Number value, or 0 if not number-type.
  */
 LD_EXPORT(double) LDValue_GetNumber(LDValue val);
@@ -162,7 +162,7 @@ LD_EXPORT(double) LDValue_GetNumber(LDValue val);
  * the LDValue. If you need the string outside this lifetime, then a copy
  * should be made.
  *
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return String value, or empty string if not string-type.
  */
 LD_EXPORT(char const*) LDValue_GetString(LDValue val);
@@ -173,7 +173,7 @@ LD_EXPORT(char const*) LDValue_GetString(LDValue val);
  *
  * If not an array-type or object-type, returns 0.
  *
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return Count of LDValue elements, or 0 if not array-type/object-type.
  */
 LD_EXPORT(unsigned int) LDValue_Count(LDValue val);
@@ -183,7 +183,7 @@ LD_EXPORT(unsigned int) LDValue_Count(LDValue val);
  *
  * The iterator starts at the first element.
  *
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return Iterator, or NULL if not an array-type. The iterator
  * must should be destroyed with LDValue_DestroyArrayIter.
  */
@@ -193,22 +193,22 @@ LD_EXPORT(LDValue_ArrayIter) LDValue_CreateArrayIter(LDValue val);
  * Move the array-type iterator to the next item. Should only be done for an
  * iterator which is not at the end.
  *
- * @param iter The iterator to advance.
+ * @param iter The iterator to advance. Must not be NULL.
  */
 LD_EXPORT(void) LDValue_ArrayIter_Next(LDValue_ArrayIter iter);
 
 /**
  * Check if an array-type iterator is at the end.
  *
- * @param iter The iterator to check.
+ * @param iter The iterator to check. Must not be NULL.
  * @return True if the iterator is at the end.
  */
 LD_EXPORT(bool) LDValue_ArrayIter_End(LDValue_ArrayIter iter);
 
 /**
  * Get the value for the array-type iterator.
  *
- * @param iter The iterator to get a value for.
+ * @param iter The iterator to get a value for. Must not be NULL.
  * @return The value.
  */
 LD_EXPORT(LDValue) LdValue_ArrayIter_Value(LDValue_ArrayIter iter);
@@ -224,7 +224,7 @@ LD_EXPORT(void) LDValue_DestroyArrayIter(LDValue_ArrayIter iter);
  *
  * The iterator starts at the first element.
  *
- * @param value Target LDValue. Cannot be NULL.
+ * @param value Target LDValue. Must not be NULL.
  * @return Iterator, or NULL if not an object-type. The iterator
  * must should be destroyed with LDValue_DestroyObjectIter.
  */
@@ -234,22 +234,22 @@ LD_EXPORT(LDValue_ObjectIter) LDValue_CreateObjectIter(LDValue val);
  * Move the object-type iterator to the next item. Should only be done for an
  * iterator which is not at the end.
  *
- * @param iter The iterator to advance.
+ * @param iter The iterator to advance. Must not be NULL.
  */
 LD_EXPORT(void) LDValue_ObjectIter_Next(LDValue_ObjectIter iter);
 
 /**
  * Check if an object-type iterator is at the end.
  *
- * @param iter The iterator to check.
+ * @param iter The iterator to check. Must not be NULL.
  * @return True if the iterator is at the end.
  */
 LD_EXPORT(bool) LDValue_ObjectIter_End(LDValue_ObjectIter iter);
 
 /**
  * Get the value for an object-type iterator.
  *
- * @param iter The iterator to get a value for.
+ * @param iter The iterator to get a value for. Must not be NULL.
  * @return The value.
  */
 LD_EXPORT(LDValue) LdValue_ObjectIter_Value(LDValue_ObjectIter iter);
@@ -259,7 +259,7 @@ LD_EXPORT(LDValue) LdValue_ObjectIter_Value(LDValue_ObjectIter iter);
  *
  * The returned key has a lifetime attached to that of the LDValue.
  *
- * @param iter The iterator to get a key for.
+ * @param iter The iterator to get a key for. Must not be NULL.
  * @return The key.
  */
 LD_EXPORT(char const*) LdValue_ObjectIter_Key(LDValue_ObjectIter iter);

libs/common/src/bindings/c/array_builder.cpp

@@ -3,6 +3,7 @@
 
 #include <launchdarkly/bindings/c/array_builder.h>
 #include <launchdarkly/value.hpp>
+#include "../../c_binding_helpers.hpp"
 
 #include <vector>
 
@@ -21,12 +22,17 @@ LD_EXPORT(void) LDArrayBuilder_Free(LDArrayBuilder array_builder) {
 }
 
 LD_EXPORT(void) LDArrayBuilder_Add(LDArrayBuilder array_builder, LDValue val) {
+    LD_ASSERT_NOT_NULL(array_builder);
+    LD_ASSERT_NOT_NULL(val);
+
     auto vector = AS_VECTOR(array_builder);
     vector->emplace_back(std::move(*AS_VALUE(val)));
     LDValue_Free(val);
 }
 
 LD_EXPORT(LDValue) LDArrayBuilder_Build(LDArrayBuilder array_builder) {
+    LD_ASSERT_NOT_NULL(array_builder);
+    
     auto vector = AS_VECTOR(array_builder);
     auto value = new Value(std::move(*vector));
     delete vector;