diff options
Diffstat (limited to 'objectivec')
61 files changed, 12050 insertions, 1790 deletions
diff --git a/objectivec/DevTools/compile_testing_protos.sh b/objectivec/DevTools/compile_testing_protos.sh index 82953130..6cc32da9 100755 --- a/objectivec/DevTools/compile_testing_protos.sh +++ b/objectivec/DevTools/compile_testing_protos.sh @@ -1,17 +1,16 @@ -#!/bin/bash - +#!/bin/bash -eu # Invoked by the Xcode projects to build the protos needed for the unittests. -set -eu - readonly OUTPUT_DIR="${PROJECT_DERIVED_FILE_DIR}/protos" +# ----------------------------------------------------------------------------- # Helper for bailing. die() { echo "Error: $1" exit 2 } +# ----------------------------------------------------------------------------- # What to do. case "${ACTION}" in "") @@ -26,12 +25,19 @@ case "${ACTION}" in ;; esac -# Move to the top of the protobuf directories. -cd "${SRCROOT}/.." +# ----------------------------------------------------------------------------- +# Ensure the output dir exists +mkdir -p "${OUTPUT_DIR}/google/protobuf" +# ----------------------------------------------------------------------------- +# Move to the top of the protobuf directories and ensure there is a protoc +# binary to use. +cd "${SRCROOT}/.." [[ -x src/protoc ]] || \ die "Could not find the protoc binary; make sure you have built it (objectivec/DevTools/full_mac_build.sh -h)." +# ----------------------------------------------------------------------------- +# See the compiler or proto files have changed. RUN_PROTOC=no if [[ ! -d "${OUTPUT_DIR}" ]] ; then RUN_PROTOC=yes @@ -50,7 +56,7 @@ else # Find the oldest output file. readonly OldestOutput=$(find \ "${OUTPUT_DIR}" \ - -type f -print0 \ + -type f -name "*pbobjc.[hm]" -print0 \ | xargs -0 stat -f "%m %N" \ | sort -n -r | tail -n1 | cut -f2- -d" ") # If the newest input is newer than the oldest output, regenerate. @@ -64,10 +70,30 @@ if [[ "${RUN_PROTOC}" != "yes" ]] ; then exit 0 fi -# Ensure the output dir exists -mkdir -p "${OUTPUT_DIR}/google/protobuf" +# ----------------------------------------------------------------------------- +# Prune out all the files from previous generations to ensure we only have +# current ones. +find "${OUTPUT_DIR}" \ + -type f -name "*pbobjc.[hm]" -print0 \ + | xargs -0 rm -rf + +# ----------------------------------------------------------------------------- +# Helper to invoke protoc +compile_protos() { + src/protoc \ + --objc_out="${OUTPUT_DIR}/google/protobuf" \ + --proto_path=src/google/protobuf/ \ + --proto_path=src \ + "$@" +} + +# ----------------------------------------------------------------------------- +# Generate most of the proto files that exist in the C++ src tree. Several +# are used in the tests, but the extra don't hurt in that they ensure ObjC +# sources can be generated from them. CORE_PROTO_FILES=( + src/google/protobuf/any_test.proto src/google/protobuf/unittest_arena.proto src/google/protobuf/unittest_custom_options.proto src/google/protobuf/unittest_enormous_descriptor.proto @@ -90,35 +116,32 @@ CORE_PROTO_FILES=( src/google/protobuf/map_lite_unittest.proto src/google/protobuf/map_proto2_unittest.proto src/google/protobuf/map_unittest.proto -) - -# The unittest_custom_options.proto extends the messages in descriptor.proto -# so we build it in to test extending in general. The library doesn't provide -# a descriptor as it doesn't use the classes/enums. -CORE_PROTO_FILES+=( + # The unittest_custom_options.proto extends the messages in descriptor.proto + # so we build it in to test extending in general. The library doesn't provide + # a descriptor as it doesn't use the classes/enums. src/google/protobuf/descriptor.proto ) -compile_proto() { - src/protoc \ - --objc_out="${OUTPUT_DIR}/google/protobuf" \ - --proto_path=src/google/protobuf/ \ - --proto_path=src \ - $* -} - +# Note: there is overlap in package.Message names between some of the test +# files, so they can't be generated all at once. This works because the overlap +# isn't linked into a single binary. for a_proto in "${CORE_PROTO_FILES[@]}" ; do - compile_proto "${a_proto}" + compile_protos "${a_proto}" done -OBJC_PROTO_FILES=( - objectivec/Tests/unittest_cycle.proto - objectivec/Tests/unittest_runtime_proto2.proto - objectivec/Tests/unittest_runtime_proto3.proto - objectivec/Tests/unittest_objc.proto +# ----------------------------------------------------------------------------- +# Generate the Objective C specific testing protos. +compile_protos \ + --proto_path="objectivec/Tests" \ + objectivec/Tests/unittest_cycle.proto \ + objectivec/Tests/unittest_extension_chain_a.proto \ + objectivec/Tests/unittest_extension_chain_b.proto \ + objectivec/Tests/unittest_extension_chain_c.proto \ + objectivec/Tests/unittest_extension_chain_d.proto \ + objectivec/Tests/unittest_extension_chain_e.proto \ + objectivec/Tests/unittest_extension_chain_f.proto \ + objectivec/Tests/unittest_extension_chain_g.proto \ + objectivec/Tests/unittest_runtime_proto2.proto \ + objectivec/Tests/unittest_runtime_proto3.proto \ + objectivec/Tests/unittest_objc.proto \ objectivec/Tests/unittest_objc_startup.proto -) - -for a_proto in "${OBJC_PROTO_FILES[@]}" ; do - compile_proto --proto_path="objectivec/Tests" "${a_proto}" -done diff --git a/objectivec/GPBArray.h b/objectivec/GPBArray.h index afda57f3..781cfb6f 100644 --- a/objectivec/GPBArray.h +++ b/objectivec/GPBArray.h @@ -32,11 +32,6 @@ #import "GPBRuntimeTypes.h" -// These classes are used for repeated fields of basic data types. They are used because -// they perform better than boxing into NSNumbers in NSArrays. - -// Note: These are not meant to be subclassed. - NS_ASSUME_NONNULL_BEGIN //%PDDM-EXPAND DECLARE_ARRAYS() @@ -44,39 +39,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Int32 +/** + * Class used for repeated fields of int32_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBInt32Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBInt32Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBInt32Array with value in it. + **/ + (instancetype)arrayWithValue:(int32_t)value; + +/** + * Creates and initializes a GPBInt32Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBInt32Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBInt32Array *)array; + +/** + * Creates and initializes a GPBInt32Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBInt32Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBInt32Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBInt32Array with a copy of the values. + **/ - (instancetype)initWithValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBInt32Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBInt32Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBInt32Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBInt32Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int32_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -84,39 +211,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - UInt32 +/** + * Class used for repeated fields of uint32_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBUInt32Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBUInt32Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBUInt32Array with value in it. + **/ + (instancetype)arrayWithValue:(uint32_t)value; + +/** + * Creates and initializes a GPBUInt32Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBUInt32Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBUInt32Array *)array; + +/** + * Creates and initializes a GPBUInt32Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBUInt32Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBUInt32Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBUInt32Array with a copy of the values. + **/ - (instancetype)initWithValues:(const uint32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBUInt32Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBUInt32Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBUInt32Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (uint32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(uint32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(uint32_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(uint32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const uint32_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBUInt32Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(uint32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(uint32_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -124,39 +383,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Int64 +/** + * Class used for repeated fields of int64_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBInt64Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBInt64Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBInt64Array with value in it. + **/ + (instancetype)arrayWithValue:(int64_t)value; + +/** + * Creates and initializes a GPBInt64Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBInt64Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBInt64Array *)array; + +/** + * Creates and initializes a GPBInt64Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBInt64Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBInt64Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBInt64Array with a copy of the values. + **/ - (instancetype)initWithValues:(const int64_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBInt64Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBInt64Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBInt64Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int64_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int64_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int64_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int64_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int64_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBInt64Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int64_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int64_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -164,39 +555,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - UInt64 +/** + * Class used for repeated fields of uint64_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBUInt64Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBUInt64Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBUInt64Array with value in it. + **/ + (instancetype)arrayWithValue:(uint64_t)value; + +/** + * Creates and initializes a GPBUInt64Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBUInt64Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBUInt64Array *)array; + +/** + * Creates and initializes a GPBUInt64Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBUInt64Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBUInt64Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBUInt64Array with a copy of the values. + **/ - (instancetype)initWithValues:(const uint64_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBUInt64Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBUInt64Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBUInt64Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (uint64_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(uint64_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(uint64_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(uint64_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const uint64_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBUInt64Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(uint64_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(uint64_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -204,39 +727,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Float +/** + * Class used for repeated fields of float values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBFloatArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBFloatArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBFloatArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBFloatArray with value in it. + **/ + (instancetype)arrayWithValue:(float)value; + +/** + * Creates and initializes a GPBFloatArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBFloatArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBFloatArray *)array; + +/** + * Creates and initializes a GPBFloatArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBFloatArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBFloatArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBFloatArray with a copy of the values. + **/ - (instancetype)initWithValues:(const float [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBFloatArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBFloatArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBFloatArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (float)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(float value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(float value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(float)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const float [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBFloatArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(float)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(float)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -244,39 +899,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Double +/** + * Class used for repeated fields of double values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBDoubleArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBDoubleArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBDoubleArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBDoubleArray with value in it. + **/ + (instancetype)arrayWithValue:(double)value; + +/** + * Creates and initializes a GPBDoubleArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBDoubleArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBDoubleArray *)array; + +/** + * Creates and initializes a GPBDoubleArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBDoubleArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBDoubleArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBDoubleArray with a copy of the values. + **/ - (instancetype)initWithValues:(const double [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBDoubleArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBDoubleArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBDoubleArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (double)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(double value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(double value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(double)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const double [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBDoubleArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(double)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(double)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -284,39 +1071,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Bool +/** + * Class used for repeated fields of BOOL values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBBoolArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBBoolArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBBoolArray with value in it. + **/ + (instancetype)arrayWithValue:(BOOL)value; + +/** + * Creates and initializes a GPBBoolArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBBoolArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBBoolArray *)array; + +/** + * Creates and initializes a GPBBoolArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBBoolArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBBoolArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBBoolArray with a copy of the values. + **/ - (instancetype)initWithValues:(const BOOL [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBBoolArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBBoolArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBBoolArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (BOOL)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(BOOL value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(BOOL value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(BOOL)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const BOOL [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBBoolArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(BOOL)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(BOOL)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -324,27 +1243,108 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum +/** + * This class is used for repeated fields of int32_t values. This performs + * better than boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBEnumArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty GPBEnumArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBEnumArray with the enum validation function + * given. + * + * @param func The enum validation function for the array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a GPBEnumArray with the enum validation function + * given and the single raw value given. + * + * @param func The enum validation function for the array. + * @param value The raw value to add to this array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)value; + +/** + * Creates and initializes a GPBEnumArray that adds the elements from the + * given array. + * + * @param array Array containing the values to add to the new array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValueArray:(GPBEnumArray *)array; + +/** + * Creates and initializes a GPBEnumArray with the given enum validation + * function and with the givencapacity. + * + * @param func The enum validation function for the array. + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBEnumArray with a capacity of count. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)count; +/** + * Initializes the array with the given enum validation function. + * + * @param func The enum validation function for the array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. +/** + * Initializes the array, copying the given values. + * + * @param func The enum validation function for the array. + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBEnumArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param func The enum validation function for the array. + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBEnumArray with a capacity of count. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)count; @@ -352,18 +1352,68 @@ NS_ASSUME_NONNULL_BEGIN // valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; // These methods bypass the validationFunc to provide access to values that were not // known at the time the binary was compiled. +/** + * Gets the raw enum value at the given index. + * + * @param index The index of the raw enum value to get. + * + * @return The raw enum value at the given index. + **/ - (int32_t)rawValueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateRawValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateRawValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; @@ -372,29 +1422,114 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int32_t)value; // These methods bypass the validationFunc to provide setting of values that were not // known at the time the binary was compiled. +/** + * Adds a raw enum value to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param value The raw enum value to add to the array. + **/ - (void)addRawValue:(int32_t)value; + +/** + * Adds raw enum values to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param array Array containing the raw enum values to add to this array. + **/ - (void)addRawValuesFromArray:(GPBEnumArray *)array; + +/** + * Adds raw enum values to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param values Array containing the raw enum values to add to this array. + * @param count The number of raw values to add. + **/ - (void)addRawValues:(const int32_t [])values count:(NSUInteger)count; +/** + * Inserts a raw enum value at the given index. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param value Raw enum value to add. + * @param index The index into which to insert the value. + **/ - (void)insertRawValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the raw enum value at the given index with the given value. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param index The index for which to replace the value. + * @param value The raw enum value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withRawValue:(int32_t)value; // No validation applies to these methods. +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -421,20 +1556,82 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE ARRAY_INTERFACE_SIMPLE(NAME, TYPE) //%#pragma mark - NAME //% +//%/** +//% * Class used for repeated fields of ##TYPE## values. This performs better than +//% * boxing into NSNumbers in NSArrays. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface GPB##NAME##Array : NSObject <NSCopying> //% +//%/** The number of elements contained in the array. */ //%@property(nonatomic, readonly) NSUInteger count; //% +//%/** +//% * @return A newly instanced and empty GPB##NAME##Array. +//% **/ //%+ (instancetype)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the single element given. +//% * +//% * @param value The value to be placed in the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with value in it. +//% **/ //%+ (instancetype)arrayWithValue:(TYPE)value; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the contents of the given +//% * array. +//% * +//% * @param array Array with the contents to be put into the new array. +//% * +//% * @return A newly instanced GPB##NAME##Array with the contents of array. +//% **/ //%+ (instancetype)arrayWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the given capacity. +//% * +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with a capacity of count. +//% **/ //%+ (instancetype)arrayWithCapacity:(NSUInteger)count; //% +//%/** +//% * @return A newly initialized and empty GPB##NAME##Array. +//% **/ //%- (instancetype)init NS_DESIGNATED_INITIALIZER; -//%// Initializes the array, copying the values. +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param values An array with the values to put inside this array. +//% * @param count The number of elements to copy into the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValues:(const TYPE [])values //% count:(NSUInteger)count; +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param array An array with the values to put inside this array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Initializes the array with the given capacity. +//% * +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a capacity of count. +//% **/ //%- (instancetype)initWithCapacity:(NSUInteger)count; //% //%ARRAY_IMMUTABLE_INTERFACE(NAME, TYPE, Basic) @@ -451,27 +1648,108 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE ARRAY_INTERFACE_ENUM(NAME, TYPE) //%#pragma mark - NAME //% +//%/** +//% * This class is used for repeated fields of ##TYPE## values. This performs +//% * better than boxing into NSNumbers in NSArrays. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface GPB##NAME##Array : NSObject <NSCopying> //% +//%/** The number of elements contained in the array. */ //%@property(nonatomic, readonly) NSUInteger count; +//%/** The validation function to check if the enums are valid. */ //%@property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; //% +//%/** +//% * @return A newly instanced and empty GPB##NAME##Array. +//% **/ //%+ (instancetype)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the enum validation function +//% * given. +//% * +//% * @param func The enum validation function for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the enum validation function +//% * given and the single raw value given. +//% * +//% * @param func The enum validation function for the array. +//% * @param value The raw value to add to this array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValue:(TYPE)value; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array that adds the elements from the +//% * given array. +//% * +//% * @param array Array containing the values to add to the new array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the given enum validation +//% * function and with the givencapacity. +//% * +//% * @param func The enum validation function for the array. +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with a capacity of count. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)count; //% +//%/** +//% * Initializes the array with the given enum validation function. +//% * +//% * @param func The enum validation function for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% NS_DESIGNATED_INITIALIZER; //% -//%// Initializes the array, copying the values. +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param func The enum validation function for the array. +//% * @param values An array with the values to put inside this array. +//% * @param count The number of elements to copy into the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValues:(const TYPE [])values //% count:(NSUInteger)count; +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param array An array with the values to put inside this array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Initializes the array with the given capacity. +//% * +//% * @param func The enum validation function for the array. +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a capacity of count. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)count; //% @@ -484,9 +1762,34 @@ NS_ASSUME_NONNULL_END //%// These methods bypass the validationFunc to provide access to values that were not //%// known at the time the binary was compiled. //% +//%/** +//% * Gets the raw enum value at the given index. +//% * +//% * @param index The index of the raw enum value to get. +//% * +//% * @return The raw enum value at the given index. +//% **/ //%- (TYPE)rawValueAtIndex:(NSUInteger)index; //% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateRawValuesWithBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; +//% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param opts Options to control the enumeration. +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateRawValuesWithOptions:(NSEnumerationOptions)opts //% usingBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; //% @@ -501,23 +1804,88 @@ NS_ASSUME_NONNULL_END //% //%PDDM-DEFINE ARRAY_IMMUTABLE_INTERFACE(NAME, TYPE, HELPER_NAME) +//%/** +//% * Gets the value at the given index. +//% * +//% * @param index The index of the value to get. +//% * +//% * @return The value at the given index. +//% **/ //%- (TYPE)valueAtIndex:(NSUInteger)index; //% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateValuesWithBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; +//% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param opts Options to control the enumeration. +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts //% usingBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; //%PDDM-DEFINE ARRAY_MUTABLE_INTERFACE(NAME, TYPE, HELPER_NAME) +//%/** +//% * Adds a value to this array. +//% * +//% * @param value The value to add to this array. +//% **/ //%- (void)addValue:(TYPE)value; +//% +//%/** +//% * Adds values to this array. +//% * +//% * @param values The values to add to this array. +//% * @param count The number of elements to add. +//% **/ //%- (void)addValues:(const TYPE [])values count:(NSUInteger)count; +//% //%ARRAY_EXTRA_MUTABLE_METHODS1_##HELPER_NAME(NAME, TYPE) +//%/** +//% * Inserts a value into the given position. +//% * +//% * @param value The value to add to this array. +//% * @param index The index into which to insert the value. +//% **/ //%- (void)insertValue:(TYPE)value atIndex:(NSUInteger)index; //% +//%/** +//% * Replaces the value at the given index with the given value. +//% * +//% * @param index The index for which to replace the value. +//% * @param value The value to replace with. +//% **/ //%- (void)replaceValueAtIndex:(NSUInteger)index withValue:(TYPE)value; //%ARRAY_EXTRA_MUTABLE_METHODS2_##HELPER_NAME(NAME, TYPE) +//%/** +//% * Removes the value at the given index. +//% * +//% * @param index The index of the value to remove. +//% **/ //%- (void)removeValueAtIndex:(NSUInteger)index; +//% +//%/** +//% * Removes all the values from this array. +//% **/ //%- (void)removeAll; //% +//%/** +//% * Exchanges the values between the given indexes. +//% * +//% * @param idx1 The index of the first element to exchange. +//% * @param idx2 The index of the second element to exchange. +//% **/ //%- (void)exchangeValueAtIndex:(NSUInteger)idx1 //% withValueAtIndex:(NSUInteger)idx2; @@ -526,6 +1894,11 @@ NS_ASSUME_NONNULL_END // //%PDDM-DEFINE ARRAY_EXTRA_MUTABLE_METHODS1_Basic(NAME, TYPE) +//%/** +//% * Adds the values from the given array to this array. +//% * +//% * @param array The array containing the elements to add to this array. +//% **/ //%- (void)addValuesFromArray:(GPB##NAME##Array *)array; //% //%PDDM-DEFINE ARRAY_EXTRA_MUTABLE_METHODS2_Basic(NAME, TYPE) @@ -537,12 +1910,57 @@ NS_ASSUME_NONNULL_END //%// These methods bypass the validationFunc to provide setting of values that were not //%// known at the time the binary was compiled. //% +//%/** +//% * Adds a raw enum value to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param value The raw enum value to add to the array. +//% **/ //%- (void)addRawValue:(TYPE)value; +//% +//%/** +//% * Adds raw enum values to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param array Array containing the raw enum values to add to this array. +//% **/ //%- (void)addRawValuesFromArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Adds raw enum values to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param values Array containing the raw enum values to add to this array. +//% * @param count The number of raw values to add. +//% **/ //%- (void)addRawValues:(const TYPE [])values count:(NSUInteger)count; //% +//%/** +//% * Inserts a raw enum value at the given index. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param value Raw enum value to add. +//% * @param index The index into which to insert the value. +//% **/ //%- (void)insertRawValue:(TYPE)value atIndex:(NSUInteger)index; //% +//%/** +//% * Replaces the raw enum value at the given index with the given value. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param index The index for which to replace the value. +//% * @param value The raw enum value to replace with. +//% **/ //%- (void)replaceValueAtIndex:(NSUInteger)index withRawValue:(TYPE)value; //% //%// No validation applies to these methods. diff --git a/objectivec/GPBArray.m b/objectivec/GPBArray.m index 64869bbb..ae57747d 100644 --- a/objectivec/GPBArray.m +++ b/objectivec/GPBArray.m @@ -195,7 +195,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { //%} //% //%- (void)enumerate##ACCESSOR_NAME##ValuesWithBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block { -//% [self enumerate##ACCESSOR_NAME##ValuesWithOptions:0 usingBlock:block]; +//% [self enumerate##ACCESSOR_NAME##ValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; //%} //% //%- (void)enumerate##ACCESSOR_NAME##ValuesWithOptions:(NSEnumerationOptions)opts @@ -406,7 +406,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -654,7 +654,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(uint32_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -902,7 +902,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(int64_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -1150,7 +1150,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(uint64_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -1398,7 +1398,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(float value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -1646,7 +1646,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(double value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -1894,7 +1894,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(BOOL value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts @@ -2166,7 +2166,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateRawValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateRawValuesWithOptions:0 usingBlock:block]; + [self enumerateRawValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateRawValuesWithOptions:(NSEnumerationOptions)opts @@ -2218,7 +2218,7 @@ static BOOL ArrayDefault_IsValidValue(int32_t value) { } - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block { - [self enumerateValuesWithOptions:0 usingBlock:block]; + [self enumerateValuesWithOptions:(NSEnumerationOptions)0 usingBlock:block]; } - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts diff --git a/objectivec/GPBBootstrap.h b/objectivec/GPBBootstrap.h index 4db08e80..7dc943d4 100644 --- a/objectivec/GPBBootstrap.h +++ b/objectivec/GPBBootstrap.h @@ -28,11 +28,13 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// The Objective C runtime has complete enough info that most protos don’t end -// up using this, so leaving it on is no cost or very little cost. If you -// happen to see it causing bloat, this is the way to disable it. If you do -// need to disable it, try only disabling it for Release builds as having -// full TextFormat can be useful for debugging. +/** + * The Objective C runtime has complete enough info that most protos don’t end + * up using this, so leaving it on is no cost or very little cost. If you + * happen to see it causing bloat, this is the way to disable it. If you do + * need to disable it, try only disabling it for Release builds as having + * full TextFormat can be useful for debugging. + **/ #ifndef GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS #define GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS 0 #endif @@ -42,6 +44,7 @@ #if !__has_feature(objc_fixed_enum) #error All supported Xcode versions should support objc_fixed_enum. #endif + // If the headers are imported into Objective-C++, we can run into an issue // where the defintion of NS_ENUM (really CF_ENUM) changes based on the C++ // standard that is in effect. If it isn't C++11 or higher, the definition @@ -53,19 +56,29 @@ #else #define GPB_ENUM(X) NS_ENUM(int32_t, X) #endif -// GPB_ENUM_FWD_DECLARE is used for forward declaring enums, ex: -// GPB_ENUM_FWD_DECLARE(Foo_Enum) -// @property (nonatomic) Foo_Enum value; + +/** + * GPB_ENUM_FWD_DECLARE is used for forward declaring enums, for example: + * + * ``` + * GPB_ENUM_FWD_DECLARE(Foo_Enum) + * @property (nonatomic) Foo_Enum value; + * ``` + **/ #define GPB_ENUM_FWD_DECLARE(X) enum X : int32_t -// Based upon CF_INLINE. Forces inlining in release. +/** + * Based upon CF_INLINE. Forces inlining in non DEBUG builds. + **/ #if !defined(DEBUG) #define GPB_INLINE static __inline__ __attribute__((always_inline)) #else #define GPB_INLINE static __inline__ #endif -// For use in public headers that might need to deal with ARC. +/** + * For use in public headers that might need to deal with ARC. + **/ #ifndef GPB_UNSAFE_UNRETAINED #if __has_feature(objc_arc) #define GPB_UNSAFE_UNRETAINED __unsafe_unretained @@ -76,10 +89,14 @@ // If property name starts with init we need to annotate it to get past ARC. // http://stackoverflow.com/questions/18723226/how-do-i-annotate-an-objective-c-property-with-an-objc-method-family/18723227#18723227 +// +// Meant to be used internally by generated code. #define GPB_METHOD_FAMILY_NONE __attribute__((objc_method_family(none))) // The protoc-gen-objc version which works with the current version of the // generated Objective C sources. In general we don't want to change the // runtime interfaces (or this version) as it means everything has to be // regenerated. -#define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30001 +// +// Meant to be used internally by generated code. +#define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30002 diff --git a/objectivec/GPBCodedInputStream.h b/objectivec/GPBCodedInputStream.h index df9d97ba..de27b186 100644 --- a/objectivec/GPBCodedInputStream.h +++ b/objectivec/GPBCodedInputStream.h @@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN CF_EXTERN_C_BEGIN -/// GPBCodedInputStream exception name. Exceptions raised from -/// GPBCodedInputStream contain an underlying error in the userInfo dictionary -/// under the GPBCodedInputStreamUnderlyingErrorKey key. +/** + * @c GPBCodedInputStream exception name. Exceptions raised from + * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary + * under the GPBCodedInputStreamUnderlyingErrorKey key. + **/ extern NSString *const GPBCodedInputStreamException; -/// The key under which the underlying NSError from the exception is stored. +/** The key under which the underlying NSError from the exception is stored. */ extern NSString *const GPBCodedInputStreamUnderlyingErrorKey; -/// NSError domain used for GPBCodedInputStream errors. +/** NSError domain used for @c GPBCodedInputStream errors. */ extern NSString *const GPBCodedInputStreamErrorDomain; -/// Error code for NSError with GPBCodedInputStreamErrorDomain. +/** + * Error code for NSError with @c GPBCodedInputStreamErrorDomain. + **/ typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) { - /// The size does not fit in the remaining bytes to be read. + /** The size does not fit in the remaining bytes to be read. */ GPBCodedInputStreamErrorInvalidSize = -100, - /// Attempted to read beyond the subsection limit. + /** Attempted to read beyond the subsection limit. */ GPBCodedInputStreamErrorSubsectionLimitReached = -101, - /// The requested subsection limit is invalid. + /** The requested subsection limit is invalid. */ GPBCodedInputStreamErrorInvalidSubsectionLimit = -102, - /// Invalid tag read. + /** Invalid tag read. */ GPBCodedInputStreamErrorInvalidTag = -103, - /// Invalid UTF-8 character in a string. + /** Invalid UTF-8 character in a string. */ GPBCodedInputStreamErrorInvalidUTF8 = -104, - /// Invalid VarInt read. + /** Invalid VarInt read. */ GPBCodedInputStreamErrorInvalidVarInt = -105, - /// The maximum recursion depth of messages was exceeded. + /** The maximum recursion depth of messages was exceeded. */ GPBCodedInputStreamErrorRecursionDepthExceeded = -106, }; CF_EXTERN_C_END -/// Reads and decodes protocol message fields. -/// -/// The common uses of protocol buffers shouldn't need to use this class. -/// @c GPBMessage's provide a @c +parseFromData:error: and @c -/// +parseFromData:extensionRegistry:error: method that will decode a -/// message for you. -/// -/// @note Subclassing of GPBCodedInputStream is NOT supported. +/** + * Reads and decodes protocol message fields. + * + * The common uses of protocol buffers shouldn't need to use this class. + * @c GPBMessage's provide a @c +parseFromData:error: and + * @c +parseFromData:extensionRegistry:error: method that will decode a + * message for you. + * + * @note Subclassing of @c GPBCodedInputStream is NOT supported. + **/ @interface GPBCodedInputStream : NSObject -/// Creates a new stream wrapping some data. +/** + * Creates a new stream wrapping some data. + * + * @param data The data to wrap inside the stream. + * + * @return A newly instanced GPBCodedInputStream. + **/ + (instancetype)streamWithData:(NSData *)data; -/// Initializes a stream wrapping some data. +/** + * Initializes a stream wrapping some data. + * + * @param data The data to wrap inside the stream. + * + * @return A newly initialized GPBCodedInputStream. + **/ - (instancetype)initWithData:(NSData *)data; -/// Attempt to read a field tag, returning zero if we have reached EOF. -/// Protocol message parsers use this to read tags, since a protocol message -/// may legally end wherever a tag occurs, and zero is not a valid tag number. +/** + * Attempts to read a field tag, returning zero if we have reached EOF. + * Protocol message parsers use this to read tags, since a protocol message + * may legally end wherever a tag occurs, and zero is not a valid tag number. + * + * @return The field tag, or zero if EOF was reached. + **/ - (int32_t)readTag; -/// Read and return a double. +/** + * @return A double read from the stream. + **/ - (double)readDouble; -/// Read and return a float. +/** + * @return A float read from the stream. + **/ - (float)readFloat; -/// Read and return a uint64. +/** + * @return A uint64 read from the stream. + **/ - (uint64_t)readUInt64; -/// Read and return a uint32. +/** + * @return A uint32 read from the stream. + **/ - (uint32_t)readUInt32; -/// Read and return an int64. +/** + * @return An int64 read from the stream. + **/ - (int64_t)readInt64; -/// Read and return an int32. +/** + * @return An int32 read from the stream. + **/ - (int32_t)readInt32; -/// Read and return a fixed64. +/** + * @return A fixed64 read from the stream. + **/ - (uint64_t)readFixed64; -/// Read and return a fixed32. +/** + * @return A fixed32 read from the stream. + **/ - (uint32_t)readFixed32; -/// Read and return an enum (int). +/** + * @return An enum read from the stream. + **/ - (int32_t)readEnum; -/// Read and return a sfixed32. +/** + * @return A sfixed32 read from the stream. + **/ - (int32_t)readSFixed32; -/// Read and return a sfixed64. +/** + * @return A fixed64 read from the stream. + **/ - (int64_t)readSFixed64; -/// Read and return a sint32. +/** + * @return A sint32 read from the stream. + **/ - (int32_t)readSInt32; -/// Read and return a sint64. +/** + * @return A sint64 read from the stream. + **/ - (int64_t)readSInt64; -/// Read and return a boolean. +/** + * @return A boolean read from the stream. + **/ - (BOOL)readBool; -/// Read and return a string. +/** + * @return A string read from the stream. + **/ - (NSString *)readString; -/// Read and return length delimited data. +/** + * @return Data read from the stream. + **/ - (NSData *)readBytes; -/// Read an embedded message field value from the stream. -/// -/// @param message The message to set fields on as they are read. -/// @param extensionRegistry An optional extension registry to use to lookup -/// extensions for @c message. +/** + * Read an embedded message field value from the stream. + * + * @param message The message to set fields on as they are read. + * @param extensionRegistry An optional extension registry to use to lookup + * extensions for message. + **/ - (void)readMessage:(GPBMessage *)message extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; -/// Reads and discards a single field, given its tag value. -/// -/// @param tag The tag number of the field to skip. -/// -/// @return NO if the tag is an endgroup tag (in which case nothing is skipped), -/// YES in all other cases. +/** + * Reads and discards a single field, given its tag value. + * + * @param tag The tag number of the field to skip. + * + * @return NO if the tag is an endgroup tag (in which case nothing is skipped), + * YES in all other cases. + **/ - (BOOL)skipField:(int32_t)tag; -/// Reads and discards an entire message. This will read either until EOF -/// or until an endgroup tag, whichever comes first. +/** + * Reads and discards an entire message. This will read either until EOF or + * until an endgroup tag, whichever comes first. + **/ - (void)skipMessage; -/// Check to see if the logical end of the stream has been reached. -/// -/// This can return NO when there is no more data, but the current parsing -/// expected more data. +/** + * Check to see if the logical end of the stream has been reached. + * + * @note This can return NO when there is no more data, but the current parsing + * expected more data. + * + * @return YES if the logical end of the stream has been reached, NO otherwise. + **/ - (BOOL)isAtEnd; -/// The offset into the stream. +/** + * @return The offset into the stream. + **/ - (size_t)position; -/// Verifies that the last call to @c -readTag returned the given tag value. -/// This is used to verify that a nested group ended with the correct end tag. -/// Throws @c NSParseErrorException if value does not match the last tag. -/// -/// @param expected The tag that was expected. +/** + * Verifies that the last call to -readTag returned the given tag value. This + * is used to verify that a nested group ended with the correct end tag. + * + * @exception NSParseErrorException If the value does not match the last tag. + * + * @param expected The tag that was expected. + **/ - (void)checkLastTagWas:(int32_t)expected; @end diff --git a/objectivec/GPBCodedOutputStream.h b/objectivec/GPBCodedOutputStream.h index 8272880d..d6fff3db 100644 --- a/objectivec/GPBCodedOutputStream.h +++ b/objectivec/GPBCodedOutputStream.h @@ -46,63 +46,122 @@ NS_ASSUME_NONNULL_BEGIN -/// Writes out protocol message fields. -/// -/// The common uses of protocol buffers shouldn't need to use this class. -/// @c GPBMessage's provide a @c -data method that will serialize the message -/// for you. -/// -/// @note Subclassing of GPBCodedOutputStream is NOT supported. +/** + * Writes out protocol message fields. + * + * The common uses of protocol buffers shouldn't need to use this class. + * GPBMessage's provide a -data method that will serialize the message for you. + * + * @note Subclassing of GPBCodedOutputStream is NOT supported. + **/ @interface GPBCodedOutputStream : NSObject -/// Creates a stream to fill in the given data. Data must be sized to fit or -/// an error will be raised when out of space. +/** + * Creates a stream to fill in the given data. Data must be sized to fit or + * an error will be raised when out of space. + * + * @param data The data where the stream will be written to. + * + * @return A newly instanced GPBCodedOutputStream. + **/ + (instancetype)streamWithData:(NSMutableData *)data; -/// Creates a stream to write into the given @c NSOutputStream. +/** + * Creates a stream to write into the given NSOutputStream. + * + * @param output The output stream where the stream will be written to. + * + * @return A newly instanced GPBCodedOutputStream. + **/ + (instancetype)streamWithOutputStream:(NSOutputStream *)output; -/// Initializes a stream to fill in the given data. Data must be sized to fit -/// or an error will be raised when out of space. +/** + * Initializes a stream to fill in the given data. Data must be sized to fit + * or an error will be raised when out of space. + * + * @param data The data where the stream will be written to. + * + * @return A newly initialized GPBCodedOutputStream. + **/ - (instancetype)initWithData:(NSMutableData *)data; -/// Initializes a stream to write into the given @c NSOutputStream. +/** + * Initializes a stream to write into the given @c NSOutputStream. + * + * @param output The output stream where the stream will be written to. + * + * @return A newly initialized GPBCodedOutputStream. + **/ - (instancetype)initWithOutputStream:(NSOutputStream *)output; -/// Flush any buffered data out. +/** + * Flush any buffered data out. + **/ - (void)flush; -/// Write the raw byte out. +/** + * Write the raw byte out. + * + * @param value The value to write out. + **/ - (void)writeRawByte:(uint8_t)value; -/// Write the tag for the given field number and wire format. -/// -/// @param fieldNumber The field number. -/// @param format The wire format the data for the field will be in. +/** + * Write the tag for the given field number and wire format. + * + * @param fieldNumber The field number. + * @param format The wire format the data for the field will be in. + **/ - (void)writeTag:(uint32_t)fieldNumber format:(GPBWireFormat)format; -/// Write a 32bit value out in little endian format. +/** + * Write a 32bit value out in little endian format. + * + * @param value The value to write out. + **/ - (void)writeRawLittleEndian32:(int32_t)value; -/// Write a 64bit value out in little endian format. +/** + * Write a 64bit value out in little endian format. + * + * @param value The value to write out. + **/ - (void)writeRawLittleEndian64:(int64_t)value; -/// Write a 32bit value out in varint format. +/** + * Write a 32bit value out in varint format. + * + * @param value The value to write out. + **/ - (void)writeRawVarint32:(int32_t)value; -/// Write a 64bit value out in varint format. +/** + * Write a 64bit value out in varint format. + * + * @param value The value to write out. + **/ - (void)writeRawVarint64:(int64_t)value; -/// Write a size_t out as a 32bit varint value. -/// -/// @note This will truncate 64 bit values to 32. +/** + * Write a size_t out as a 32bit varint value. + * + * @note This will truncate 64 bit values to 32. + * + * @param value The value to write out. + **/ - (void)writeRawVarintSizeTAs32:(size_t)value; -/// Writes the contents of an @c NSData out. +/** + * Writes the contents of an NSData out. + * + * @param data The data to write out. + **/ - (void)writeRawData:(NSData *)data; -/// Writes out the given data. -/// -/// @param data The data blob to write out. -/// @param offset The offset into the blob to start writing out. -/// @param length The number of bytes from the blob to write out. +/** + * Writes out the given data. + * + * @param data The data blob to write out. + * @param offset The offset into the blob to start writing out. + * @param length The number of bytes from the blob to write out. + **/ - (void)writeRawPtr:(const void *)data offset:(size_t)offset length:(size_t)length; @@ -110,179 +169,471 @@ NS_ASSUME_NONNULL_BEGIN //%PDDM-EXPAND _WRITE_DECLS() // This block of code is generated, do not edit it directly. -/// Write a double for the given field number. +/** + * Write a double for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeDouble:(int32_t)fieldNumber value:(double)value; -/// Write a packed array of double for the given field number. +/** + * Write a packed array of double for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeDoubleArray:(int32_t)fieldNumber values:(GPBDoubleArray *)values tag:(uint32_t)tag; -/// Write a double without any tag. +/** + * Write a double without any tag. + * + * @param value The value to write out. + **/ - (void)writeDoubleNoTag:(double)value; -/// Write a float for the given field number. +/** + * Write a float for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeFloat:(int32_t)fieldNumber value:(float)value; -/// Write a packed array of float for the given field number. +/** + * Write a packed array of float for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeFloatArray:(int32_t)fieldNumber values:(GPBFloatArray *)values tag:(uint32_t)tag; -/// Write a float without any tag. +/** + * Write a float without any tag. + * + * @param value The value to write out. + **/ - (void)writeFloatNoTag:(float)value; -/// Write a uint64_t for the given field number. +/** + * Write a uint64_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeUInt64:(int32_t)fieldNumber value:(uint64_t)value; -/// Write a packed array of uint64_t for the given field number. +/** + * Write a packed array of uint64_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeUInt64Array:(int32_t)fieldNumber values:(GPBUInt64Array *)values tag:(uint32_t)tag; -/// Write a uint64_t without any tag. +/** + * Write a uint64_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeUInt64NoTag:(uint64_t)value; -/// Write a int64_t for the given field number. +/** + * Write a int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeInt64:(int32_t)fieldNumber value:(int64_t)value; -/// Write a packed array of int64_t for the given field number. +/** + * Write a packed array of int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeInt64Array:(int32_t)fieldNumber values:(GPBInt64Array *)values tag:(uint32_t)tag; -/// Write a int64_t without any tag. +/** + * Write a int64_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeInt64NoTag:(int64_t)value; -/// Write a int32_t for the given field number. +/** + * Write a int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeInt32:(int32_t)fieldNumber value:(int32_t)value; -/// Write a packed array of int32_t for the given field number. +/** + * Write a packed array of int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeInt32Array:(int32_t)fieldNumber values:(GPBInt32Array *)values tag:(uint32_t)tag; -/// Write a int32_t without any tag. +/** + * Write a int32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeInt32NoTag:(int32_t)value; -/// Write a uint32_t for the given field number. +/** + * Write a uint32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeUInt32:(int32_t)fieldNumber value:(uint32_t)value; -/// Write a packed array of uint32_t for the given field number. +/** + * Write a packed array of uint32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeUInt32Array:(int32_t)fieldNumber values:(GPBUInt32Array *)values tag:(uint32_t)tag; -/// Write a uint32_t without any tag. +/** + * Write a uint32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeUInt32NoTag:(uint32_t)value; -/// Write a uint64_t for the given field number. +/** + * Write a uint64_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeFixed64:(int32_t)fieldNumber value:(uint64_t)value; -/// Write a packed array of uint64_t for the given field number. +/** + * Write a packed array of uint64_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeFixed64Array:(int32_t)fieldNumber values:(GPBUInt64Array *)values tag:(uint32_t)tag; -/// Write a uint64_t without any tag. +/** + * Write a uint64_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeFixed64NoTag:(uint64_t)value; -/// Write a uint32_t for the given field number. +/** + * Write a uint32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeFixed32:(int32_t)fieldNumber value:(uint32_t)value; -/// Write a packed array of uint32_t for the given field number. +/** + * Write a packed array of uint32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeFixed32Array:(int32_t)fieldNumber values:(GPBUInt32Array *)values tag:(uint32_t)tag; -/// Write a uint32_t without any tag. +/** + * Write a uint32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeFixed32NoTag:(uint32_t)value; -/// Write a int32_t for the given field number. +/** + * Write a int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeSInt32:(int32_t)fieldNumber value:(int32_t)value; -/// Write a packed array of int32_t for the given field number. +/** + * Write a packed array of int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeSInt32Array:(int32_t)fieldNumber values:(GPBInt32Array *)values tag:(uint32_t)tag; -/// Write a int32_t without any tag. +/** + * Write a int32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeSInt32NoTag:(int32_t)value; -/// Write a int64_t for the given field number. +/** + * Write a int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeSInt64:(int32_t)fieldNumber value:(int64_t)value; -/// Write a packed array of int64_t for the given field number. +/** + * Write a packed array of int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeSInt64Array:(int32_t)fieldNumber values:(GPBInt64Array *)values tag:(uint32_t)tag; -/// Write a int64_t without any tag. +/** + * Write a int64_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeSInt64NoTag:(int64_t)value; -/// Write a int64_t for the given field number. +/** + * Write a int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeSFixed64:(int32_t)fieldNumber value:(int64_t)value; -/// Write a packed array of int64_t for the given field number. +/** + * Write a packed array of int64_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeSFixed64Array:(int32_t)fieldNumber values:(GPBInt64Array *)values tag:(uint32_t)tag; -/// Write a int64_t without any tag. +/** + * Write a int64_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeSFixed64NoTag:(int64_t)value; -/// Write a int32_t for the given field number. +/** + * Write a int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeSFixed32:(int32_t)fieldNumber value:(int32_t)value; -/// Write a packed array of int32_t for the given field number. +/** + * Write a packed array of int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeSFixed32Array:(int32_t)fieldNumber values:(GPBInt32Array *)values tag:(uint32_t)tag; -/// Write a int32_t without any tag. +/** + * Write a int32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeSFixed32NoTag:(int32_t)value; -/// Write a BOOL for the given field number. +/** + * Write a BOOL for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeBool:(int32_t)fieldNumber value:(BOOL)value; -/// Write a packed array of BOOL for the given field number. +/** + * Write a packed array of BOOL for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeBoolArray:(int32_t)fieldNumber values:(GPBBoolArray *)values tag:(uint32_t)tag; -/// Write a BOOL without any tag. +/** + * Write a BOOL without any tag. + * + * @param value The value to write out. + **/ - (void)writeBoolNoTag:(BOOL)value; -/// Write a int32_t for the given field number. +/** + * Write a int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeEnum:(int32_t)fieldNumber value:(int32_t)value; -/// Write a packed array of int32_t for the given field number. +/** + * Write a packed array of int32_t for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + * @param tag The tag assigned to the values. + **/ - (void)writeEnumArray:(int32_t)fieldNumber values:(GPBEnumArray *)values tag:(uint32_t)tag; -/// Write a int32_t without any tag. +/** + * Write a int32_t without any tag. + * + * @param value The value to write out. + **/ - (void)writeEnumNoTag:(int32_t)value; -/// Write a NSString for the given field number. +/** + * Write a NSString for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeString:(int32_t)fieldNumber value:(NSString *)value; -/// Write an array of NSString for the given field number. +/** + * Write an array of NSString for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + **/ - (void)writeStringArray:(int32_t)fieldNumber values:(NSArray<NSString*> *)values; -/// Write a NSString without any tag. +/** + * Write a NSString without any tag. + * + * @param value The value to write out. + **/ - (void)writeStringNoTag:(NSString *)value; -/// Write a GPBMessage for the given field number. +/** + * Write a GPBMessage for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeMessage:(int32_t)fieldNumber value:(GPBMessage *)value; -/// Write an array of GPBMessage for the given field number. +/** + * Write an array of GPBMessage for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + **/ - (void)writeMessageArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values; -/// Write a GPBMessage without any tag. +/** + * Write a GPBMessage without any tag. + * + * @param value The value to write out. + **/ - (void)writeMessageNoTag:(GPBMessage *)value; -/// Write a NSData for the given field number. +/** + * Write a NSData for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeBytes:(int32_t)fieldNumber value:(NSData *)value; -/// Write an array of NSData for the given field number. +/** + * Write an array of NSData for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + **/ - (void)writeBytesArray:(int32_t)fieldNumber values:(NSArray<NSData*> *)values; -/// Write a NSData without any tag. +/** + * Write a NSData without any tag. + * + * @param value The value to write out. + **/ - (void)writeBytesNoTag:(NSData *)value; -/// Write a GPBMessage for the given field number. +/** + * Write a GPBMessage for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeGroup:(int32_t)fieldNumber value:(GPBMessage *)value; -/// Write an array of GPBMessage for the given field number. +/** + * Write an array of GPBMessage for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + **/ - (void)writeGroupArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values; -/// Write a GPBMessage without any tag (but does write the endGroup tag). +/** + * Write a GPBMessage without any tag (but does write the endGroup tag). + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeGroupNoTag:(int32_t)fieldNumber value:(GPBMessage *)value; -/// Write a GPBUnknownFieldSet for the given field number. +/** + * Write a GPBUnknownFieldSet for the given field number. + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeUnknownGroup:(int32_t)fieldNumber value:(GPBUnknownFieldSet *)value; -/// Write an array of GPBUnknownFieldSet for the given field number. +/** + * Write an array of GPBUnknownFieldSet for the given field number. + * + * @param fieldNumber The field number assigned to the values. + * @param values The values to write out. + **/ - (void)writeUnknownGroupArray:(int32_t)fieldNumber values:(NSArray<GPBUnknownFieldSet*> *)values; -/// Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag). +/** + * Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag). + * + * @param fieldNumber The field number assigned to the value. + * @param value The value to write out. + **/ - (void)writeUnknownGroupNoTag:(int32_t)fieldNumber value:(GPBUnknownFieldSet *)value; //%PDDM-EXPAND-END _WRITE_DECLS() -/// Write a MessageSet extension field to the stream. For historical reasons, -/// the wire format differs from normal fields. +/** +Write a MessageSet extension field to the stream. For historical reasons, +the wire format differs from normal fields. + +@param fieldNumber The extension field number to write out. +@param value The message from where to get the extension. +*/ - (void)writeMessageSetExtension:(int32_t)fieldNumber value:(GPBMessage *)value; -/// Write an unparsed MessageSet extension field to the stream. For -/// historical reasons, the wire format differs from normal fields. +/** +Write an unparsed MessageSet extension field to the stream. For historical +reasons, the wire format differs from normal fields. + +@param fieldNumber The extension field number to write out. +@param value The raw message from where to get the extension. +*/ - (void)writeRawMessageSetExtension:(int32_t)fieldNumber value:(NSData *)value; @end @@ -291,32 +642,76 @@ NS_ASSUME_NONNULL_END // Write methods for types that can be in packed arrays. //%PDDM-DEFINE _WRITE_PACKABLE_DECLS(NAME, ARRAY_TYPE, TYPE) -//%/// Write a TYPE for the given field number. +//%/** +//% * Write a TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the value. +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE)value; -//%/// Write a packed array of TYPE for the given field number. +//%/** +//% * Write a packed array of TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the values. +//% * @param values The values to write out. +//% * @param tag The tag assigned to the values. +//% **/ //%- (void)write##NAME##Array:(int32_t)fieldNumber //% NAME$S values:(GPB##ARRAY_TYPE##Array *)values //% NAME$S tag:(uint32_t)tag; -//%/// Write a TYPE without any tag. +//%/** +//% * Write a TYPE without any tag. +//% * +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME##NoTag:(TYPE)value; //% // Write methods for types that aren't in packed arrays. //%PDDM-DEFINE _WRITE_UNPACKABLE_DECLS(NAME, TYPE) -//%/// Write a TYPE for the given field number. +//%/** +//% * Write a TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the value. +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE *)value; -//%/// Write an array of TYPE for the given field number. +//%/** +//% * Write an array of TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the values. +//% * @param values The values to write out. +//% **/ //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values; -//%/// Write a TYPE without any tag. +//%/** +//% * Write a TYPE without any tag. +//% * +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME##NoTag:(TYPE *)value; //% // Special write methods for Groups. //%PDDM-DEFINE _WRITE_GROUP_DECLS(NAME, TYPE) -//%/// Write a TYPE for the given field number. +//%/** +//% * Write a TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the value. +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME:(int32_t)fieldNumber //% NAME$S value:(TYPE *)value; -//%/// Write an array of TYPE for the given field number. +//%/** +//% * Write an array of TYPE for the given field number. +//% * +//% * @param fieldNumber The field number assigned to the values. +//% * @param values The values to write out. +//% **/ //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values; -//%/// Write a TYPE without any tag (but does write the endGroup tag). +//%/** +//% * Write a TYPE without any tag (but does write the endGroup tag). +//% * +//% * @param fieldNumber The field number assigned to the value. +//% * @param value The value to write out. +//% **/ //%- (void)write##NAME##NoTag:(int32_t)fieldNumber //% NAME$S value:(TYPE *)value; //% diff --git a/objectivec/GPBCodedOutputStream.m b/objectivec/GPBCodedOutputStream.m index 63ba8068..7c3ab447 100644 --- a/objectivec/GPBCodedOutputStream.m +++ b/objectivec/GPBCodedOutputStream.m @@ -144,22 +144,6 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state, GPBWriteRawByte(state, (int32_t)(value >> 56) & 0xFF); } -#if defined(DEBUG) && DEBUG && !defined(NS_BLOCK_ASSERTIONS) -+ (void)load { - // This test exists to verify that CFStrings with embedded NULLs will work - // for us. If this Assert fails, all code below that depends on - // CFStringGetCStringPtr will NOT work properly on strings that contain - // embedded NULLs, and we do get that in some protobufs. - // Note that this will not be compiled in release. - // We didn't feel that just keeping it in a unit test was sufficient because - // the Protobuf unit tests are only run when somebody is actually working - // on protobufs. - CFStringRef zeroTest = CFSTR("Test\0String"); - const char *cString = CFStringGetCStringPtr(zeroTest, kCFStringEncodingUTF8); - NSAssert(cString == NULL, @"Serious Error"); -} -#endif // DEBUG && !defined(NS_BLOCK_ASSERTIONS) - - (void)dealloc { [self flush]; [state_.output close]; @@ -282,19 +266,15 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state, } - (void)writeStringNoTag:(const NSString *)value { - // If you are concerned about embedded NULLs see the test in - // +load above. - const char *quickString = - CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); - size_t length = (quickString != NULL) - ? strlen(quickString) - : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; + size_t length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; GPBWriteRawVarint32(&state_, (int32_t)length); - if (length == 0) { return; } + const char *quickString = + CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); + // Fast path: Most strings are short, if the buffer already has space, // add to it directly. NSUInteger bufferBytesLeft = state_.size - state_.position; @@ -310,7 +290,7 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state, maxLength:bufferBytesLeft usedLength:&usedBufferLength encoding:NSUTF8StringEncoding - options:0 + options:(NSStringEncodingConversionOptions)0 range:NSMakeRange(0, [value length]) remainingRange:NULL]; } @@ -1038,14 +1018,7 @@ size_t GPBComputeBoolSizeNoTag(BOOL value) { } size_t GPBComputeStringSizeNoTag(NSString *value) { - // If you are concerned about embedded NULLs see the test in - // +load above. - const char *quickString = - CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); - NSUInteger length = - (quickString != NULL) - ? strlen(quickString) - : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; + NSUInteger length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; return GPBComputeRawVarint32SizeForInteger(length) + length; } diff --git a/objectivec/GPBDescriptor.h b/objectivec/GPBDescriptor.h index fe4ff390..651f4de0 100644 --- a/objectivec/GPBDescriptor.h +++ b/objectivec/GPBDescriptor.h @@ -39,104 +39,250 @@ NS_ASSUME_NONNULL_BEGIN +/** Syntax used in the proto file. */ typedef NS_ENUM(uint8_t, GPBFileSyntax) { + /** Unknown syntax. */ GPBFileSyntaxUnknown = 0, + /** Proto2 syntax. */ GPBFileSyntaxProto2 = 2, + /** Proto3 syntax. */ GPBFileSyntaxProto3 = 3, }; +/** Type of proto field. */ typedef NS_ENUM(uint8_t, GPBFieldType) { - GPBFieldTypeSingle, // optional/required - GPBFieldTypeRepeated, // repeated - GPBFieldTypeMap, // map<K,V> + /** Optional/required field. Only valid for proto2 fields. */ + GPBFieldTypeSingle, + /** Repeated field. */ + GPBFieldTypeRepeated, + /** Map field. */ + GPBFieldTypeMap, }; +/** + * Describes a proto message. + **/ @interface GPBDescriptor : NSObject<NSCopying> +/** Name of the message. */ @property(nonatomic, readonly, copy) NSString *name; +/** Fields declared in the message. */ @property(nonatomic, readonly, strong, nullable) NSArray<GPBFieldDescriptor*> *fields; +/** Oneofs declared in the message. */ @property(nonatomic, readonly, strong, nullable) NSArray<GPBOneofDescriptor*> *oneofs; +/** Extension range declared for the message. */ @property(nonatomic, readonly, nullable) const GPBExtensionRange *extensionRanges; +/** Number of extension ranges declared for the message. */ @property(nonatomic, readonly) uint32_t extensionRangesCount; +/** Descriptor for the file where the message was defined. */ @property(nonatomic, readonly, assign) GPBFileDescriptor *file; +/** Whether the message is in wire format or not. */ @property(nonatomic, readonly, getter=isWireFormat) BOOL wireFormat; +/** The class of this message. */ @property(nonatomic, readonly) Class messageClass; +/** Containing message descriptor if this message is nested, or nil otherwise. */ +@property(readonly, nullable) GPBDescriptor *containingType; +/** + * Fully qualified name for this message (package.message). Can be nil if the + * value is unable to be computed. + */ +@property(readonly, nullable) NSString *fullName; +/** + * Gets the field for the given number. + * + * @param fieldNumber The number for the field to get. + * + * @return The field descriptor for the given number, or nil if not found. + **/ - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber; + +/** + * Gets the field for the given name. + * + * @param name The name for the field to get. + * + * @return The field descriptor for the given name, or nil if not found. + **/ - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name; + +/** + * Gets the oneof for the given name. + * + * @param name The name for the oneof to get. + * + * @return The oneof descriptor for the given name, or nil if not found. + **/ - (nullable GPBOneofDescriptor *)oneofWithName:(NSString *)name; @end +/** + * Describes a proto file. + **/ @interface GPBFileDescriptor : NSObject +/** The package declared in the proto file. */ @property(nonatomic, readonly, copy) NSString *package; +/** The objc prefix declared in the proto file. */ +@property(nonatomic, readonly, copy, nullable) NSString *objcPrefix; +/** The syntax of the proto file. */ @property(nonatomic, readonly) GPBFileSyntax syntax; @end +/** + * Describes a oneof field. + **/ @interface GPBOneofDescriptor : NSObject +/** Name of the oneof field. */ @property(nonatomic, readonly) NSString *name; +/** Fields declared in the oneof. */ @property(nonatomic, readonly) NSArray<GPBFieldDescriptor*> *fields; +/** + * Gets the field for the given number. + * + * @param fieldNumber The number for the field to get. + * + * @return The field descriptor for the given number, or nil if not found. + **/ - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber; + +/** + * Gets the field for the given name. + * + * @param name The name for the field to get. + * + * @return The field descriptor for the given name, or nil if not found. + **/ - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name; + @end +/** + * Describes a proto field. + **/ @interface GPBFieldDescriptor : NSObject +/** Name of the field. */ @property(nonatomic, readonly, copy) NSString *name; +/** Number associated with the field. */ @property(nonatomic, readonly) uint32_t number; +/** Data type contained in the field. */ @property(nonatomic, readonly) GPBDataType dataType; +/** Whether it has a default value or not. */ @property(nonatomic, readonly) BOOL hasDefaultValue; +/** Default value for the field. */ @property(nonatomic, readonly) GPBGenericValue defaultValue; +/** Whether this field is required. Only valid for proto2 fields. */ @property(nonatomic, readonly, getter=isRequired) BOOL required; +/** Whether this field is optional. */ @property(nonatomic, readonly, getter=isOptional) BOOL optional; +/** Type of field (single, repeated, map). */ @property(nonatomic, readonly) GPBFieldType fieldType; -// If it is a map, the value type is in -type. +/** Type of the key if the field is a map. The value's type is -fieldType. */ @property(nonatomic, readonly) GPBDataType mapKeyDataType; +/** Whether the field is packable. */ @property(nonatomic, readonly, getter=isPackable) BOOL packable; +/** The containing oneof if this field is part of one, nil otherwise. */ @property(nonatomic, readonly, assign, nullable) GPBOneofDescriptor *containingOneof; -// Message properties +/** Class of the message if the field is of message type. */ @property(nonatomic, readonly, assign, nullable) Class msgClass; -// Enum properties +/** Descriptor for the enum if this field is an enum. */ @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor; +/** + * Checks whether the given enum raw value is a valid enum value. + * + * @param value The raw enum value to check. + * + * @return YES if value is a valid enum raw value. + **/ - (BOOL)isValidEnumValue:(int32_t)value; -// For now, this will return nil if it doesn't know the name to use for -// TextFormat. +/** @return Name for the text format, or nil if not known. */ - (nullable NSString *)textFormatName; @end +/** + * Describes a proto enum. + **/ @interface GPBEnumDescriptor : NSObject +/** Name of the enum. */ @property(nonatomic, readonly, copy) NSString *name; +/** Function that validates that raw values are valid enum values. */ @property(nonatomic, readonly) GPBEnumValidationFunc enumVerifier; +/** + * Returns the enum value name for the given raw enum. + * + * @param number The raw enum value. + * + * @return The name of the enum value passed, or nil if not valid. + **/ - (nullable NSString *)enumNameForValue:(int32_t)number; + +/** + * Gets the enum raw value for the given enum name. + * + * @param outValue A pointer where the value will be set. + * @param name The enum name for which to get the raw value. + * + * @return YES if a value was copied into the pointer, NO otherwise. + **/ - (BOOL)getValue:(nullable int32_t *)outValue forEnumName:(NSString *)name; +/** + * Returns the text format for the given raw enum value. + * + * @param number The raw enum value. + * + * @return The text format name for the raw enum value, or nil if not valid. + **/ - (nullable NSString *)textFormatNameForValue:(int32_t)number; + +/** + * Gets the enum raw value for the given text format name. + * + * @param outValue A pointer where the value will be set. + * @param textFormatName The text format name for which to get the raw value. + * + * @return YES if a value was copied into the pointer, NO otherwise. + **/ - (BOOL)getValue:(nullable int32_t *)outValue forEnumTextFormatName:(NSString *)textFormatName; @end +/** + * Describes a proto extension. + **/ @interface GPBExtensionDescriptor : NSObject<NSCopying> +/** Field number under which the extension is stored. */ @property(nonatomic, readonly) uint32_t fieldNumber; +/** The containing message class, i.e. the class extended by this extension. */ @property(nonatomic, readonly) Class containingMessageClass; +/** Data type contained in the extension. */ @property(nonatomic, readonly) GPBDataType dataType; +/** Whether the extension is repeated. */ @property(nonatomic, readonly, getter=isRepeated) BOOL repeated; +/** Whether the extension is packable. */ @property(nonatomic, readonly, getter=isPackable) BOOL packable; +/** The class of the message if the extension is of message type. */ @property(nonatomic, readonly, assign) Class msgClass; +/** The singleton name for the extension. */ @property(nonatomic, readonly) NSString *singletonName; +/** The enum descriptor if the extension is of enum type. */ @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor; +/** The default value for the extension. */ @property(nonatomic, readonly, nullable) id defaultValue; + @end NS_ASSUME_NONNULL_END diff --git a/objectivec/GPBDescriptor.m b/objectivec/GPBDescriptor.m index dccb9bc8..0753a948 100644 --- a/objectivec/GPBDescriptor.m +++ b/objectivec/GPBDescriptor.m @@ -42,8 +42,10 @@ #pragma clang diagnostic push #pragma clang diagnostic ignored "-Wdirect-ivar-access" -// The address of this variable is used as a key for obj_getAssociatedObject. +// The addresses of these variables are used as keys for objc_getAssociatedObject. static const char kTextFormatExtraValueKey = 0; +static const char kParentClassNameValueKey = 0; +static const char kClassNameSuffixKey = 0; // Utility function to generate selectors on the fly. static SEL SelFromStrings(const char *prefix, const char *middle, @@ -215,10 +217,102 @@ static NSArray *NewFieldsArrayForHasIndex(int hasIndex, extensionRangesCount_ = count; } +- (void)setupContainingMessageClassName:(const char *)msgClassName { + // Note: Only fetch the class here, can't send messages to it because + // that could cause cycles back to this class within +initialize if + // two messages have each other in fields (i.e. - they build a graph). + NSAssert(objc_getClass(msgClassName), @"Class %s not defined", msgClassName); + NSValue *parentNameValue = [NSValue valueWithPointer:msgClassName]; + objc_setAssociatedObject(self, &kParentClassNameValueKey, + parentNameValue, + OBJC_ASSOCIATION_RETAIN_NONATOMIC); +} + +- (void)setupMessageClassNameSuffix:(NSString *)suffix { + if (suffix.length) { + objc_setAssociatedObject(self, &kClassNameSuffixKey, + suffix, + OBJC_ASSOCIATION_RETAIN_NONATOMIC); + } +} + - (NSString *)name { return NSStringFromClass(messageClass_); } +- (GPBDescriptor *)containingType { + NSValue *parentNameValue = + objc_getAssociatedObject(self, &kParentClassNameValueKey); + if (!parentNameValue) { + return nil; + } + const char *parentName = [parentNameValue pointerValue]; + Class parentClass = objc_getClass(parentName); + NSAssert(parentClass, @"Class %s not defined", parentName); + return [parentClass descriptor]; +} + +- (NSString *)fullName { + NSString *className = NSStringFromClass(self.messageClass); + GPBFileDescriptor *file = self.file; + NSString *objcPrefix = file.objcPrefix; + if (objcPrefix && ![className hasPrefix:objcPrefix]) { + NSAssert(0, + @"Class didn't have correct prefix? (%@ - %@)", + className, objcPrefix); + return nil; + } + GPBDescriptor *parent = self.containingType; + + NSString *name = nil; + if (parent) { + NSString *parentClassName = NSStringFromClass(parent.messageClass); + // The generator will add _Class to avoid reserved words, drop it. + NSString *suffix = objc_getAssociatedObject(parent, &kClassNameSuffixKey); + if (suffix) { + if (![parentClassName hasSuffix:suffix]) { + NSAssert(0, + @"ParentMessage class didn't have correct suffix? (%@ - %@)", + className, suffix); + return nil; + } + parentClassName = + [parentClassName substringToIndex:(parentClassName.length - suffix.length)]; + } + NSString *parentPrefix = [parentClassName stringByAppendingString:@"_"]; + if (![className hasPrefix:parentPrefix]) { + NSAssert(0, + @"Class didn't have the correct parent name prefix? (%@ - %@)", + parentPrefix, className); + return nil; + } + name = [className substringFromIndex:parentPrefix.length]; + } else { + name = [className substringFromIndex:objcPrefix.length]; + } + + // The generator will add _Class to avoid reserved words, drop it. + NSString *suffix = objc_getAssociatedObject(self, &kClassNameSuffixKey); + if (suffix) { + if (![name hasSuffix:suffix]) { + NSAssert(0, + @"Message class didn't have correct suffix? (%@ - %@)", + name, suffix); + return nil; + } + name = [name substringToIndex:(name.length - suffix.length)]; + } + + NSString *prefix = (parent != nil ? parent.fullName : file.package); + NSString *result; + if (prefix.length > 0) { + result = [NSString stringWithFormat:@"%@.%@", prefix, name]; + } else { + result = name; + } + return result; +} + - (id)copyWithZone:(NSZone *)zone { #pragma unused(zone) return [self retain]; @@ -255,13 +349,27 @@ static NSArray *NewFieldsArrayForHasIndex(int hasIndex, @implementation GPBFileDescriptor { NSString *package_; + NSString *objcPrefix_; GPBFileSyntax syntax_; } @synthesize package = package_; +@synthesize objcPrefix = objcPrefix_; @synthesize syntax = syntax_; - (instancetype)initWithPackage:(NSString *)package + objcPrefix:(NSString *)objcPrefix + syntax:(GPBFileSyntax)syntax { + self = [super init]; + if (self) { + package_ = [package copy]; + objcPrefix_ = [objcPrefix copy]; + syntax_ = syntax; + } + return self; +} + +- (instancetype)initWithPackage:(NSString *)package syntax:(GPBFileSyntax)syntax { self = [super init]; if (self) { @@ -273,6 +381,7 @@ static NSArray *NewFieldsArrayForHasIndex(int hasIndex, - (void)dealloc { [package_ release]; + [objcPrefix_ release]; [super dealloc]; } @@ -416,6 +525,9 @@ uint32_t GPBFieldAlternateTag(GPBFieldDescriptor *self) { // Extra type specific data. if (isMessage) { const char *className = coreDesc->dataTypeSpecific.className; + // Note: Only fetch the class here, can't send messages to it because + // that could cause cycles back to this class within +initialize if + // two messages have each other in fields (i.e. - they build a graph). msgClass_ = objc_getClass(className); NSAssert(msgClass_, @"Class %s not defined", className); } else if (dataType == GPBDataTypeEnum) { diff --git a/objectivec/GPBDescriptor_PackagePrivate.h b/objectivec/GPBDescriptor_PackagePrivate.h index c20ff6b0..9173e7a2 100644 --- a/objectivec/GPBDescriptor_PackagePrivate.h +++ b/objectivec/GPBDescriptor_PackagePrivate.h @@ -37,6 +37,7 @@ // Describes attributes of the field. typedef NS_OPTIONS(uint16_t, GPBFieldFlags) { + GPBFieldNone = 0, // These map to standard protobuf concepts. GPBFieldRequired = 1 << 0, GPBFieldRepeated = 1 << 1, @@ -111,6 +112,7 @@ typedef struct GPBMessageFieldDescriptionWithDefault { // Describes attributes of the extension. typedef NS_OPTIONS(uint8_t, GPBExtensionOptions) { + GPBExtensionNone = 0, // These map to standard protobuf concepts. GPBExtensionRepeated = 1 << 0, GPBExtensionPacked = 1 << 1, @@ -130,6 +132,7 @@ typedef struct GPBExtensionDescription { } GPBExtensionDescription; typedef NS_OPTIONS(uint32_t, GPBDescriptorInitializationFlags) { + GPBDescriptorInitializationFlag_None = 0, GPBDescriptorInitializationFlag_FieldsWithDefault = 1 << 0, GPBDescriptorInitializationFlag_WireFormat = 1 << 1, }; @@ -165,11 +168,16 @@ typedef NS_OPTIONS(uint32_t, GPBDescriptorInitializationFlags) { firstHasIndex:(int32_t)firstHasIndex; - (void)setupExtraTextInfo:(const char *)extraTextFormatInfo; - (void)setupExtensionRanges:(const GPBExtensionRange *)ranges count:(int32_t)count; +- (void)setupContainingMessageClassName:(const char *)msgClassName; +- (void)setupMessageClassNameSuffix:(NSString *)suffix; @end @interface GPBFileDescriptor () - (instancetype)initWithPackage:(NSString *)package + objcPrefix:(NSString *)objcPrefix + syntax:(GPBFileSyntax)syntax; +- (instancetype)initWithPackage:(NSString *)package syntax:(GPBFileSyntax)syntax; @end diff --git a/objectivec/GPBDictionary.h b/objectivec/GPBDictionary.h index f7959960..4b2b9ff3 100644 --- a/objectivec/GPBDictionary.h +++ b/objectivec/GPBDictionary.h @@ -32,11 +32,6 @@ #import "GPBRuntimeTypes.h" -// These classes are used for map fields of basic data types. They are used because -// they perform better than boxing into NSNumbers in NSDictionaries. - -// Note: These are not meant to be subclassed. - // Note on naming: for the classes holding numeric values, a more natural // naming of the method might be things like "-valueForKey:", // "-setValue:forKey:"; etc. But those selectors are also defined by Key Value @@ -53,289 +48,1134 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - UInt32 -> UInt32 +/** + * Class used for map fields of <uint32_t, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32UInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32UInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32UInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(uint32_t key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32UInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Int32 +/** + * Class used for map fields of <uint32_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32Int32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32Int32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32Int32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(uint32_t key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32Int32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> UInt64 +/** + * Class used for map fields of <uint32_t, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32UInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32UInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32UInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(uint32_t key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32UInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Int64 +/** + * Class used for map fields of <uint32_t, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32Int64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32Int64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32Int64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(uint32_t key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32Int64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Bool +/** + * Class used for map fields of <uint32_t, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32BoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32BoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32BoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(uint32_t key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32BoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Float +/** + * Class used for map fields of <uint32_t, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32FloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32FloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32FloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(uint32_t key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32FloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Double +/** + * Class used for map fields of <uint32_t, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32DoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32DoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32DoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(uint32_t key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32DoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Enum +/** + * Class used for map fields of <uint32_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32EnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32EnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBUInt32EnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -343,23 +1183,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(uint32_t key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(uint32_t key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBUInt32EnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -367,339 +1247,1312 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(uint32_t)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(uint32_t)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt32 -> Object +/** + * Class used for map fields of <uint32_t, ObjectType> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32ObjectDictionary<__covariant ObjectType> : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param object The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithObject:(ObjectType)object forKey:(uint32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param objects The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const uint32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt32ObjectDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param objects The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const uint32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt32ObjectDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; +/** + * Fetches the object stored under the given key. + * + * @param key Key under which the value is stored, if present. + * + * @return The object if found, nil otherwise. + **/ - (ObjectType)objectForKey:(uint32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **object**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndObjectsUsingBlock: (void (^)(uint32_t key, ObjectType object, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt32ObjectDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param object The value to set. + * @param key The key under which to store the value. + **/ - (void)setObject:(ObjectType)object forKey:(uint32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeObjectForKey:(uint32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> UInt32 +/** + * Class used for map fields of <int32_t, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32UInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32UInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32UInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(int32_t key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32UInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Int32 +/** + * Class used for map fields of <int32_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32Int32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32Int32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32Int32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(int32_t key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32Int32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> UInt64 +/** + * Class used for map fields of <int32_t, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32UInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32UInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32UInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(int32_t key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32UInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Int64 +/** + * Class used for map fields of <int32_t, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32Int64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32Int64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32Int64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(int32_t key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32Int64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Bool +/** + * Class used for map fields of <int32_t, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32BoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32BoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32BoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(int32_t key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32BoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Float +/** + * Class used for map fields of <int32_t, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32FloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32FloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32FloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(int32_t key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32FloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Double +/** + * Class used for map fields of <int32_t, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32DoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32DoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32DoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(int32_t key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32DoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Enum +/** + * Class used for map fields of <int32_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32EnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32EnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBInt32EnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -707,23 +2560,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(int32_t key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(int32_t key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBInt32EnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -731,339 +2624,1312 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(int32_t)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(int32_t)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int32 -> Object +/** + * Class used for map fields of <int32_t, ObjectType> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32ObjectDictionary<__covariant ObjectType> : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param object The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithObject:(ObjectType)object forKey:(int32_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param objects The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const int32_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt32ObjectDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param objects The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const int32_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt32ObjectDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; +/** + * Fetches the object stored under the given key. + * + * @param key Key under which the value is stored, if present. + * + * @return The object if found, nil otherwise. + **/ - (ObjectType)objectForKey:(int32_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **object**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndObjectsUsingBlock: (void (^)(int32_t key, ObjectType object, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt32ObjectDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param object The value to set. + * @param key The key under which to store the value. + **/ - (void)setObject:(ObjectType)object forKey:(int32_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeObjectForKey:(int32_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> UInt32 +/** + * Class used for map fields of <uint64_t, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64UInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64UInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64UInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(uint64_t key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64UInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Int32 +/** + * Class used for map fields of <uint64_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64Int32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64Int32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64Int32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(uint64_t key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64Int32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> UInt64 +/** + * Class used for map fields of <uint64_t, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64UInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64UInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64UInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(uint64_t key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64UInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Int64 +/** + * Class used for map fields of <uint64_t, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64Int64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64Int64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64Int64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(uint64_t key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64Int64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Bool +/** + * Class used for map fields of <uint64_t, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64BoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64BoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64BoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(uint64_t key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64BoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Float +/** + * Class used for map fields of <uint64_t, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64FloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64FloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64FloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(uint64_t key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64FloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Double +/** + * Class used for map fields of <uint64_t, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64DoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64DoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64DoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(uint64_t key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64DoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Enum +/** + * Class used for map fields of <uint64_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64EnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64EnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBUInt64EnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -1071,23 +3937,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(uint64_t key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(uint64_t key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBUInt64EnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -1095,339 +4001,1312 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(uint64_t)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(uint64_t)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - UInt64 -> Object +/** + * Class used for map fields of <uint64_t, ObjectType> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64ObjectDictionary<__covariant ObjectType> : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param object The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithObject:(ObjectType)object forKey:(uint64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param objects The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const uint64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBUInt64ObjectDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param objects The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const uint64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBUInt64ObjectDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; +/** + * Fetches the object stored under the given key. + * + * @param key Key under which the value is stored, if present. + * + * @return The object if found, nil otherwise. + **/ - (ObjectType)objectForKey:(uint64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **object**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndObjectsUsingBlock: (void (^)(uint64_t key, ObjectType object, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBUInt64ObjectDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param object The value to set. + * @param key The key under which to store the value. + **/ - (void)setObject:(ObjectType)object forKey:(uint64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeObjectForKey:(uint64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> UInt32 +/** + * Class used for map fields of <int64_t, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64UInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64UInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64UInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(int64_t key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64UInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Int32 +/** + * Class used for map fields of <int64_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64Int32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64Int32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64Int32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(int64_t key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64Int32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> UInt64 +/** + * Class used for map fields of <int64_t, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64UInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64UInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64UInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(int64_t key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64UInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Int64 +/** + * Class used for map fields of <int64_t, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64Int64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64Int64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64Int64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(int64_t key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64Int64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Bool +/** + * Class used for map fields of <int64_t, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64BoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64BoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64BoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(int64_t key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64BoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Float +/** + * Class used for map fields of <int64_t, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64FloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64FloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64FloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(int64_t key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64FloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Double +/** + * Class used for map fields of <int64_t, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64DoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64DoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64DoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(int64_t key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64DoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Enum +/** + * Class used for map fields of <int64_t, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64EnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64EnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBInt64EnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -1435,23 +5314,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(int64_t key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(int64_t key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBInt64EnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -1459,339 +5378,1312 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(int64_t)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(int64_t)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Int64 -> Object +/** + * Class used for map fields of <int64_t, ObjectType> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64ObjectDictionary<__covariant ObjectType> : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param object The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithObject:(ObjectType)object forKey:(int64_t)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param objects The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const int64_t [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBInt64ObjectDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param objects The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const int64_t [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBInt64ObjectDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; +/** + * Fetches the object stored under the given key. + * + * @param key Key under which the value is stored, if present. + * + * @return The object if found, nil otherwise. + **/ - (ObjectType)objectForKey:(int64_t)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **object**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndObjectsUsingBlock: (void (^)(int64_t key, ObjectType object, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBInt64ObjectDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param object The value to set. + * @param key The key under which to store the value. + **/ - (void)setObject:(ObjectType)object forKey:(int64_t)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeObjectForKey:(int64_t)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> UInt32 +/** + * Class used for map fields of <BOOL, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolUInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolUInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolUInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(BOOL key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolUInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Int32 +/** + * Class used for map fields of <BOOL, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(BOOL key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> UInt64 +/** + * Class used for map fields of <BOOL, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolUInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolUInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolUInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(BOOL key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolUInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Int64 +/** + * Class used for map fields of <BOOL, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(BOOL key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Bool +/** + * Class used for map fields of <BOOL, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolBoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolBoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolBoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(BOOL key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolBoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Float +/** + * Class used for map fields of <BOOL, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolFloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolFloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolFloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(BOOL key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolFloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Double +/** + * Class used for map fields of <BOOL, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolDoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolDoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolDoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(BOOL key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolDoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Enum +/** + * Class used for map fields of <BOOL, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolEnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolEnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBBoolEnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -1799,23 +6691,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(BOOL key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(BOOL key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBBoolEnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -1823,339 +6755,1312 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(BOOL)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(BOOL)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - Bool -> Object +/** + * Class used for map fields of <BOOL, ObjectType> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolObjectDictionary<__covariant ObjectType> : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param object The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithObject:(ObjectType)object forKey:(BOOL)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param objects The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const BOOL [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBBoolObjectDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param objects The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithObjects:(const ObjectType GPB_UNSAFE_UNRETAINED [])objects forKeys:(const BOOL [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBBoolObjectDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; +/** + * Fetches the object stored under the given key. + * + * @param key Key under which the value is stored, if present. + * + * @return The object if found, nil otherwise. + **/ - (ObjectType)objectForKey:(BOOL)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **object**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndObjectsUsingBlock: (void (^)(BOOL key, ObjectType object, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBBoolObjectDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param object The value to set. + * @param key The key under which to store the value. + **/ - (void)setObject:(ObjectType)object forKey:(BOOL)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeObjectForKey:(BOOL)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> UInt32 +/** + * Class used for map fields of <NSString, uint32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringUInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt32:(uint32_t)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt32s:(const uint32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringUInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt32s:(const uint32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringUInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt32:(nullable uint32_t *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt32sUsingBlock: (void (^)(NSString *key, uint32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringUInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt32:(uint32_t)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt32ForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Int32 +/** + * Class used for map fields of <NSString, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringInt32Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt32:(int32_t)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt32s:(const int32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringInt32Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt32s:(const int32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringInt32Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt32:(nullable int32_t *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt32sUsingBlock: (void (^)(NSString *key, int32_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringInt32Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt32:(int32_t)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt32ForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> UInt64 +/** + * Class used for map fields of <NSString, uint64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringUInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithUInt64:(uint64_t)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithUInt64s:(const uint64_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringUInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithUInt64s:(const uint64_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringUInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getUInt64:(nullable uint64_t *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndUInt64sUsingBlock: (void (^)(NSString *key, uint64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringUInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setUInt64:(uint64_t)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeUInt64ForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Int64 +/** + * Class used for map fields of <NSString, int64_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringInt64Dictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithInt64:(int64_t)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithInt64s:(const int64_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringInt64Dictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithInt64s:(const int64_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringInt64Dictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getInt64:(nullable int64_t *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndInt64sUsingBlock: (void (^)(NSString *key, int64_t value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringInt64Dictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setInt64:(int64_t)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeInt64ForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Bool +/** + * Class used for map fields of <NSString, BOOL> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringBoolDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithBool:(BOOL)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithBools:(const BOOL [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringBoolDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithBools:(const BOOL [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringBoolDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getBool:(nullable BOOL *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndBoolsUsingBlock: (void (^)(NSString *key, BOOL value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringBoolDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setBool:(BOOL)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeBoolForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Float +/** + * Class used for map fields of <NSString, float> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringFloatDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithFloat:(float)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithFloats:(const float [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringFloatDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithFloats:(const float [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringFloatDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getFloat:(nullable float *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndFloatsUsingBlock: (void (^)(NSString *key, float value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringFloatDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setFloat:(float)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeFloatForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Double +/** + * Class used for map fields of <NSString, double> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringDoubleDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param value The value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithDouble:(double)value forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param values The values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithDoubles:(const double [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringDoubleDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; +/** + * Initializes this dictionary, copying the given values and keys. + * + * @param values The values to be placed in this dictionary. + * @param keys The keys under which to store the values. + * @param count The number of elements to copy into the dictionary. + * + * @return A newly initialized dictionary with a copy of the values and keys. + **/ - (instancetype)initWithDoubles:(const double [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes this dictionary, copying the entries from the given dictionary. + * + * @param dictionary Dictionary containing the entries to add to this dictionary. + * + * @return A newly initialized dictionary with the entries of the given dictionary. + **/ - (instancetype)initWithDictionary:(GPBStringDoubleDictionary *)dictionary; + +/** + * Initializes this dictionary with the requested capacity. + * + * @param numItems Number of items needed for this dictionary. + * + * @return A newly initialized dictionary with the requested capacity. + **/ - (instancetype)initWithCapacity:(NSUInteger)numItems; -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getDouble:(nullable double *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndDoublesUsingBlock: (void (^)(NSString *key, double value, BOOL *stop))block; +/** + * Adds the keys and values from another dictionary. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addEntriesFromDictionary:(GPBStringDoubleDictionary *)otherDictionary; +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setDouble:(double)value forKey:(NSString *)key; +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeDoubleForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end #pragma mark - String -> Enum +/** + * Class used for map fields of <NSString, int32_t> + * values. This performs better than boxing into NSNumbers in NSDictionaries. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBStringEnumDictionary : NSObject <NSCopying> +/** Number of entries stored in this dictionary. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty dictionary. + **/ + (instancetype)dictionary; + +/** + * Creates and initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly instanced dictionary. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a dictionary with the single entry given. + * + * @param func The enum validation function for the dictionary. + * @param rawValue The raw enum value to be placed in the dictionary. + * @param key The key under which to store the value. + * + * @return A newly instanced dictionary with the key and value in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)rawValue forKey:(NSString *)key; + +/** + * Creates and initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly instanced dictionary with the keys and values in it. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count; + +/** + * Creates and initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly instanced dictionary with the entries from the given + * dictionary in it. + **/ + (instancetype)dictionaryWithDictionary:(GPBStringEnumDictionary *)dictionary; + +/** + * Creates and initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly instanced dictionary with the given capacity. + **/ + (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; +/** + * Initializes a dictionary with the given validation function. + * + * @param func The enum validation function for the dictionary. + * + * @return A newly initialized dictionary. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Initializes a dictionary with the entries given. + * + * @param func The enum validation function for the dictionary. + * @param values The raw enum values values to be placed in the dictionary. + * @param keys The keys under which to store the values. + * @param count The number of entries to store in the dictionary. + * + * @return A newly initialized dictionary with the keys and values in it. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values forKeys:(const NSString * GPB_UNSAFE_UNRETAINED [])keys count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; + +/** + * Initializes a dictionary with the entries from the given. + * dictionary. + * + * @param dictionary Dictionary containing the entries to add to the dictionary. + * + * @return A newly initialized dictionary with the entries from the given + * dictionary in it. + **/ - (instancetype)initWithDictionary:(GPBStringEnumDictionary *)dictionary; + +/** + * Initializes a dictionary with the given capacity. + * + * @param func The enum validation function for the dictionary. + * @param numItems Capacity needed for the dictionary. + * + * @return A newly initialized dictionary with the given capacity. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)numItems; @@ -2163,23 +8068,63 @@ NS_ASSUME_NONNULL_BEGIN // is not a valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the value for the given key. + * + * @param value Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getEnum:(nullable int32_t *)value forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **value**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndEnumsUsingBlock: (void (^)(NSString *key, int32_t value, BOOL *stop))block; -// These methods bypass the validationFunc to provide access to values that were not -// known at the time the binary was compiled. - -// Returns YES/NO to indicate if the key was found or not, filling in the value -// only when the key was found. +/** + * Gets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param rawValue Pointer into which the value will be set, if found. + * @param key Key under which the value is stored, if present. + * + * @return YES if the key was found and the value was copied, NO otherwise. + **/ - (BOOL)getRawValue:(nullable int32_t *)rawValue forKey:(NSString *)key; +/** + * Enumerates the keys and values on this dictionary with the given block. + * + * @note This method bypass the validationFunc to enable the access of values that + * were not known at the time the binary was compiled. + * + * @param block The block to enumerate with. + * **key**: The key for the current entry. + * **rawValue**: The value for the current entry + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateKeysAndRawValuesUsingBlock: (void (^)(NSString *key, int32_t rawValue, BOOL *stop))block; +/** + * Adds the keys and raw enum values from another dictionary. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param otherDictionary Dictionary containing entries to be added to this + * dictionary. + **/ - (void)addRawEntriesFromDictionary:(GPBStringEnumDictionary *)otherDictionary; // If value is not a valid enumerator as defined by validationFunc, these @@ -2187,15 +8132,35 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Sets the value for the given key. + * + * @param value The value to set. + * @param key The key under which to store the value. + **/ - (void)setEnum:(int32_t)value forKey:(NSString *)key; -// This method bypass the validationFunc to provide setting of values that were not -// known at the time the binary was compiled. +/** + * Sets the raw enum value for the given key. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param rawValue The raw enum value to set. + * @param key The key under which to store the raw enum value. + **/ - (void)setRawValue:(int32_t)rawValue forKey:(NSString *)key; -// No validation applies to these methods. - +/** + * Removes the entry for the given key. + * + * @param aKey Key to be removed from this dictionary. + **/ - (void)removeEnumForKey:(NSString *)aKey; + +/** + * Removes all entries in this dictionary. + **/ - (void)removeAll; @end @@ -2228,10 +8193,23 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE DICTIONARY_POD_KEY_TO_OBJECT_INTERFACE(KEY_NAME, KEY_TYPE, VALUE_NAME, VALUE_TYPE) //%DICTIONARY_COMMON_INTERFACE(KEY_NAME, KEY_TYPE, , POD, VALUE_NAME, VALUE_TYPE, OBJECT, Object, object) //%PDDM-DEFINE VALUE_FOR_KEY_POD(KEY_TYPE, VALUE_TYPE, VNAME) -//%// Returns YES/NO to indicate if the key was found or not, filling in the value -//%// only when the key was found. +//%/** +//% * Gets the value for the given key. +//% * +//% * @param value Pointer into which the value will be set, if found. +//% * @param key Key under which the value is stored, if present. +//% * +//% * @return YES if the key was found and the value was copied, NO otherwise. +//% **/ //%- (BOOL)get##VNAME##:(nullable VALUE_TYPE *)value forKey:(KEY_TYPE)key; //%PDDM-DEFINE VALUE_FOR_KEY_OBJECT(KEY_TYPE, VALUE_TYPE, VNAME) +//%/** +//% * Fetches the object stored under the given key. +//% * +//% * @param key Key under which the value is stored, if present. +//% * +//% * @return The object if found, nil otherwise. +//% **/ //%- (VALUE_TYPE)objectForKey:(KEY_TYPE)key; //%PDDM-DEFINE VALUE_FOR_KEY_Enum(KEY_TYPE, VALUE_TYPE, VNAME) //%VALUE_FOR_KEY_POD(KEY_TYPE, VALUE_TYPE, VNAME) @@ -2250,27 +8228,105 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE DICTIONARY_COMMON_INTERFACE(KEY_NAME, KEY_TYPE, KisP, KHELPER, VALUE_NAME, VALUE_TYPE, VHELPER, VNAME, VNAME_VAR) //%#pragma mark - KEY_NAME -> VALUE_NAME //% +//%/** +//% * Class used for map fields of <##KEY_TYPE##, ##VALUE_TYPE##> +//% * values. This performs better than boxing into NSNumbers in NSDictionaries. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface DICTIONARY_CLASS_DECL##VHELPER(KEY_NAME, VALUE_NAME, VALUE_TYPE) : NSObject <NSCopying> //% +//%/** Number of entries stored in this dictionary. */ //%@property(nonatomic, readonly) NSUInteger count; //% +//%/** +//% * @return A newly instanced and empty dictionary. +//% **/ //%+ (instancetype)dictionary; +//% +//%/** +//% * Creates and initializes a dictionary with the single entry given. +//% * +//% * @param ##VNAME_VAR The value to be placed in the dictionary. +//% * @param key ##VNAME_VAR$S## The key under which to store the value. +//% * +//% * @return A newly instanced dictionary with the key and value in it. +//% **/ //%+ (instancetype)dictionaryWith##VNAME##:(VALUE_TYPE)##VNAME_VAR //% ##VNAME$S## forKey:(KEY_TYPE##KisP$S##KisP)key; +//% +//%/** +//% * Creates and initializes a dictionary with the entries given. +//% * +//% * @param ##VNAME_VAR##s The values to be placed in the dictionary. +//% * @param keys ##VNAME_VAR$S## The keys under which to store the values. +//% * @param count ##VNAME_VAR$S## The number of entries to store in the dictionary. +//% * +//% * @return A newly instanced dictionary with the keys and values in it. +//% **/ //%+ (instancetype)dictionaryWith##VNAME##s:(const VALUE_TYPE ARRAY_ARG_MODIFIER##VHELPER()[])##VNAME_VAR##s //% ##VNAME$S## forKeys:(const KEY_TYPE##KisP$S##KisP ARRAY_ARG_MODIFIER##KHELPER()[])keys //% ##VNAME$S## count:(NSUInteger)count; +//% +//%/** +//% * Creates and initializes a dictionary with the entries from the given. +//% * dictionary. +//% * +//% * @param dictionary Dictionary containing the entries to add to the dictionary. +//% * +//% * @return A newly instanced dictionary with the entries from the given +//% * dictionary in it. +//% **/ //%+ (instancetype)dictionaryWithDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)dictionary; +//% +//%/** +//% * Creates and initializes a dictionary with the given capacity. +//% * +//% * @param numItems Capacity needed for the dictionary. +//% * +//% * @return A newly instanced dictionary with the given capacity. +//% **/ //%+ (instancetype)dictionaryWithCapacity:(NSUInteger)numItems; //% +//%/** +//% * Initializes this dictionary, copying the given values and keys. +//% * +//% * @param ##VNAME_VAR##s The values to be placed in this dictionary. +//% * @param keys ##VNAME_VAR$S## The keys under which to store the values. +//% * @param count ##VNAME_VAR$S## The number of elements to copy into the dictionary. +//% * +//% * @return A newly initialized dictionary with a copy of the values and keys. +//% **/ //%- (instancetype)initWith##VNAME##s:(const VALUE_TYPE ARRAY_ARG_MODIFIER##VHELPER()[])##VNAME_VAR##s //% ##VNAME$S## forKeys:(const KEY_TYPE##KisP$S##KisP ARRAY_ARG_MODIFIER##KHELPER()[])keys //% ##VNAME$S## count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; +//% +//%/** +//% * Initializes this dictionary, copying the entries from the given dictionary. +//% * +//% * @param dictionary Dictionary containing the entries to add to this dictionary. +//% * +//% * @return A newly initialized dictionary with the entries of the given dictionary. +//% **/ //%- (instancetype)initWithDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)dictionary; +//% +//%/** +//% * Initializes this dictionary with the requested capacity. +//% * +//% * @param numItems Number of items needed for this dictionary. +//% * +//% * @return A newly initialized dictionary with the requested capacity. +//% **/ //%- (instancetype)initWithCapacity:(NSUInteger)numItems; //% //%DICTIONARY_IMMUTABLE_INTERFACE(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE, VHELPER, VNAME, VNAME_VAR) //% +//%/** +//% * Adds the keys and values from another dictionary. +//% * +//% * @param otherDictionary Dictionary containing entries to be added to this +//% * dictionary. +//% **/ //%- (void)addEntriesFromDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)otherDictionary; //% //%DICTIONARY_MUTABLE_INTERFACE(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE, VHELPER, VNAME, VNAME_VAR) @@ -2283,30 +8339,126 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE DICTIONARY_KEY_TO_ENUM_INTERFACE2(KEY_NAME, KEY_TYPE, KisP, KHELPER, VALUE_NAME, VALUE_TYPE, VHELPER) //%#pragma mark - KEY_NAME -> VALUE_NAME //% +//%/** +//% * Class used for map fields of <##KEY_TYPE##, ##VALUE_TYPE##> +//% * values. This performs better than boxing into NSNumbers in NSDictionaries. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface GPB##KEY_NAME##VALUE_NAME##Dictionary : NSObject <NSCopying> //% +//%/** Number of entries stored in this dictionary. */ //%@property(nonatomic, readonly) NSUInteger count; +//%/** The validation function to check if the enums are valid. */ //%@property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; //% +//%/** +//% * @return A newly instanced and empty dictionary. +//% **/ //%+ (instancetype)dictionary; +//% +//%/** +//% * Creates and initializes a dictionary with the given validation function. +//% * +//% * @param func The enum validation function for the dictionary. +//% * +//% * @return A newly instanced dictionary. +//% **/ //%+ (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func; +//% +//%/** +//% * Creates and initializes a dictionary with the single entry given. +//% * +//% * @param func The enum validation function for the dictionary. +//% * @param rawValue The raw enum value to be placed in the dictionary. +//% * @param key The key under which to store the value. +//% * +//% * @return A newly instanced dictionary with the key and value in it. +//% **/ //%+ (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValue:(VALUE_TYPE)rawValue //% forKey:(KEY_TYPE##KisP$S##KisP)key; +//% +//%/** +//% * Creates and initializes a dictionary with the entries given. +//% * +//% * @param func The enum validation function for the dictionary. +//% * @param values The raw enum values values to be placed in the dictionary. +//% * @param keys The keys under which to store the values. +//% * @param count The number of entries to store in the dictionary. +//% * +//% * @return A newly instanced dictionary with the keys and values in it. +//% **/ //%+ (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValues:(const VALUE_TYPE ARRAY_ARG_MODIFIER##VHELPER()[])values //% forKeys:(const KEY_TYPE##KisP$S##KisP ARRAY_ARG_MODIFIER##KHELPER()[])keys //% count:(NSUInteger)count; +//% +//%/** +//% * Creates and initializes a dictionary with the entries from the given. +//% * dictionary. +//% * +//% * @param dictionary Dictionary containing the entries to add to the dictionary. +//% * +//% * @return A newly instanced dictionary with the entries from the given +//% * dictionary in it. +//% **/ //%+ (instancetype)dictionaryWithDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)dictionary; +//% +//%/** +//% * Creates and initializes a dictionary with the given capacity. +//% * +//% * @param func The enum validation function for the dictionary. +//% * @param numItems Capacity needed for the dictionary. +//% * +//% * @return A newly instanced dictionary with the given capacity. +//% **/ //%+ (instancetype)dictionaryWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)numItems; //% +//%/** +//% * Initializes a dictionary with the given validation function. +//% * +//% * @param func The enum validation function for the dictionary. +//% * +//% * @return A newly initialized dictionary. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func; +//% +//%/** +//% * Initializes a dictionary with the entries given. +//% * +//% * @param func The enum validation function for the dictionary. +//% * @param values The raw enum values values to be placed in the dictionary. +//% * @param keys The keys under which to store the values. +//% * @param count The number of entries to store in the dictionary. +//% * +//% * @return A newly initialized dictionary with the keys and values in it. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValues:(const VALUE_TYPE ARRAY_ARG_MODIFIER##VHELPER()[])values //% forKeys:(const KEY_TYPE##KisP$S##KisP ARRAY_ARG_MODIFIER##KHELPER()[])keys //% count:(NSUInteger)count NS_DESIGNATED_INITIALIZER; +//% +//%/** +//% * Initializes a dictionary with the entries from the given. +//% * dictionary. +//% * +//% * @param dictionary Dictionary containing the entries to add to the dictionary. +//% * +//% * @return A newly initialized dictionary with the entries from the given +//% * dictionary in it. +//% **/ //%- (instancetype)initWithDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)dictionary; +//% +//%/** +//% * Initializes a dictionary with the given capacity. +//% * +//% * @param func The enum validation function for the dictionary. +//% * @param numItems Capacity needed for the dictionary. +//% * +//% * @return A newly initialized dictionary with the given capacity. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)numItems; //% @@ -2316,16 +8468,42 @@ NS_ASSUME_NONNULL_END //% //%DICTIONARY_IMMUTABLE_INTERFACE(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE, VHELPER, Enum, value) //% -//%// These methods bypass the validationFunc to provide access to values that were not -//%// known at the time the binary was compiled. -//% -//%// Returns YES/NO to indicate if the key was found or not, filling in the value -//%// only when the key was found. +//%/** +//% * Gets the raw enum value for the given key. +//% * +//% * @note This method bypass the validationFunc to enable the access of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param rawValue Pointer into which the value will be set, if found. +//% * @param key Key under which the value is stored, if present. +//% * +//% * @return YES if the key was found and the value was copied, NO otherwise. +//% **/ //%- (BOOL)getRawValue:(nullable VALUE_TYPE *)rawValue forKey:(KEY_TYPE##KisP$S##KisP)key; //% +//%/** +//% * Enumerates the keys and values on this dictionary with the given block. +//% * +//% * @note This method bypass the validationFunc to enable the access of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param block The block to enumerate with. +//% * **key**: The key for the current entry. +//% * **rawValue**: The value for the current entry +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateKeysAndRawValuesUsingBlock: //% (void (^)(KEY_TYPE KisP##key, VALUE_TYPE rawValue, BOOL *stop))block; //% +//%/** +//% * Adds the keys and raw enum values from another dictionary. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param otherDictionary Dictionary containing entries to be added to this +//% * dictionary. +//% **/ //%- (void)addRawEntriesFromDictionary:(GPB##KEY_NAME##VALUE_NAME##Dictionary *)otherDictionary; //% //%// If value is not a valid enumerator as defined by validationFunc, these @@ -2341,13 +8519,36 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE DICTIONARY_IMMUTABLE_INTERFACE(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE, VHELPER, VNAME, VNAME_VAR) //%VALUE_FOR_KEY_##VHELPER(KEY_TYPE##KisP$S##KisP, VALUE_TYPE, VNAME) //% +//%/** +//% * Enumerates the keys and values on this dictionary with the given block. +//% * +//% * @param block The block to enumerate with. +//% * **key**: ##VNAME_VAR$S## The key for the current entry. +//% * **VNAME_VAR**: The value for the current entry +//% * **stop**: ##VNAME_VAR$S## A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateKeysAnd##VNAME##sUsingBlock: //% (void (^)(KEY_TYPE KisP##key, VALUE_TYPE VNAME_VAR, BOOL *stop))block; //%PDDM-DEFINE DICTIONARY_MUTABLE_INTERFACE(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE, VHELPER, VNAME, VNAME_VAR) +//%/** +//% * Sets the value for the given key. +//% * +//% * @param ##VNAME_VAR The value to set. +//% * @param key ##VNAME_VAR$S## The key under which to store the value. +//% **/ //%- (void)set##VNAME##:(VALUE_TYPE)##VNAME_VAR forKey:(KEY_TYPE##KisP$S##KisP)key; //%DICTIONARY_EXTRA_MUTABLE_METHODS_##VHELPER(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE) +//%/** +//% * Removes the entry for the given key. +//% * +//% * @param aKey Key to be removed from this dictionary. +//% **/ //%- (void)remove##VNAME##ForKey:(KEY_TYPE##KisP$S##KisP)aKey; +//% +//%/** +//% * Removes all entries in this dictionary. +//% **/ //%- (void)removeAll; //%PDDM-DEFINE DICTIONARY_EXTRA_MUTABLE_METHODS_POD(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE) @@ -2356,9 +8557,14 @@ NS_ASSUME_NONNULL_END // Empty //%PDDM-DEFINE DICTIONARY_EXTRA_MUTABLE_METHODS_Enum(KEY_NAME, KEY_TYPE, KisP, VALUE_NAME, VALUE_TYPE) //% -//%// This method bypass the validationFunc to provide setting of values that were not -//%// known at the time the binary was compiled. +//%/** +//% * Sets the raw enum value for the given key. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param rawValue The raw enum value to set. +//% * @param key The key under which to store the raw enum value. +//% **/ //%- (void)setRawValue:(VALUE_TYPE)rawValue forKey:(KEY_TYPE##KisP$S##KisP)key; //% -//%// No validation applies to these methods. -//% diff --git a/objectivec/GPBExtensionRegistry.h b/objectivec/GPBExtensionRegistry.h index 08a6472a..d79632d2 100644 --- a/objectivec/GPBExtensionRegistry.h +++ b/objectivec/GPBExtensionRegistry.h @@ -35,45 +35,50 @@ NS_ASSUME_NONNULL_BEGIN -/// A table of known extensions, searchable by name or field number. When -/// parsing a protocol message that might have extensions, you must provide a -/// @c GPBExtensionRegistry in which you have registered any extensions that you -/// want to be able to parse. Otherwise, those extensions will just be treated -/// like unknown fields. -/// -/// The @c *Root classes provide @c +extensionRegistry for the extensions defined -/// in a given file *and* all files it imports. You can also create a -/// @c GPBExtensionRegistry, and merge those registries to handle parsing -/// extensions defined from non overlapping files. -/// -/// @code -/// GPBExtensionRegistry *registry = -/// [[[MyProtoFileRoot extensionRegistry] copy] autorelease]; -/// [registry addExtension:[OtherMessage neededExtension]; // Not in MyProtoFile -/// NSError *parseError = nil; -/// MyMessage *msg = [MyMessage parseData:data -/// extensionRegistry:registry -/// error:&parseError]; -/// @endcode +/** + * A table of known extensions, searchable by name or field number. When + * parsing a protocol message that might have extensions, you must provide a + * GPBExtensionRegistry in which you have registered any extensions that you + * want to be able to parse. Otherwise, those extensions will just be treated + * like unknown fields. + * + * The *Root classes provide `+extensionRegistry` for the extensions defined + * in a given file *and* all files it imports. You can also create a + * GPBExtensionRegistry, and merge those registries to handle parsing + * extensions defined from non overlapping files. + * + * ``` + * GPBExtensionRegistry *registry = [[MyProtoFileRoot extensionRegistry] copy]; + * [registry addExtension:[OtherMessage neededExtension]]; // Not in MyProtoFile + * NSError *parseError; + * MyMessage *msg = [MyMessage parseData:data extensionRegistry:registry error:&parseError]; + * ``` + **/ @interface GPBExtensionRegistry : NSObject<NSCopying> -/// Add the given @c GPBExtensionDescriptor to this registry. -/// -/// @param extension The extension description to add. +/** + * Adds the given GPBExtensionDescriptor to this registry. + * + * @param extension The extension description to add. + **/ - (void)addExtension:(GPBExtensionDescriptor *)extension; -/// Adds all the extensions from another registry to this registry. -/// -/// @param registry The registry to merge into this registry. +/** + * Adds all the extensions from another registry to this registry. + * + * @param registry The registry to merge into this registry. + **/ - (void)addExtensions:(GPBExtensionRegistry *)registry; -/// Looks for the extension registered for the given field number on a given -/// @c GPBDescriptor. -/// -/// @param descriptor The descriptor to look for a registered extension on. -/// @param fieldNumber The field number of an extension to look for. -/// -/// @return The registered @c GPBExtensionDescripto or nil if none was found. +/** + * Looks for the extension registered for the given field number on a given + * GPBDescriptor. + * + * @param descriptor The descriptor to look for a registered extension on. + * @param fieldNumber The field number of the extension to look for. + * + * @return The registered GPBExtensionDescriptor or nil if none was found. + **/ - (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor fieldNumber:(NSInteger)fieldNumber; diff --git a/objectivec/GPBMessage.h b/objectivec/GPBMessage.h index 9608cdb0..0cb74f9f 100644 --- a/objectivec/GPBMessage.h +++ b/objectivec/GPBMessage.h @@ -44,282 +44,404 @@ NS_ASSUME_NONNULL_BEGIN CF_EXTERN_C_BEGIN -/// NSError domain used for errors. +/** NSError domain used for errors. */ extern NSString *const GPBMessageErrorDomain; -/// Error code for NSError with GPBMessageErrorDomain. +/** Error codes for NSErrors originated in GPBMessage. */ typedef NS_ENUM(NSInteger, GPBMessageErrorCode) { - /// Uncategorized error. + /** Uncategorized error. */ GPBMessageErrorCodeOther = -100, - /// A message can't be serialized because it is missing required fields. + /** Message couldn't be serialized because it is missing required fields. */ GPBMessageErrorCodeMissingRequiredField = -101, }; -/// Key under which the error's reason is stored inside the userInfo dictionary. +/** + * Key under which the GPBMessage error's reason is stored inside the userInfo + * dictionary. + **/ extern NSString *const GPBErrorReasonKey; CF_EXTERN_C_END -/// Base class for all of the generated message classes. +/** + * Base class that each generated message subclasses from. + **/ @interface GPBMessage : NSObject<NSSecureCoding, NSCopying> - -// NOTE: If you add a instance method/property to this class that may conflict -// with methods declared in protos, you need to update objective_helpers.cc. -// The main cases are methods that take no arguments, or setFoo:/hasFoo: type -// methods. - -/// The unknown fields for this message. -/// -/// Only messages from proto files declared with "proto2" syntax support unknown -/// fields. For "proto3" syntax, any unknown fields found while parsing are -/// dropped. + +// If you add an instance method/property to this class that may conflict with +// fields declared in protos, you need to update objective_helpers.cc. The main +// cases are methods that take no arguments, or setFoo:/hasFoo: type methods. + +/** + * The set of unknown fields for this message. + * + * Only messages from proto files declared with "proto2" syntax support unknown + * fields. For "proto3" syntax, any unknown fields found while parsing are + * dropped. + **/ @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields; -/// Are all required fields set in the message and all embedded messages. +/** + * Whether the message, along with all submessages, have the required fields + * set. This is only applicable for files declared with "proto2" syntax, as + * there are no required fields for "proto3" syntax. + **/ @property(nonatomic, readonly, getter=isInitialized) BOOL initialized; -/// Returns an autoreleased instance. +/** + * @return An autoreleased message with the default values set. + **/ + (instancetype)message; -/// Creates a new instance by parsing the data. This method should be sent to -/// the generated message class that the data should be interpreted as. If -/// there is an error the method returns nil and the error is returned in -/// errorPtr (when provided). -/// -/// @note In DEBUG builds, the parsed message is checked to be sure all required -/// fields were provided, and the parse will fail if some are missing. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param data The data to parse. -/// @param errorPtr An optional error pointer to fill in with a failure reason if -/// the data can not be parsed. -/// -/// @return A new instance of the class messaged. +/** + * Creates a new instance by parsing the provided data. This method should be + * sent to the generated message class that the data should be interpreted as. + * If there is an error the method returns nil and the error is returned in + * errorPtr (when provided). + * + * @note In DEBUG builds, the parsed message is checked to be sure all required + * fields were provided, and the parse will fail if some are missing. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param data The data to parse. + * @param errorPtr An optional error pointer to fill in with a failure reason if + * the data can not be parsed. + * + * @return A new instance of the generated class. + **/ + (nullable instancetype)parseFromData:(NSData *)data error:(NSError **)errorPtr; -/// Creates a new instance by parsing the data. This method should be sent to -/// the generated message class that the data should be interpreted as. If -/// there is an error the method returns nil and the error is returned in -/// errorPtr (when provided). -/// -/// @note In DEBUG builds, the parsed message is checked to be sure all required -/// fields were provided, and the parse will fail if some are missing. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param data The data to parse. -/// @param extensionRegistry The extension registry to use to look up extensions. -/// @param errorPtr An optional error pointer to fill in with a failure -/// reason if the data can not be parsed. -/// -/// @return A new instance of the class messaged. +/** + * Creates a new instance by parsing the data. This method should be sent to + * the generated message class that the data should be interpreted as. If + * there is an error the method returns nil and the error is returned in + * errorPtr (when provided). + * + * @note In DEBUG builds, the parsed message is checked to be sure all required + * fields were provided, and the parse will fail if some are missing. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param data The data to parse. + * @param extensionRegistry The extension registry to use to look up extensions. + * @param errorPtr An optional error pointer to fill in with a failure + * reason if the data can not be parsed. + * + * @return A new instance of the generated class. + **/ + (nullable instancetype)parseFromData:(NSData *)data extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -/// Creates a new instance by parsing the data from the given input stream. This -/// method should be sent to the generated message class that the data should -/// be interpreted as. If there is an error the method returns nil and the error -/// is returned in errorPtr (when provided). -/// -/// @note In DEBUG builds, the parsed message is checked to be sure all required -/// fields were provided, and the parse will fail if some are missing. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param input The stream to read data from. -/// @param extensionRegistry The extension registry to use to look up extensions. -/// @param errorPtr An optional error pointer to fill in with a failure -/// reason if the data can not be parsed. -/// -/// @return A new instance of the class messaged. +/** + * Creates a new instance by parsing the data from the given input stream. This + * method should be sent to the generated message class that the data should + * be interpreted as. If there is an error the method returns nil and the error + * is returned in errorPtr (when provided). + * + * @note In DEBUG builds, the parsed message is checked to be sure all required + * fields were provided, and the parse will fail if some are missing. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param input The stream to read data from. + * @param extensionRegistry The extension registry to use to look up extensions. + * @param errorPtr An optional error pointer to fill in with a failure + * reason if the data can not be parsed. + * + * @return A new instance of the generated class. + **/ + (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -/// Creates a new instance by parsing the data from the given input stream. This -/// method should be sent to the generated message class that the data should -/// be interpreted as. If there is an error the method returns nil and the error -/// is returned in errorPtr (when provided). -/// -/// @note Unlike the parseFrom... methods, this never checks to see if all of -/// the required fields are set. So this method can be used to reload -/// messages that may not be complete. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param input The stream to read data from. -/// @param extensionRegistry The extension registry to use to look up extensions. -/// @param errorPtr An optional error pointer to fill in with a failure -/// reason if the data can not be parsed. -/// -/// @return A new instance of the class messaged. +/** + * Creates a new instance by parsing the data from the given input stream. This + * method should be sent to the generated message class that the data should + * be interpreted as. If there is an error the method returns nil and the error + * is returned in errorPtr (when provided). + * + * @note Unlike the parseFrom... methods, this never checks to see if all of + * the required fields are set. So this method can be used to reload + * messages that may not be complete. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param input The stream to read data from. + * @param extensionRegistry The extension registry to use to look up extensions. + * @param errorPtr An optional error pointer to fill in with a failure + * reason if the data can not be parsed. + * + * @return A new instance of the generated class. + **/ + (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -/// Initializes an instance by parsing the data. This method should be sent to -/// the generated message class that the data should be interpreted as. If -/// there is an error the method returns nil and the error is returned in -/// errorPtr (when provided). -/// -/// @note In DEBUG builds, the parsed message is checked to be sure all required -/// fields were provided, and the parse will fail if some are missing. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param data The data to parse. -/// @param errorPtr An optional error pointer to fill in with a failure reason if -/// the data can not be parsed. +/** + * Initializes an instance by parsing the data. This method should be sent to + * the generated message class that the data should be interpreted as. If + * there is an error the method returns nil and the error is returned in + * errorPtr (when provided). + * + * @note In DEBUG builds, the parsed message is checked to be sure all required + * fields were provided, and the parse will fail if some are missing. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param data The data to parse. + * @param errorPtr An optional error pointer to fill in with a failure reason if + * the data can not be parsed. + * + * @return An initialized instance of the generated class. + **/ - (nullable instancetype)initWithData:(NSData *)data error:(NSError **)errorPtr; -/// Initializes an instance by parsing the data. This method should be sent to -/// the generated message class that the data should be interpreted as. If -/// there is an error the method returns nil and the error is returned in -/// errorPtr (when provided). -/// -/// @note In DEBUG builds, the parsed message is checked to be sure all required -/// fields were provided, and the parse will fail if some are missing. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param data The data to parse. -/// @param extensionRegistry The extension registry to use to look up extensions. -/// @param errorPtr An optional error pointer to fill in with a failure -/// reason if the data can not be parsed. +/** + * Initializes an instance by parsing the data. This method should be sent to + * the generated message class that the data should be interpreted as. If + * there is an error the method returns nil and the error is returned in + * errorPtr (when provided). + * + * @note In DEBUG builds, the parsed message is checked to be sure all required + * fields were provided, and the parse will fail if some are missing. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param data The data to parse. + * @param extensionRegistry The extension registry to use to look up extensions. + * @param errorPtr An optional error pointer to fill in with a failure + * reason if the data can not be parsed. + * + * @return An initialized instance of the generated class. + **/ - (nullable instancetype)initWithData:(NSData *)data extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -/// Initializes an instance by parsing the data from the given input stream. This -/// method should be sent to the generated message class that the data should -/// be interpreted as. If there is an error the method returns nil and the error -/// is returned in errorPtr (when provided). -/// -/// @note Unlike the parseFrom... methods, this never checks to see if all of -/// the required fields are set. So this method can be used to reload -/// messages that may not be complete. -/// -/// @note The errors returned are likely coming from the domain and codes listed -/// at the top of this file and GPBCodedInputStream.h. -/// -/// @param input The stream to read data from. -/// @param extensionRegistry The extension registry to use to look up extensions. -/// @param errorPtr An optional error pointer to fill in with a failure -/// reason if the data can not be parsed. +/** + * Initializes an instance by parsing the data from the given input stream. This + * method should be sent to the generated message class that the data should + * be interpreted as. If there is an error the method returns nil and the error + * is returned in errorPtr (when provided). + * + * @note Unlike the parseFrom... methods, this never checks to see if all of + * the required fields are set. So this method can be used to reload + * messages that may not be complete. + * + * @note The errors returned are likely coming from the domain and codes listed + * at the top of this file and GPBCodedInputStream.h. + * + * @param input The stream to read data from. + * @param extensionRegistry The extension registry to use to look up extensions. + * @param errorPtr An optional error pointer to fill in with a failure + * reason if the data can not be parsed. + * + * @return An initialized instance of the generated class. + **/ - (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -/// Writes out the message to the given output stream. +/** + * Parses the given data as this message's class, and merges those values into + * this message. + * + * @param data The binary representation of the message to merge. + * @param extensionRegistry The extension registry to use to look up extensions. + * + * @exception GPBCodedInputStreamException Exception thrown when parsing was + * unsuccessful. + **/ +- (void)mergeFromData:(NSData *)data + extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; + +/** + * Merges the fields from another message (of the same type) into this + * message. + * + * @param other Message to merge into this message. + **/ +- (void)mergeFrom:(GPBMessage *)other; + +/** + * Writes out the message to the given coded output stream. + * + * @param output The coded output stream into which to write the message. + **/ - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output; -/// Writes out the message to the given output stream. + +/** + * Writes out the message to the given output stream. + * + * @param output The output stream into which to write the message. + **/ - (void)writeToOutputStream:(NSOutputStream *)output; -/// Writes out a varint for the message size followed by the the message to -/// the given output stream. +/** + * Writes out a varint for the message size followed by the the message to + * the given output stream. + * + * @param output The coded output stream into which to write the message. + **/ - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output; -/// Writes out a varint for the message size followed by the the message to -/// the given output stream. + +/** + * Writes out a varint for the message size followed by the the message to + * the given output stream. + * + * @param output The output stream into which to write the message. + **/ - (void)writeDelimitedToOutputStream:(NSOutputStream *)output; -/// Serializes the message to a @c NSData. -/// -/// If there is an error while generating the data, nil is returned. -/// -/// @note This value is not cached, so if you are using it repeatedly, cache -/// it yourself. -/// -/// @note In DEBUG ONLY, the message is also checked for all required field, -/// if one is missing, nil will be returned. +/** + * Serializes the message to an NSData. + * + * If there is an error while generating the data, nil is returned. + * + * @note This value is not cached, so if you are using it repeatedly, cache + * it yourself. + * + * @note In DEBUG ONLY, the message is also checked for all required field, + * if one is missing, nil will be returned. + * + * @return The binary representation of the message. + **/ - (nullable NSData *)data; -/// Serializes a varint with the message size followed by the message data, -/// returning that as a @c NSData. -/// -/// @note This value is not cached, so if you are using it repeatedly, cache -/// it yourself. +/** + * Serializes a varint with the message size followed by the message data, + * returning that as an NSData. + * + * @note This value is not cached, so if you are using it repeatedly, it is + * recommended to keep a local copy. + * + * @return The binary representation of the size along with the message. + **/ - (NSData *)delimitedData; -/// Calculates the size of the object if it were serialized. -/// -/// This is not a cached value. If you are following a pattern like this: -/// @code -/// size_t size = [aMsg serializedSize]; -/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; -/// [foo writeSize:size]; -/// [foo appendData:[aMsg data]]; -/// @endcode -/// you would be better doing: -/// @code -/// NSData *data = [aMsg data]; -/// NSUInteger size = [aMsg length]; -/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; -/// [foo writeSize:size]; -/// [foo appendData:data]; -/// @endcode +/** + * Calculates the size of the object if it were serialized. + * + * This is not a cached value. If you are following a pattern like this: + * + * ``` + * size_t size = [aMsg serializedSize]; + * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; + * [foo writeSize:size]; + * [foo appendData:[aMsg data]]; + * ``` + * + * you would be better doing: + * + * ``` + * NSData *data = [aMsg data]; + * NSUInteger size = [aMsg length]; + * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; + * [foo writeSize:size]; + * [foo appendData:data]; + * ``` + * + * @return The size of the message in it's binary representation. + **/ - (size_t)serializedSize; -/// Return the descriptor for the message class. +/** + * @return The descriptor for the message class. + **/ + (GPBDescriptor *)descriptor; -/// Return the descriptor for the message. + +/** + * Return the descriptor for the message. + **/ - (GPBDescriptor *)descriptor; -/// Test to see if the given extension is set on the message. +/** + * @return An array with the extension descriptors that are currently set on the + * message. + **/ +- (NSArray *)extensionsCurrentlySet; + +/** + * Checks whether there is an extension set on the message which matches the + * given extension descriptor. + * + * @param extension Extension descriptor to check if it's set on the message. + * + * @return Whether the extension is currently set on the message. + **/ - (BOOL)hasExtension:(GPBExtensionDescriptor *)extension; -/// Fetches the given extension's value for this message. -/// -/// Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for -/// repeated fields. If the extension is a Message one will be auto created for you -/// and returned similar to fields. +/* + * Fetches the given extension's value for this message. + * + * Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for + * repeated fields. If the extension is a Message one will be auto created for + * you and returned similar to fields. + * + * @param extension The extension descriptor of the extension to fetch. + * + * @return The extension matching the given descriptor, or nil if none found. + **/ - (nullable id)getExtension:(GPBExtensionDescriptor *)extension; -/// Sets the given extension's value for this message. This is only for single -/// field extensions (i.e. - not repeated fields). -/// -/// Extensions use boxed values (@c NSNumbers). -- (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value; - -/// Adds the given value to the extension for this message. This is only for -/// repeated field extensions. If the field is a repeated POD type the @c value -/// is a @c NSNumber. +/** + * Sets the given extension's value for this message. This only applies for + * single field extensions (i.e. - not repeated fields). + * + * Extensions use boxed values (NSNumbers). + * + * @param extension The extension descriptor under which to set the value. + * @param value The value to be set as the extension. + **/ +- (void)setExtension:(GPBExtensionDescriptor *)extension + value:(nullable id)value; + +/** + * Adds the given value to the extension for this message. This only applies + * to repeated field extensions. If the field is a repeated POD type, the value + * should be an NSNumber. + * + * @param extension The extension descriptor under which to add the value. + * @param value The value to be added to the repeated extension. + **/ - (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value; -/// Replaces the given value at an index for the extension on this message. This -/// is only for repeated field extensions. If the field is a repeated POD type -/// the @c value is a @c NSNumber. +/** + * Replaces the value at the given index with the given value for the extension + * on this message. This only applies to repeated field extensions. If the field + * is a repeated POD type, the value is should be an NSNumber. + * + * @param extension The extension descriptor under which to replace the value. + * @param index The index of the extension to be replaced. + * @param value The value to be replaced in the repeated extension. + **/ - (void)setExtension:(GPBExtensionDescriptor *)extension index:(NSUInteger)index value:(id)value; -/// Clears the given extension for this message. +/** + * Clears the given extension for this message. + * + * @param extension The extension descriptor to be cleared from this message. + **/ - (void)clearExtension:(GPBExtensionDescriptor *)extension; -/// Resets all of the fields of this message to their default values. +/** + * Resets all of the fields of this message to their default values. + **/ - (void)clear; -/// Parses a message of this type from the input and merges it with this -/// message. -/// -/// @note This will throw if there is an error parsing the data. -- (void)mergeFromData:(NSData *)data - extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; - -/// Merges the fields from another message (of the same type) into this -/// message. -- (void)mergeFrom:(GPBMessage *)other; - @end NS_ASSUME_NONNULL_END diff --git a/objectivec/GPBMessage.m b/objectivec/GPBMessage.m index b9566bdf..4a6f0612 100644 --- a/objectivec/GPBMessage.m +++ b/objectivec/GPBMessage.m @@ -1777,11 +1777,6 @@ static GPBUnknownFieldSet *GetOrMakeUnknownFields(GPBMessage *self) { } } -- (NSArray *)sortedExtensionsInUse { - return [[extensionMap_ allKeys] - sortedArrayUsingSelector:@selector(compareByFieldNumber:)]; -} - - (void)setExtension:(GPBExtensionDescriptor *)extension value:(id)value { if (!value) { [self clearExtension:extension]; diff --git a/objectivec/GPBMessage_PackagePrivate.h b/objectivec/GPBMessage_PackagePrivate.h index ff3cd6eb..02d0e16e 100644 --- a/objectivec/GPBMessage_PackagePrivate.h +++ b/objectivec/GPBMessage_PackagePrivate.h @@ -78,10 +78,6 @@ typedef struct GPBMessage_Storage *GPBMessage_StoragePtr; // returns nil if the extension is not set) - (id)getExistingExtension:(GPBExtensionDescriptor *)extension; -// Returns an array of GPBExtensionDescriptor* for all the extensions currently -// in use on the message. They are sorted by field number. -- (NSArray *)sortedExtensionsInUse; - // Parses a message of this type from the input and merges it with this // message. // diff --git a/objectivec/GPBRootObject.h b/objectivec/GPBRootObject.h index c05b5c62..d2e2aebf 100644 --- a/objectivec/GPBRootObject.h +++ b/objectivec/GPBRootObject.h @@ -34,12 +34,17 @@ NS_ASSUME_NONNULL_BEGIN -/// Every generated proto file defines a local "Root" class that exposes a -/// @c GPBExtensionRegistry for all the extensions defined by that file and -/// the files it depends on. +/** + * Every generated proto file defines a local "Root" class that exposes a + * GPBExtensionRegistry for all the extensions defined by that file and + * the files it depends on. + **/ @interface GPBRootObject : NSObject -/// An extension registry for the given file and all the files it depends on. +/** + * @return An extension registry for the given file and all the files it depends + * on. + **/ + (GPBExtensionRegistry *)extensionRegistry; @end diff --git a/objectivec/GPBRuntimeTypes.h b/objectivec/GPBRuntimeTypes.h index 0a38b110..4d552060 100644 --- a/objectivec/GPBRuntimeTypes.h +++ b/objectivec/GPBRuntimeTypes.h @@ -36,21 +36,28 @@ @class GPBMessage; @class GPBInt32Array; -// Function used to verify that a given value can be represented by an -// enum type. +/** + * Verifies that a given value can be represented by an enum type. + * */ typedef BOOL (*GPBEnumValidationFunc)(int32_t); -// Function used to fetch an EnumDescriptor. +/** + * Fetches an EnumDescriptor. + * */ typedef GPBEnumDescriptor *(*GPBEnumDescriptorFunc)(void); -// Magic values used for when an the at runtime to indicate an enum value -// that wasn't know at compile time. +/** + * Magic value used at runtime to indicate an enum value that wasn't know at + * compile time. + * */ enum { kGPBUnrecognizedEnumeratorValue = (int32_t)0xFBADBEEF, }; -// A union for storing all possible Protobuf values. -// Note that owner is responsible for memory management of object types. +/** + * A union for storing all possible Protobuf values. Note that owner is + * responsible for memory management of object types. + * */ typedef union { BOOL valueBool; int32_t valueInt32; @@ -65,38 +72,73 @@ typedef union { int32_t valueEnum; } GPBGenericValue; -// Do not change the order of this enum (or add things to it) without thinking -// about it very carefully. There are several things that depend on the order. +/** + * Enum listing the possible data types that a field can contain. + * + * @note Do not change the order of this enum (or add things to it) without + * thinking about it very carefully. There are several things that depend + * on the order. + * */ typedef NS_ENUM(uint8_t, GPBDataType) { + /** Field contains boolean value(s). */ GPBDataTypeBool = 0, + /** Field contains unsigned 4 byte value(s). */ GPBDataTypeFixed32, + /** Field contains signed 4 byte value(s). */ GPBDataTypeSFixed32, + /** Field contains float value(s). */ GPBDataTypeFloat, + /** Field contains unsigned 8 byte value(s). */ GPBDataTypeFixed64, + /** Field contains signed 8 byte value(s). */ GPBDataTypeSFixed64, + /** Field contains double value(s). */ GPBDataTypeDouble, + /** + * Field contains variable length value(s). Inefficient for encoding negative + * numbers – if your field is likely to have negative values, use + * GPBDataTypeSInt32 instead. + **/ GPBDataTypeInt32, + /** + * Field contains variable length value(s). Inefficient for encoding negative + * numbers – if your field is likely to have negative values, use + * GPBDataTypeSInt64 instead. + **/ GPBDataTypeInt64, + /** Field contains signed variable length integer value(s). */ GPBDataTypeSInt32, + /** Field contains signed variable length integer value(s). */ GPBDataTypeSInt64, + /** Field contains unsigned variable length integer value(s). */ GPBDataTypeUInt32, + /** Field contains unsigned variable length integer value(s). */ GPBDataTypeUInt64, + /** Field contains an arbitrary sequence of bytes. */ GPBDataTypeBytes, + /** Field contains UTF-8 encoded or 7-bit ASCII text. */ GPBDataTypeString, + /** Field contains message type(s). */ GPBDataTypeMessage, + /** Field contains message type(s). */ GPBDataTypeGroup, + /** Field contains enum value(s). */ GPBDataTypeEnum, }; enum { - // A count of the number of types in GPBDataType. Separated out from the - // GPBDataType enum to avoid warnings regarding not handling - // GPBDataType_Count in switch statements. + /** + * A count of the number of types in GPBDataType. Separated out from the + * GPBDataType enum to avoid warnings regarding not handling GPBDataType_Count + * in switch statements. + **/ GPBDataType_Count = GPBDataTypeEnum + 1 }; -// An extension range. +/** An extension range. */ typedef struct GPBExtensionRange { - uint32_t start; // inclusive - uint32_t end; // exclusive + /** Inclusive. */ + uint32_t start; + /** Exclusive. */ + uint32_t end; } GPBExtensionRange; diff --git a/objectivec/GPBUnknownField.h b/objectivec/GPBUnknownField.h index 0f301e47..a135cc20 100644 --- a/objectivec/GPBUnknownField.h +++ b/objectivec/GPBUnknownField.h @@ -36,52 +36,59 @@ @class GPBUnknownFieldSet; NS_ASSUME_NONNULL_BEGIN - -/// Store an unknown field. These are used in conjunction with @c GPBUnknownFieldSet +/** + * Store an unknown field. These are used in conjunction with + * GPBUnknownFieldSet. + **/ @interface GPBUnknownField : NSObject<NSCopying> -/// The field number the data is stored under. +/** The field number the data is stored under. */ @property(nonatomic, readonly, assign) int32_t number; -/// An array of varint values for this field. +/** An array of varint values for this field. */ @property(nonatomic, readonly, strong) GPBUInt64Array *varintList; -/// An array of fixed32 values for this field. +/** An array of fixed32 values for this field. */ @property(nonatomic, readonly, strong) GPBUInt32Array *fixed32List; -/// An array of fixed64 values for this field. +/** An array of fixed64 values for this field. */ @property(nonatomic, readonly, strong) GPBUInt64Array *fixed64List; -/// An array of data values for this field. +/** An array of data values for this field. */ @property(nonatomic, readonly, strong) NSArray<NSData*> *lengthDelimitedList; -/// An array of groups of values for this field. +/** An array of groups of values for this field. */ @property(nonatomic, readonly, strong) NSArray<GPBUnknownFieldSet*> *groupList; - -/// Add a value to the varintList. -/// -/// @param value The value to add. +/** + * Add a value to the varintList. + * + * @param value The value to add. + **/ - (void)addVarint:(uint64_t)value; - -/// Add a value to the fixed32List. -/// -/// @param value The value to add. +/** + * Add a value to the fixed32List. + * + * @param value The value to add. + **/ - (void)addFixed32:(uint32_t)value; - -/// Add a value to the fixed64List. -/// -/// @param value The value to add. +/** + * Add a value to the fixed64List. + * + * @param value The value to add. + **/ - (void)addFixed64:(uint64_t)value; - -/// Add a value to the lengthDelimitedList. -/// -/// @param value The value to add. +/** + * Add a value to the lengthDelimitedList. + * + * @param value The value to add. + **/ - (void)addLengthDelimited:(NSData *)value; - -/// Add a value to the groupList. -/// -/// @param value The value to add. +/** + * Add a value to the groupList. + * + * @param value The value to add. + **/ - (void)addGroup:(GPBUnknownFieldSet *)value; @end diff --git a/objectivec/GPBUnknownFieldSet.h b/objectivec/GPBUnknownFieldSet.h index cf612993..1b5f24f3 100644 --- a/objectivec/GPBUnknownFieldSet.h +++ b/objectivec/GPBUnknownFieldSet.h @@ -34,31 +34,48 @@ NS_ASSUME_NONNULL_BEGIN -/// A collection of unknown fields. +/** + * A collection of unknown fields. Fields parsed from the binary representation + * of a message that are unknown end up in an instance of this set. This only + * applies for files declared with the "proto2" syntax. Files declared with the + * "proto3" syntax discard the unknown values. + **/ @interface GPBUnknownFieldSet : NSObject<NSCopying> -/// Tests to see if the given field number has a value. -/// -/// @param number The field number to check. -/// -/// @return YES if there is an unknown field for the given field number. +/** + * Tests to see if the given field number has a value. + * + * @param number The field number to check. + * + * @return YES if there is an unknown field for the given field number. + **/ - (BOOL)hasField:(int32_t)number; -/// Fetches the @c GPBUnknownField for the given field number. -/// -/// @param number The field number to look up. -/// -/// @return The @c GPBUnknownField or nil. +/** + * Fetches the GPBUnknownField for the given field number. + * + * @param number The field number to look up. + * + * @return The GPBUnknownField or nil if none found. + **/ - (nullable GPBUnknownField *)getField:(int32_t)number; -/// Returns the number of fields in this set. +/** + * @return The number of fields in this set. + **/ - (NSUInteger)countOfFields; -/// Adds the given field to the set. +/** + * Adds the given field to the set. + * + * @param field The field to add to the set. + **/ - (void)addField:(GPBUnknownField *)field; -/// Returns an NSArray of the @c GPBUnknownFields sorted by the field numbers. -- (NSArray<GPBUnknownField*> *)sortedFields; +/** + * @return An array of the GPBUnknownFields sorted by the field numbers. + **/ +- (NSArray<GPBUnknownField *> *)sortedFields; @end diff --git a/objectivec/GPBUtilities.h b/objectivec/GPBUtilities.h index b7209324..52e7d2e0 100644 --- a/objectivec/GPBUtilities.h +++ b/objectivec/GPBUtilities.h @@ -38,34 +38,58 @@ CF_EXTERN_C_BEGIN NS_ASSUME_NONNULL_BEGIN -/// Generates a string that should be a valid "Text Format" for the C++ version -/// of Protocol Buffers. -/// -/// @param message The message to generate from. -/// @param lineIndent A string to use as the prefix for all lines generated. Can -/// be nil if no extra indent is needed. -/// -/// @return A @c NSString with the Text Format of the message. +/** + * Generates a string that should be a valid "TextFormat" for the C++ version + * of Protocol Buffers. + * + * @param message The message to generate from. + * @param lineIndent A string to use as the prefix for all lines generated. Can + * be nil if no extra indent is needed. + * + * @return An NSString with the TextFormat of the message. + **/ NSString *GPBTextFormatForMessage(GPBMessage *message, NSString * __nullable lineIndent); -/// Generates a string that should be a valid "Text Format" for the C++ version -/// of Protocol Buffers. -/// -/// @param unknownSet The unknown field set to generate from. -/// @param lineIndent A string to use as the prefix for all lines generated. Can -/// be nil if no extra indent is needed. -/// -/// @return A @c NSString with the Text Format of the unknown field set. +/** + * Generates a string that should be a valid "TextFormat" for the C++ version + * of Protocol Buffers. + * + * @param unknownSet The unknown field set to generate from. + * @param lineIndent A string to use as the prefix for all lines generated. Can + * be nil if no extra indent is needed. + * + * @return An NSString with the TextFormat of the unknown field set. + **/ NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet, NSString * __nullable lineIndent); -/// Test if the given field is set on a message. +/** + * Checks if the given field number is set on a message. + * + * @param self The message to check. + * @param fieldNumber The field number to check. + * + * @return YES if the field number is set on the given message. + **/ BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber); -/// Test if the given field is set on a message. + +/** + * Checks if the given field is set on a message. + * + * @param self The message to check. + * @param field The field to check. + * + * @return YES if the field is set on the given message. + **/ BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field); -/// Clear the given field of a message. +/** + * Clears the given field for the given message. + * + * @param self The message for which to clear the field. + * @param field The field to clear. + **/ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field); //%PDDM-EXPAND GPB_ACCESSORS() @@ -73,112 +97,299 @@ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field); // -// Get/Set the given field of a message. +// Get/Set a given field from/to a message. // // Single Fields -/// Gets the value of a bytes field. +/** + * Gets the value of a bytes field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a bytes field. + +/** + * Sets the value of a bytes field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value); -/// Gets the value of a string field. +/** + * Gets the value of a string field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a string field. + +/** + * Sets the value of a string field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value); -/// Gets the value of a message field. +/** + * Gets the value of a message field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a message field. + +/** + * Sets the value of a message field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value); -/// Gets the value of a group field. +/** + * Gets the value of a group field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a group field. + +/** + * Sets the value of a group field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value); -/// Gets the value of a bool field. +/** + * Gets the value of a bool field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a bool field. + +/** + * Sets the value of a bool field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value); -/// Gets the value of an int32 field. +/** + * Gets the value of an int32 field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of an int32 field. + +/** + * Sets the value of an int32 field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); -/// Gets the value of an uint32 field. +/** + * Gets the value of an uint32 field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of an uint32 field. + +/** + * Sets the value of an uint32 field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value); -/// Gets the value of an int64 field. +/** + * Gets the value of an int64 field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of an int64 field. + +/** + * Sets the value of an int64 field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value); -/// Gets the value of an uint64 field. +/** + * Gets the value of an uint64 field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of an uint64 field. + +/** + * Sets the value of an uint64 field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value); -/// Gets the value of a float field. +/** + * Gets the value of a float field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a float field. + +/** + * Sets the value of a float field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value); -/// Gets the value of a double field. +/** + * Gets the value of a double field. + * + * @param self The message from which to get the field. + * @param field The field to get. + **/ double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a double field. + +/** + * Sets the value of a double field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The to set in the field. + **/ void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value); -/// Get the given enum field of a message. For proto3, if the value isn't a -/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned. -/// GPBGetMessageRawEnumField will bypass the check and return whatever value -/// was set. +/** + * Gets the given enum field of a message. For proto3, if the value isn't a + * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned. + * GPBGetMessageRawEnumField will bypass the check and return whatever value + * was set. + * + * @param self The message from which to get the field. + * @param field The field to get. + * + * @return The enum value for the given field. + **/ int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field); -/// Set the given enum field of a message. You can only set values that are -/// members of the enum. -void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); -/// Get the given enum field of a message. No check is done to ensure the value -/// was defined in the enum. + +/** + * Set the given enum field of a message. You can only set values that are + * members of the enum. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The enum value to set in the field. + **/ +void GPBSetMessageEnumField(GPBMessage *self, + GPBFieldDescriptor *field, + int32_t value); + +/** + * Get the given enum field of a message. No check is done to ensure the value + * was defined in the enum. + * + * @param self The message from which to get the field. + * @param field The field to get. + * + * @return The raw enum value for the given field. + **/ int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field); -/// Set the given enum field of a message. You can set the value to anything, -/// even a value that is not a member of the enum. -void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); + +/** + * Set the given enum field of a message. You can set the value to anything, + * even a value that is not a member of the enum. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param value The raw enum value to set in the field. + **/ +void GPBSetMessageRawEnumField(GPBMessage *self, + GPBFieldDescriptor *field, + int32_t value); // Repeated Fields -/// Gets the value of a repeated field. -/// -/// The result will be @c GPB*Array or @c NSMutableArray based on the -/// field's type. +/** + * Gets the value of a repeated field. + * + * @param self The message from which to get the field. + * @param field The repeated field to get. + * + * @return A GPB*Array or an NSMutableArray based on the field's type. + **/ id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a repeated field. -/// -/// The value should be @c GPB*Array or @c NSMutableArray based on the -/// field's type. -void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array); + +/** + * Sets the value of a repeated field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param array A GPB*Array or NSMutableArray based on the field's type. + **/ +void GPBSetMessageRepeatedField(GPBMessage *self, + GPBFieldDescriptor *field, + id array); // Map Fields -/// Gets the value of a map<> field. -/// -/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on -/// the field's type. +/** + * Gets the value of a map<> field. + * + * @param self The message from which to get the field. + * @param field The repeated field to get. + * + * @return A GPB*Dictionary or NSMutableDictionary based on the field's type. + **/ id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field); -/// Sets the value of a map<> field. -/// -/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based -/// on the field's type. -void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary); + +/** + * Sets the value of a map<> field. + * + * @param self The message into which to set the field. + * @param field The field to set. + * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the + * field's type. + **/ +void GPBSetMessageMapField(GPBMessage *self, + GPBFieldDescriptor *field, + id dictionary); //%PDDM-EXPAND-END GPB_ACCESSORS() -// Returns an empty NSData to assign to byte fields when you wish -// to assign them to empty. Prevents allocating a lot of little [NSData data] -// objects. +/** + * Returns an empty NSData to assign to byte fields when you wish to assign them + * to empty. Prevents allocating a lot of little [NSData data] objects. + **/ NSData *GPBEmptyNSData(void) __attribute__((pure)); NS_ASSUME_NONNULL_END @@ -189,7 +400,7 @@ CF_EXTERN_C_END //%PDDM-DEFINE GPB_ACCESSORS() //% //%// -//%// Get/Set the given field of a message. +//%// Get/Set a given field from/to a message. //%// //% //%// Single Fields @@ -205,53 +416,119 @@ CF_EXTERN_C_END //%GPB_ACCESSOR_SINGLE(UInt64, uint64_t, n) //%GPB_ACCESSOR_SINGLE(Float, float, ) //%GPB_ACCESSOR_SINGLE(Double, double, ) -//%/// Get the given enum field of a message. For proto3, if the value isn't a -//%/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned. -//%/// GPBGetMessageRawEnumField will bypass the check and return whatever value -//%/// was set. +//%/** +//% * Gets the given enum field of a message. For proto3, if the value isn't a +//% * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned. +//% * GPBGetMessageRawEnumField will bypass the check and return whatever value +//% * was set. +//% * +//% * @param self The message from which to get the field. +//% * @param field The field to get. +//% * +//% * @return The enum value for the given field. +//% **/ //%int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field); -//%/// Set the given enum field of a message. You can only set values that are -//%/// members of the enum. -//%void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); -//%/// Get the given enum field of a message. No check is done to ensure the value -//%/// was defined in the enum. +//% +//%/** +//% * Set the given enum field of a message. You can only set values that are +//% * members of the enum. +//% * +//% * @param self The message into which to set the field. +//% * @param field The field to set. +//% * @param value The enum value to set in the field. +//% **/ +//%void GPBSetMessageEnumField(GPBMessage *self, +//% GPBFieldDescriptor *field, +//% int32_t value); +//% +//%/** +//% * Get the given enum field of a message. No check is done to ensure the value +//% * was defined in the enum. +//% * +//% * @param self The message from which to get the field. +//% * @param field The field to get. +//% * +//% * @return The raw enum value for the given field. +//% **/ //%int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field); -//%/// Set the given enum field of a message. You can set the value to anything, -//%/// even a value that is not a member of the enum. -//%void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); +//% +//%/** +//% * Set the given enum field of a message. You can set the value to anything, +//% * even a value that is not a member of the enum. +//% * +//% * @param self The message into which to set the field. +//% * @param field The field to set. +//% * @param value The raw enum value to set in the field. +//% **/ +//%void GPBSetMessageRawEnumField(GPBMessage *self, +//% GPBFieldDescriptor *field, +//% int32_t value); //% //%// Repeated Fields //% -//%/// Gets the value of a repeated field. -//%/// -//%/// The result will be @c GPB*Array or @c NSMutableArray based on the -//%/// field's type. +//%/** +//% * Gets the value of a repeated field. +//% * +//% * @param self The message from which to get the field. +//% * @param field The repeated field to get. +//% * +//% * @return A GPB*Array or an NSMutableArray based on the field's type. +//% **/ //%id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field); -//%/// Sets the value of a repeated field. -//%/// -//%/// The value should be @c GPB*Array or @c NSMutableArray based on the -//%/// field's type. -//%void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array); +//% +//%/** +//% * Sets the value of a repeated field. +//% * +//% * @param self The message into which to set the field. +//% * @param field The field to set. +//% * @param array A GPB*Array or NSMutableArray based on the field's type. +//% **/ +//%void GPBSetMessageRepeatedField(GPBMessage *self, +//% GPBFieldDescriptor *field, +//% id array); //% //%// Map Fields //% -//%/// Gets the value of a map<> field. -//%/// -//%/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on -//%/// the field's type. +//%/** +//% * Gets the value of a map<> field. +//% * +//% * @param self The message from which to get the field. +//% * @param field The repeated field to get. +//% * +//% * @return A GPB*Dictionary or NSMutableDictionary based on the field's type. +//% **/ //%id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field); -//%/// Sets the value of a map<> field. -//%/// -//%/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based -//%/// on the field's type. -//%void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary); +//% +//%/** +//% * Sets the value of a map<> field. +//% * +//% * @param self The message into which to set the field. +//% * @param field The field to set. +//% * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the +//% * field's type. +//% **/ +//%void GPBSetMessageMapField(GPBMessage *self, +//% GPBFieldDescriptor *field, +//% id dictionary); //% //%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE, AN) //%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, ) //%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, TisP) -//%/// Gets the value of a##AN NAME$L field. +//%/** +//% * Gets the value of a##AN NAME$L field. +//% * +//% * @param self The message from which to get the field. +//% * @param field The field to get. +//% **/ //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field); -//%/// Sets the value of a##AN NAME$L field. +//% +//%/** +//% * Sets the value of a##AN NAME$L field. +//% * +//% * @param self The message into which to set the field. +//% * @param field The field to set. +//% * @param value The to set in the field. +//% **/ //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value); //% diff --git a/objectivec/GPBUtilities.m b/objectivec/GPBUtilities.m index 05375084..80b85d07 100644 --- a/objectivec/GPBUtilities.m +++ b/objectivec/GPBUtilities.m @@ -218,9 +218,10 @@ void GPBMaybeClearOneof(GPBMessage *self, GPBOneofDescriptor *oneof, //% TYPE *typePtr = (TYPE *)&storage[field->description_->offset]; //% *typePtr = value; //% // proto2: any value counts as having been set; proto3, it -//% // has to be a non zero value. -//% BOOL hasValue = -//% (syntax == GPBFileSyntaxProto2) || (value != (TYPE)0); +//% // has to be a non zero value or be in a oneof. +//% BOOL hasValue = ((syntax == GPBFileSyntaxProto2) +//% || (value != (TYPE)0) +//% || (field->containingOneof_ != NULL)); //% GPBSetHasIvarField(self, field, hasValue); //% GPBBecomeVisibleToAutocreator(self); //%} @@ -337,8 +338,19 @@ void GPBSetRetainedObjectIvarWithFieldInternal(GPBMessage *self, // zero, they are being cleared. if ((syntax == GPBFileSyntaxProto3) && !fieldIsMessage && ([value length] == 0)) { - setHasValue = NO; - value = nil; + // Except, if the field was in a oneof, then it still gets recorded as + // having been set so the state of the oneof can be serialized back out. + if (!oneof) { + setHasValue = NO; + } + if (setHasValue) { + NSCAssert(value != nil, @"Should never be setting has for nil"); + } else { + // The value passed in was retained, it must be released since we + // aren't saving anything in the field. + [value release]; + value = nil; + } } GPBSetHasIvarField(self, field, setHasValue); } @@ -524,9 +536,10 @@ void GPBSetBoolIvarWithFieldInternal(GPBMessage *self, GPBSetHasIvar(self, (int32_t)(fieldDesc->offset), fieldDesc->number, value); // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (BOOL)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (BOOL)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -573,9 +586,10 @@ void GPBSetInt32IvarWithFieldInternal(GPBMessage *self, int32_t *typePtr = (int32_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (int32_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (int32_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -622,9 +636,10 @@ void GPBSetUInt32IvarWithFieldInternal(GPBMessage *self, uint32_t *typePtr = (uint32_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (uint32_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (uint32_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -671,9 +686,10 @@ void GPBSetInt64IvarWithFieldInternal(GPBMessage *self, int64_t *typePtr = (int64_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (int64_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (int64_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -720,9 +736,10 @@ void GPBSetUInt64IvarWithFieldInternal(GPBMessage *self, uint64_t *typePtr = (uint64_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (uint64_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (uint64_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -769,9 +786,10 @@ void GPBSetFloatIvarWithFieldInternal(GPBMessage *self, float *typePtr = (float *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (float)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (float)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -818,9 +836,10 @@ void GPBSetDoubleIvarWithFieldInternal(GPBMessage *self, double *typePtr = (double *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (double)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (double)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -1052,7 +1071,15 @@ static void AppendStringEscaped(NSString *toPrint, NSMutableString *destStr) { case '\'': [destStr appendString:@"\\\'"]; break; case '\\': [destStr appendString:@"\\\\"]; break; default: - [destStr appendFormat:@"%C", aChar]; + // This differs slightly from the C++ code in that the C++ doesn't + // generate UTF8; it looks at the string in UTF8, but escapes every + // byte > 0x7E. + if (aChar < 0x20) { + [destStr appendFormat:@"\\%d%d%d", + (aChar / 64), ((aChar % 64) / 8), (aChar % 8)]; + } else { + [destStr appendFormat:@"%C", aChar]; + } break; } } @@ -1472,7 +1499,8 @@ static void AppendTextFormatForMessage(GPBMessage *message, NSUInteger fieldCount = fieldsArray.count; const GPBExtensionRange *extensionRanges = descriptor.extensionRanges; NSUInteger extensionRangesCount = descriptor.extensionRangesCount; - NSArray *activeExtensions = [message sortedExtensionsInUse]; + NSArray *activeExtensions = [[message extensionsCurrentlySet] + sortedArrayUsingSelector:@selector(compareByFieldNumber:)]; for (NSUInteger i = 0, j = 0; i < fieldCount || j < extensionRangesCount;) { if (i == fieldCount) { AppendTextFormatForMessageExtensionRange( diff --git a/objectivec/GPBUtilities_PackagePrivate.h b/objectivec/GPBUtilities_PackagePrivate.h index c02493b2..a41ee2ab 100644 --- a/objectivec/GPBUtilities_PackagePrivate.h +++ b/objectivec/GPBUtilities_PackagePrivate.h @@ -96,7 +96,7 @@ GPB_INLINE int64_t GPBLogicalRightShift64(int64_t value, int32_t spaces) { // negative values must be sign-extended to 64 bits to be varint encoded, // thus always taking 10 bytes on the wire.) GPB_INLINE int32_t GPBDecodeZigZag32(uint32_t n) { - return GPBLogicalRightShift32(n, 1) ^ -(n & 1); + return (int32_t)(GPBLogicalRightShift32((int32_t)n, 1) ^ -((int32_t)(n) & 1)); } // Decode a ZigZag-encoded 64-bit value. ZigZag encodes signed integers @@ -104,7 +104,7 @@ GPB_INLINE int32_t GPBDecodeZigZag32(uint32_t n) { // negative values must be sign-extended to 64 bits to be varint encoded, // thus always taking 10 bytes on the wire.) GPB_INLINE int64_t GPBDecodeZigZag64(uint64_t n) { - return GPBLogicalRightShift64(n, 1) ^ -(n & 1); + return (int64_t)(GPBLogicalRightShift64((int64_t)n, 1) ^ -((int64_t)(n) & 1)); } // Encode a ZigZag-encoded 32-bit value. ZigZag encodes signed integers @@ -113,7 +113,7 @@ GPB_INLINE int64_t GPBDecodeZigZag64(uint64_t n) { // thus always taking 10 bytes on the wire.) GPB_INLINE uint32_t GPBEncodeZigZag32(int32_t n) { // Note: the right-shift must be arithmetic - return (n << 1) ^ (n >> 31); + return (uint32_t)((n << 1) ^ (n >> 31)); } // Encode a ZigZag-encoded 64-bit value. ZigZag encodes signed integers @@ -122,7 +122,7 @@ GPB_INLINE uint32_t GPBEncodeZigZag32(int32_t n) { // thus always taking 10 bytes on the wire.) GPB_INLINE uint64_t GPBEncodeZigZag64(int64_t n) { // Note: the right-shift must be arithmetic - return (n << 1) ^ (n >> 63); + return (uint64_t)((n << 1) ^ (n >> 63)); } #pragma clang diagnostic push diff --git a/objectivec/GPBWellKnownTypes.h b/objectivec/GPBWellKnownTypes.h index 311ac58e..90d96c6f 100644 --- a/objectivec/GPBWellKnownTypes.h +++ b/objectivec/GPBWellKnownTypes.h @@ -37,27 +37,198 @@ #endif #if GPB_USE_PROTOBUF_FRAMEWORK_IMPORTS + #import <Protobuf/Any.pbobjc.h> #import <Protobuf/Duration.pbobjc.h> #import <Protobuf/Timestamp.pbobjc.h> #else + #import "google/protobuf/Any.pbobjc.h" #import "google/protobuf/Duration.pbobjc.h" #import "google/protobuf/Timestamp.pbobjc.h" #endif NS_ASSUME_NONNULL_BEGIN -// Extension to GPBTimestamp to work with standard Foundation time/date types. +#pragma mark - Errors + +/** NSError domain used for errors. */ +extern NSString *const GPBWellKnownTypesErrorDomain; + +/** Error code for NSError with GPBWellKnownTypesErrorDomain. */ +typedef NS_ENUM(NSInteger, GPBWellKnownTypesErrorCode) { + /** The type_url could not be computed for the requested GPBMessage class. */ + GPBWellKnownTypesErrorCodeFailedToComputeTypeURL = -100, + /** type_url in a Any doesn’t match that of the requested GPBMessage class. */ + GPBWellKnownTypesErrorCodeTypeURLMismatch = -101, +}; + +#pragma mark - GPBTimestamp + +/** + * Category for GPBTimestamp to work with standard Foundation time/date types. + **/ @interface GPBTimestamp (GBPWellKnownTypes) + +/** The NSDate representation of this GPBTimestamp. */ @property(nonatomic, readwrite, strong) NSDate *date; + +/** + * The NSTimeInterval representation of this GPBTimestamp. + * + * @note: Not all second/nanos combinations can be represented in a + * NSTimeInterval, so getting this could be a lossy transform. + **/ @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970; + +/** + * Initializes a GPBTimestamp with the given NSDate. + * + * @param date The date to configure the GPBTimestamp with. + * + * @return A newly initialized GPBTimestamp. + **/ - (instancetype)initWithDate:(NSDate *)date; + +/** + * Initializes a GPBTimestamp with the given NSTimeInterval. + * + * @param timeIntervalSince1970 Time interval to configure the GPBTimestamp with. + * + * @return A newly initialized GPBTimestamp. + **/ - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970; + @end -// Extension to GPBDuration to work with standard Foundation time type. +#pragma mark - GPBDuration + +/** + * Category for GPBDuration to work with standard Foundation time type. + **/ @interface GPBDuration (GBPWellKnownTypes) + +/** + * The NSTimeInterval representation of this GPBDuration. + * + * @note: Not all second/nanos combinations can be represented in a + * NSTimeInterval, so getting this could be a lossy transform. + **/ @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970; + +/** + * Initializes a GPBDuration with the given NSTimeInterval. + * + * @param timeIntervalSince1970 Time interval to configure the GPBDuration with. + * + * @return A newly initialized GPBDuration. + **/ - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970; + +@end + +#pragma mark - GPBAny + +/** + * Category for GPBAny to help work with the message within the object. + **/ +@interface GPBAny (GBPWellKnownTypes) + +/** + * Convenience method to create a GPBAny containing the serialized message. + * This uses type.googleapis.com/ as the type_url's prefix. + * + * @param message The message to be packed into the GPBAny. + * @param errorPtr Pointer to an error that will be populated if something goes + * wrong. + * + * @return A newly configured GPBAny with the given message, or nil on failure. + */ ++ (nullable instancetype)anyWithMessage:(nonnull GPBMessage *)message + error:(NSError **)errorPtr; + +/** + * Convenience method to create a GPBAny containing the serialized message. + * + * @param message The message to be packed into the GPBAny. + * @param typeURLPrefix The URL prefix to apply for type_url. + * @param errorPtr Pointer to an error that will be populated if something + * goes wrong. + * + * @return A newly configured GPBAny with the given message, or nil on failure. + */ ++ (nullable instancetype)anyWithMessage:(nonnull GPBMessage *)message + typeURLPrefix:(nonnull NSString *)typeURLPrefix + error:(NSError **)errorPtr; + +/** + * Initializes a GPBAny to contain the serialized message. This uses + * type.googleapis.com/ as the type_url's prefix. + * + * @param message The message to be packed into the GPBAny. + * @param errorPtr Pointer to an error that will be populated if something goes + * wrong. + * + * @return A newly configured GPBAny with the given message, or nil on failure. + */ +- (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message + error:(NSError **)errorPtr; + +/** + * Initializes a GPBAny to contain the serialized message. + * + * @param message The message to be packed into the GPBAny. + * @param typeURLPrefix The URL prefix to apply for type_url. + * @param errorPtr Pointer to an error that will be populated if something + * goes wrong. + * + * @return A newly configured GPBAny with the given message, or nil on failure. + */ +- (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message + typeURLPrefix:(nonnull NSString *)typeURLPrefix + error:(NSError **)errorPtr; + +/** + * Packs the serialized message into this GPBAny. This uses + * type.googleapis.com/ as the type_url's prefix. + * + * @param message The message to be packed into the GPBAny. + * @param errorPtr Pointer to an error that will be populated if something goes + * wrong. + * + * @return Whether the packing was successful or not. + */ +- (BOOL)packWithMessage:(nonnull GPBMessage *)message + error:(NSError **)errorPtr; + +/** + * Packs the serialized message into this GPBAny. + * + * @param message The message to be packed into the GPBAny. + * @param typeURLPrefix The URL prefix to apply for type_url. + * @param errorPtr Pointer to an error that will be populated if something + * goes wrong. + * + * @return Whether the packing was successful or not. + */ +- (BOOL)packWithMessage:(nonnull GPBMessage *)message + typeURLPrefix:(nonnull NSString *)typeURLPrefix + error:(NSError **)errorPtr; + +/** + * Unpacks the serialized message as if it was an instance of the given class. + * + * @note When checking type_url, the base URL is not checked, only the fully + * qualified name. + * + * @param messageClass The class to use to deserialize the contained message. + * @param errorPtr Pointer to an error that will be populated if something + * goes wrong. + * + * @return An instance of the given class populated with the contained data, or + * nil on failure. + */ +- (nullable GPBMessage *)unpackMessageClass:(Class)messageClass + error:(NSError **)errorPtr; + @end NS_ASSUME_NONNULL_END diff --git a/objectivec/GPBWellKnownTypes.m b/objectivec/GPBWellKnownTypes.m index 5cdd62d5..ed798a2e 100644 --- a/objectivec/GPBWellKnownTypes.m +++ b/objectivec/GPBWellKnownTypes.m @@ -34,6 +34,13 @@ #import "GPBWellKnownTypes.h" +#import "GPBUtilities_PackagePrivate.h" + +NSString *const GPBWellKnownTypesErrorDomain = + GPBNSStringifySymbol(GPBWellKnownTypesErrorDomain); + +static NSString *kTypePrefixGoogleApisCom = @"type.googleapis.com/"; + static NSTimeInterval TimeIntervalSince1970FromSecondsAndNanos(int64_t seconds, int32_t nanos) { return seconds + (NSTimeInterval)nanos / 1e9; @@ -48,6 +55,30 @@ static int32_t SecondsAndNanosFromTimeIntervalSince1970(NSTimeInterval time, return (int32_t)nanos; } +static NSString *BuildTypeURL(NSString *typeURLPrefix, NSString *fullName) { + if (typeURLPrefix.length == 0) { + return fullName; + } + + if ([typeURLPrefix hasSuffix:@"/"]) { + return [typeURLPrefix stringByAppendingString:fullName]; + } + + return [NSString stringWithFormat:@"%@/%@", typeURLPrefix, fullName]; +} + +static NSString *ParseTypeFromURL(NSString *typeURLString) { + NSRange range = [typeURLString rangeOfString:@"/" options:NSBackwardsSearch]; + if ((range.location == NSNotFound) || + (NSMaxRange(range) == typeURLString.length)) { + return nil; + } + NSString *result = [typeURLString substringFromIndex:range.location + 1]; + return result; +} + +#pragma mark - GPBTimestamp + @implementation GPBTimestamp (GBPWellKnownTypes) - (instancetype)initWithDate:(NSDate *)date { @@ -87,6 +118,8 @@ static int32_t SecondsAndNanosFromTimeIntervalSince1970(NSTimeInterval time, @end +#pragma mark - GPBDuration + @implementation GPBDuration (GBPWellKnownTypes) - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970 { @@ -113,3 +146,105 @@ static int32_t SecondsAndNanosFromTimeIntervalSince1970(NSTimeInterval time, } @end + +#pragma mark - GPBAny + +@implementation GPBAny (GBPWellKnownTypes) + ++ (instancetype)anyWithMessage:(GPBMessage *)message + error:(NSError **)errorPtr { + return [self anyWithMessage:message + typeURLPrefix:kTypePrefixGoogleApisCom + error:errorPtr]; +} + ++ (instancetype)anyWithMessage:(GPBMessage *)message + typeURLPrefix:(NSString *)typeURLPrefix + error:(NSError **)errorPtr { + return [[[self alloc] initWithMessage:message + typeURLPrefix:typeURLPrefix + error:errorPtr] autorelease]; +} + +- (instancetype)initWithMessage:(GPBMessage *)message + error:(NSError **)errorPtr { + return [self initWithMessage:message + typeURLPrefix:kTypePrefixGoogleApisCom + error:errorPtr]; +} + +- (instancetype)initWithMessage:(GPBMessage *)message + typeURLPrefix:(NSString *)typeURLPrefix + error:(NSError **)errorPtr { + self = [self init]; + if (self) { + if (![self packWithMessage:message + typeURLPrefix:typeURLPrefix + error:errorPtr]) { + [self release]; + self = nil; + } + } + return self; +} + +- (BOOL)packWithMessage:(GPBMessage *)message + error:(NSError **)errorPtr { + return [self packWithMessage:message + typeURLPrefix:kTypePrefixGoogleApisCom + error:errorPtr]; +} + +- (BOOL)packWithMessage:(GPBMessage *)message + typeURLPrefix:(NSString *)typeURLPrefix + error:(NSError **)errorPtr { + NSString *fullName = [message descriptor].fullName; + if (fullName.length == 0) { + if (errorPtr) { + *errorPtr = + [NSError errorWithDomain:GPBWellKnownTypesErrorDomain + code:GPBWellKnownTypesErrorCodeFailedToComputeTypeURL + userInfo:nil]; + } + return NO; + } + if (errorPtr) { + *errorPtr = nil; + } + self.typeURL = BuildTypeURL(typeURLPrefix, fullName); + self.value = message.data; + return YES; +} + +- (GPBMessage *)unpackMessageClass:(Class)messageClass + error:(NSError **)errorPtr { + NSString *fullName = [messageClass descriptor].fullName; + if (fullName.length == 0) { + if (errorPtr) { + *errorPtr = + [NSError errorWithDomain:GPBWellKnownTypesErrorDomain + code:GPBWellKnownTypesErrorCodeFailedToComputeTypeURL + userInfo:nil]; + } + return nil; + } + + NSString *expectedFullName = ParseTypeFromURL(self.typeURL); + if ((expectedFullName == nil) || ![expectedFullName isEqual:fullName]) { + if (errorPtr) { + *errorPtr = + [NSError errorWithDomain:GPBWellKnownTypesErrorDomain + code:GPBWellKnownTypesErrorCodeTypeURLMismatch + userInfo:nil]; + } + return nil; + } + + // Any is proto3, which means no extensions, so this assumes anything put + // within an any also won't need extensions. A second helper could be added + // if needed. + return [messageClass parseFromData:self.value + error:errorPtr]; +} + +@end diff --git a/objectivec/ProtocolBuffers_OSX.xcodeproj/project.pbxproj b/objectivec/ProtocolBuffers_OSX.xcodeproj/project.pbxproj index 32067910..1585dbed 100644 --- a/objectivec/ProtocolBuffers_OSX.xcodeproj/project.pbxproj +++ b/objectivec/ProtocolBuffers_OSX.xcodeproj/project.pbxproj @@ -65,6 +65,7 @@ F4E675A11B21D0000054530B /* Struct.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675911B21D0000054530B /* Struct.pbobjc.m */; }; F4E675A31B21D0000054530B /* Type.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675931B21D0000054530B /* Type.pbobjc.m */; }; F4E675A51B21D0000054530B /* Wrappers.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675951B21D0000054530B /* Wrappers.pbobjc.m */; }; + F4F8D8831D789FD9002CE128 /* GPBUnittestProtos2.m in Sources */ = {isa = PBXBuildFile; fileRef = F4F8D8811D789FCE002CE128 /* GPBUnittestProtos2.m */; }; /* End PBXBuildFile section */ /* Begin PBXContainerItemProxy section */ @@ -211,6 +212,7 @@ F4E675AB1B21D05C0054530B /* struct.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = struct.proto; path = ../src/google/protobuf/struct.proto; sourceTree = "<group>"; }; F4E675AC1B21D05C0054530B /* type.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = type.proto; path = ../src/google/protobuf/type.proto; sourceTree = "<group>"; }; F4E675AD1B21D05C0054530B /* wrappers.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = wrappers.proto; path = ../src/google/protobuf/wrappers.proto; sourceTree = "<group>"; }; + F4F8D8811D789FCE002CE128 /* GPBUnittestProtos2.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = GPBUnittestProtos2.m; sourceTree = "<group>"; }; /* End PBXFileReference section */ /* Begin PBXFrameworksBuildPhase section */ @@ -408,6 +410,7 @@ 7461B6AB0F94FDF800A0C422 /* GPBTestUtilities.h */, 7461B6AC0F94FDF800A0C422 /* GPBTestUtilities.m */, 8BD3981E14BE59D70081D629 /* GPBUnittestProtos.m */, + F4F8D8811D789FCE002CE128 /* GPBUnittestProtos2.m */, 7461B6B80F94FDF900A0C422 /* GPBUnknownFieldSetTest.m */, 7461B6BA0F94FDF900A0C422 /* GPBUtilitiesTests.m */, 8B4248DB1A92933A00BC1EC6 /* GPBWellKnownTypesTest.m */, @@ -659,6 +662,7 @@ F4B51B1E1BBC610700744318 /* GPBObjectiveCPlusPlusTest.mm in Sources */, F4487C7F1AAF62CD00531423 /* GPBMessageTests+Serialization.m in Sources */, 8B4248DC1A92933A00BC1EC6 /* GPBWellKnownTypesTest.m in Sources */, + F4F8D8831D789FD9002CE128 /* GPBUnittestProtos2.m in Sources */, F4353D1D1AB8822D005A6198 /* GPBDescriptorTests.m in Sources */, 8B4248BB1A8C256A00BC1EC6 /* GPBSwiftTests.swift in Sources */, 5102DABC1891A073002037B6 /* GPBConcurrencyTests.m in Sources */, @@ -778,6 +782,7 @@ CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES; CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES; CLANG_STATIC_ANALYZER_MODE = deep; + CLANG_WARN_ASSIGN_ENUM = YES; CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES; @@ -838,6 +843,7 @@ CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES; CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES; CLANG_STATIC_ANALYZER_MODE = deep; + CLANG_WARN_ASSIGN_ENUM = YES; CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES; diff --git a/objectivec/ProtocolBuffers_iOS.xcodeproj/project.pbxproj b/objectivec/ProtocolBuffers_iOS.xcodeproj/project.pbxproj index 9f688f8d..b6bc95ab 100644 --- a/objectivec/ProtocolBuffers_iOS.xcodeproj/project.pbxproj +++ b/objectivec/ProtocolBuffers_iOS.xcodeproj/project.pbxproj @@ -73,6 +73,7 @@ F4E675D51B21D1620054530B /* Struct.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675C21B21D1440054530B /* Struct.pbobjc.m */; }; F4E675D61B21D1620054530B /* Type.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675C51B21D1440054530B /* Type.pbobjc.m */; }; F4E675D71B21D1620054530B /* Wrappers.pbobjc.m in Sources */ = {isa = PBXBuildFile; fileRef = F4E675C71B21D1440054530B /* Wrappers.pbobjc.m */; }; + F4F8D8861D78A193002CE128 /* GPBUnittestProtos2.m in Sources */ = {isa = PBXBuildFile; fileRef = F4F8D8841D78A186002CE128 /* GPBUnittestProtos2.m */; }; /* End PBXBuildFile section */ /* Begin PBXContainerItemProxy section */ @@ -234,6 +235,7 @@ F4E675DD1B21D1DE0054530B /* struct.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = struct.proto; path = ../src/google/protobuf/struct.proto; sourceTree = "<group>"; }; F4E675DE1B21D1DE0054530B /* type.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = type.proto; path = ../src/google/protobuf/type.proto; sourceTree = "<group>"; }; F4E675DF1B21D1DE0054530B /* wrappers.proto */ = {isa = PBXFileReference; lastKnownFileType = text; name = wrappers.proto; path = ../src/google/protobuf/wrappers.proto; sourceTree = "<group>"; }; + F4F8D8841D78A186002CE128 /* GPBUnittestProtos2.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = GPBUnittestProtos2.m; sourceTree = "<group>"; }; /* End PBXFileReference section */ /* Begin PBXFrameworksBuildPhase section */ @@ -446,6 +448,7 @@ 7461B6AB0F94FDF800A0C422 /* GPBTestUtilities.h */, 7461B6AC0F94FDF800A0C422 /* GPBTestUtilities.m */, 8BD3981E14BE59D70081D629 /* GPBUnittestProtos.m */, + F4F8D8841D78A186002CE128 /* GPBUnittestProtos2.m */, 7461B6B80F94FDF900A0C422 /* GPBUnknownFieldSetTest.m */, 7461B6BA0F94FDF900A0C422 /* GPBUtilitiesTests.m */, 8B4248E51A929C9900BC1EC6 /* GPBWellKnownTypesTest.m */, @@ -755,6 +758,7 @@ F4487C811AAF62FC00531423 /* GPBMessageTests+Serialization.m in Sources */, 8B4248E61A929C9900BC1EC6 /* GPBWellKnownTypesTest.m in Sources */, F4353D1F1AB88243005A6198 /* GPBDescriptorTests.m in Sources */, + F4F8D8861D78A193002CE128 /* GPBUnittestProtos2.m in Sources */, F4B51B1C1BBC5C7100744318 /* GPBObjectiveCPlusPlusTest.mm in Sources */, 8B4248B41A8BD96E00BC1EC6 /* GPBSwiftTests.swift in Sources */, 5102DABC1891A073002037B6 /* GPBConcurrencyTests.m in Sources */, @@ -940,6 +944,7 @@ CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES; CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES; CLANG_STATIC_ANALYZER_MODE = deep; + CLANG_WARN_ASSIGN_ENUM = YES; CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES; @@ -1001,6 +1006,7 @@ CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES; CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES; CLANG_STATIC_ANALYZER_MODE = deep; + CLANG_WARN_ASSIGN_ENUM = YES; CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES; diff --git a/objectivec/Tests/GPBCodedOuputStreamTests.m b/objectivec/Tests/GPBCodedOuputStreamTests.m index 0723b645..2ad326be 100644 --- a/objectivec/Tests/GPBCodedOuputStreamTests.m +++ b/objectivec/Tests/GPBCodedOuputStreamTests.m @@ -193,6 +193,32 @@ } } +- (void)assertWriteStringNoTag:(NSData*)data + value:(NSString *)value + context:(NSString *)contextMessage { + NSOutputStream* rawOutput = [NSOutputStream outputStreamToMemory]; + GPBCodedOutputStream* output = + [GPBCodedOutputStream streamWithOutputStream:rawOutput]; + [output writeStringNoTag:value]; + [output flush]; + + NSData* actual = + [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey]; + XCTAssertEqualObjects(data, actual, @"%@", contextMessage); + + // Try different block sizes. + for (int blockSize = 1; blockSize <= 16; blockSize *= 2) { + rawOutput = [NSOutputStream outputStreamToMemory]; + output = [GPBCodedOutputStream streamWithOutputStream:rawOutput + bufferSize:blockSize]; + [output writeStringNoTag:value]; + [output flush]; + + actual = [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey]; + XCTAssertEqualObjects(data, actual, @"%@", contextMessage); + } +} + - (void)testWriteVarint1 { [self assertWriteVarint:bytes(0x00) value:0]; } @@ -337,4 +363,64 @@ XCTAssertEqualObjects(rawBytes, goldenData); } +- (void)testCFStringGetCStringPtrAndStringsWithNullChars { + // This test exists to verify that CFStrings with embedded NULLs still expose + // their raw buffer if they are backed by UTF8 storage. If this fails, the + // quick/direct access paths in GPBCodedOutputStream that depend on + // CFStringGetCStringPtr need to be re-evalutated (maybe just removed). + // And yes, we do get NULLs in strings from some servers. + + char zeroTest[] = "\0Test\0String"; + // Note: there is a \0 at the end of this since it is a c-string. + NSString *asNSString = [[NSString alloc] initWithBytes:zeroTest + length:sizeof(zeroTest) + encoding:NSUTF8StringEncoding]; + const char *cString = + CFStringGetCStringPtr((CFStringRef)asNSString, kCFStringEncodingUTF8); + XCTAssertTrue(cString != NULL); + // Again, if the above assert fails, then it means NSString no longer exposes + // the raw utf8 storage of a string created from utf8 input, so the code using + // CFStringGetCStringPtr in GPBCodedOutputStream will still work (it will take + // a different code path); but the optimizations for when + // CFStringGetCStringPtr does work could possibly go away. + + XCTAssertEqual(sizeof(zeroTest), + [asNSString lengthOfBytesUsingEncoding:NSUTF8StringEncoding]); + XCTAssertTrue(0 == memcmp(cString, zeroTest, sizeof(zeroTest))); + [asNSString release]; +} + +- (void)testWriteStringsWithZeroChar { + // Unicode allows `\0` as a character, and NSString is a class cluster, so + // there are a few different classes that could end up beind a given string. + // Historically, we've seen differences based on constant strings in code and + // strings built via the NSString apis. So this round trips them to ensure + // they are acting as expected. + + NSArray<NSString *> *strs = @[ + @"\0at start", + @"in\0middle", + @"at end\0", + ]; + int i = 0; + for (NSString *str in strs) { + NSData *asUTF8 = [str dataUsingEncoding:NSUTF8StringEncoding]; + NSMutableData *expected = [NSMutableData data]; + uint8_t lengthByte = (uint8_t)asUTF8.length; + [expected appendBytes:&lengthByte length:1]; + [expected appendData:asUTF8]; + + NSString *context = [NSString stringWithFormat:@"Loop %d - Literal", i]; + [self assertWriteStringNoTag:expected value:str context:context]; + + // Force a new string to be built which gets a different class from the + // NSString class cluster than the literal did. + NSString *str2 = [NSString stringWithFormat:@"%@", str]; + context = [NSString stringWithFormat:@"Loop %d - Built", i]; + [self assertWriteStringNoTag:expected value:str2 context:context]; + + ++i; + } +} + @end diff --git a/objectivec/Tests/GPBDescriptorTests.m b/objectivec/Tests/GPBDescriptorTests.m index 74e3172b..1e1c3de8 100644 --- a/objectivec/Tests/GPBDescriptorTests.m +++ b/objectivec/Tests/GPBDescriptorTests.m @@ -34,12 +34,41 @@ #import "GPBDescriptor.h" #import "google/protobuf/Unittest.pbobjc.h" +#import "google/protobuf/UnittestObjc.pbobjc.h" +#import "google/protobuf/Descriptor.pbobjc.h" @interface DescriptorTests : GPBTestCase @end @implementation DescriptorTests +- (void)testDescriptor_containingType { + GPBDescriptor *testAllTypesDesc = [TestAllTypes descriptor]; + GPBDescriptor *nestedMessageDesc = [TestAllTypes_NestedMessage descriptor]; + XCTAssertNil(testAllTypesDesc.containingType); + XCTAssertNotNil(nestedMessageDesc.containingType); + XCTAssertEqual(nestedMessageDesc.containingType, testAllTypesDesc); // Ptr comparison +} + +- (void)testDescriptor_fullName { + GPBDescriptor *testAllTypesDesc = [TestAllTypes descriptor]; + XCTAssertEqualObjects(testAllTypesDesc.fullName, @"protobuf_unittest.TestAllTypes"); + GPBDescriptor *nestedMessageDesc = [TestAllTypes_NestedMessage descriptor]; + XCTAssertEqualObjects(nestedMessageDesc.fullName, @"protobuf_unittest.TestAllTypes.NestedMessage"); + + // Prefixes removed. + GPBDescriptor *descDesc = [GPBDescriptorProto descriptor]; + XCTAssertEqualObjects(descDesc.fullName, @"google.protobuf.DescriptorProto"); + GPBDescriptor *descExtRngDesc = [GPBDescriptorProto_ExtensionRange descriptor]; + XCTAssertEqualObjects(descExtRngDesc.fullName, @"google.protobuf.DescriptorProto.ExtensionRange"); + + // Things that get "_Class" added. + GPBDescriptor *pointDesc = [Point_Class descriptor]; + XCTAssertEqualObjects(pointDesc.fullName, @"protobuf_unittest.Point"); + GPBDescriptor *pointRectDesc = [Point_Rect descriptor]; + XCTAssertEqualObjects(pointRectDesc.fullName, @"protobuf_unittest.Point.Rect"); +} + - (void)testFieldDescriptor { GPBDescriptor *descriptor = [TestAllTypes descriptor]; diff --git a/objectivec/Tests/GPBMessageTests+Runtime.m b/objectivec/Tests/GPBMessageTests+Runtime.m index 1520381b..0058311b 100644 --- a/objectivec/Tests/GPBMessageTests+Runtime.m +++ b/objectivec/Tests/GPBMessageTests+Runtime.m @@ -36,6 +36,7 @@ #import "google/protobuf/MapUnittest.pbobjc.h" #import "google/protobuf/Unittest.pbobjc.h" +#import "google/protobuf/UnittestCycle.pbobjc.h" #import "google/protobuf/UnittestObjcStartup.pbobjc.h" #import "google/protobuf/UnittestRuntimeProto2.pbobjc.h" #import "google/protobuf/UnittestRuntimeProto3.pbobjc.h" @@ -49,11 +50,24 @@ // specific. - (void)testStartupOrdering { - // Just have to create a message. Nothing else uses the classes from - // this file, so the first selector invoked on the class will initialize - // it, which also initializes the root. + // Message class/Root class initialization is a little tricky, so these just + // create some possible patterns that can be a problem. The messages don't + // have to be exercised, just creating them is enough to test. If there + // is a problem, the runtime should assert or hang. + // + // Note: the messages from these proto files should not be used in any other + // tests, that way when they are referenced here it will be the first use and + // initialization will take place now. + TestObjCStartupMessage *message = [TestObjCStartupMessage message]; XCTAssertNotNil(message); + + CycleBaz *baz = [CycleBaz message]; + CycleBar *bar = [CycleBar message]; + CycleFoo *foo = [CycleFoo message]; + XCTAssertNotNil(baz); + XCTAssertNotNil(bar); + XCTAssertNotNil(foo); } - (void)testProto2HasMethodSupport { @@ -326,6 +340,17 @@ //% [msg release]; //% } //% +//%PDDM-DEFINE PROTO2_TEST_CLEAR_FIELD_WITH_NIL(FIELD, VALUE) +//% { // optional##FIELD +//% Message2 *msg = [[Message2 alloc] init]; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = VALUE; +//% XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = nil; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% [msg release]; +//% } +//% //%PDDM-DEFINE PROTO2_TEST_HAS_FIELDS() //%PROTO2_TEST_HAS_FIELD(Int32, 1, 0) //%PROTO2_TEST_HAS_FIELD(Int64, 1, 0) @@ -347,6 +372,14 @@ //% // //% //%PROTO2_TEST_HAS_FIELD(Enum, Message2_Enum_Bar, Message2_Enum_Foo) +//% // +//% // Nil can also be used to clear strings, bytes, groups, and messages. +//% // +//% +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(String, @"foo") +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding]) +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Group, [Message2_OptionalGroup message]) +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Message, [Message2 message]) //%PDDM-EXPAND PROTO2_TEST_HAS_FIELDS() // This block of code is generated, do not edit it directly. @@ -658,13 +691,57 @@ [msg release]; } + // + // Nil can also be used to clear strings, bytes, groups, and messages. + // + + { // optionalString + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + msg.optionalString = @"foo"; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + msg.optionalString = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + [msg release]; + } + + { // optionalBytes + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + msg.optionalBytes = [@"foo" dataUsingEncoding:NSUTF8StringEncoding]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + msg.optionalBytes = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + [msg release]; + } + + { // optionalGroup + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + msg.optionalGroup = [Message2_OptionalGroup message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + msg.optionalGroup = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + [msg release]; + } + + { // optionalMessage + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + msg.optionalMessage = [Message2 message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + msg.optionalMessage = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + [msg release]; + } + //%PDDM-EXPAND-END PROTO2_TEST_HAS_FIELDS() } - (void)testProto3SingleFieldHasBehavior { // - // Setting to any value including the default value (0) should result has* - // being true. + // Setting to any value but the default value (0) should result has* + // being true. When set to the default, shouldn't be true. // //%PDDM-DEFINE PROTO3_TEST_HAS_FIELD(FIELD, NON_ZERO_VALUE, ZERO_VALUE) @@ -678,6 +755,17 @@ //% [msg release]; //% } //% +//%PDDM-DEFINE PROTO3_TEST_CLEAR_FIELD_WITH_NIL(FIELD, VALUE) +//% { // optional##FIELD +//% Message3 *msg = [[Message3 alloc] init]; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = VALUE; +//% XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = nil; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% [msg release]; +//% } +//% //%PDDM-DEFINE PROTO3_TEST_HAS_FIELDS() //%PROTO3_TEST_HAS_FIELD(Int32, 1, 0) //%PROTO3_TEST_HAS_FIELD(Int64, 1, 0) @@ -695,10 +783,17 @@ //%PROTO3_TEST_HAS_FIELD(String, @"foo", @"") //%PROTO3_TEST_HAS_FIELD(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding], [NSData data]) //% // -//% // Test doesn't apply to optionalGroup/optionalMessage. +//% // Test doesn't apply to optionalMessage (no groups in proto3). //% // //% //%PROTO3_TEST_HAS_FIELD(Enum, Message3_Enum_Bar, Message3_Enum_Foo) +//% // +//% // Nil can also be used to clear strings, bytes, and messages (no groups in proto3). +//% // +//% +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(String, @"foo") +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding]) +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(Message, [Message3 message]) //%PDDM-EXPAND PROTO3_TEST_HAS_FIELDS() // This block of code is generated, do not edit it directly. @@ -853,7 +948,7 @@ } // - // Test doesn't apply to optionalGroup/optionalMessage. + // Test doesn't apply to optionalMessage (no groups in proto3). // { // optionalEnum @@ -866,6 +961,40 @@ [msg release]; } + // + // Nil can also be used to clear strings, bytes, and messages (no groups in proto3). + // + + { // optionalString + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + msg.optionalString = @"foo"; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + msg.optionalString = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + [msg release]; + } + + { // optionalBytes + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + msg.optionalBytes = [@"foo" dataUsingEncoding:NSUTF8StringEncoding]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + msg.optionalBytes = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + [msg release]; + } + + { // optionalMessage + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + msg.optionalMessage = [Message3 message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + msg.optionalMessage = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + [msg release]; + } + //%PDDM-EXPAND-END PROTO3_TEST_HAS_FIELDS() } @@ -1972,6 +2101,262 @@ [msg release]; } +- (void)testProto2OneofSetToDefault { + + // proto3 doesn't normally write out zero (default) fields, but if they are + // in a oneof it does. proto2 doesn't have this special behavior, but we + // still confirm setting to the explicit default does set the case to be + // sure the runtime is working correctly. + + NSString *oneofStringDefault = @"string"; + NSData *oneofBytesDefault = [@"data" dataUsingEncoding:NSUTF8StringEncoding]; + + Message2 *msg = [[Message2 alloc] init]; + + uint32_t values[] = { + Message2_O_OneOfCase_OneofInt32, + Message2_O_OneOfCase_OneofInt64, + Message2_O_OneOfCase_OneofUint32, + Message2_O_OneOfCase_OneofUint64, + Message2_O_OneOfCase_OneofSint32, + Message2_O_OneOfCase_OneofSint64, + Message2_O_OneOfCase_OneofFixed32, + Message2_O_OneOfCase_OneofFixed64, + Message2_O_OneOfCase_OneofSfixed32, + Message2_O_OneOfCase_OneofSfixed64, + Message2_O_OneOfCase_OneofFloat, + Message2_O_OneOfCase_OneofDouble, + Message2_O_OneOfCase_OneofBool, + Message2_O_OneOfCase_OneofString, + Message2_O_OneOfCase_OneofBytes, + // Skip group + // Skip message + Message2_O_OneOfCase_OneofEnum, + }; + + for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) { + switch (values[i]) { + case Message2_O_OneOfCase_OneofInt32: + msg.oneofInt32 = 100; + break; + case Message2_O_OneOfCase_OneofInt64: + msg.oneofInt64 = 101; + break; + case Message2_O_OneOfCase_OneofUint32: + msg.oneofUint32 = 102; + break; + case Message2_O_OneOfCase_OneofUint64: + msg.oneofUint64 = 103; + break; + case Message2_O_OneOfCase_OneofSint32: + msg.oneofSint32 = 104; + break; + case Message2_O_OneOfCase_OneofSint64: + msg.oneofSint64 = 105; + break; + case Message2_O_OneOfCase_OneofFixed32: + msg.oneofFixed32 = 106; + break; + case Message2_O_OneOfCase_OneofFixed64: + msg.oneofFixed64 = 107; + break; + case Message2_O_OneOfCase_OneofSfixed32: + msg.oneofSfixed32 = 108; + break; + case Message2_O_OneOfCase_OneofSfixed64: + msg.oneofSfixed64 = 109; + break; + case Message2_O_OneOfCase_OneofFloat: + msg.oneofFloat = 110.0f; + break; + case Message2_O_OneOfCase_OneofDouble: + msg.oneofDouble = 111.0; + break; + case Message2_O_OneOfCase_OneofBool: + msg.oneofBool = YES; + break; + case Message2_O_OneOfCase_OneofString: + msg.oneofString = oneofStringDefault; + break; + case Message2_O_OneOfCase_OneofBytes: + msg.oneofBytes = oneofBytesDefault; + break; + case Message2_O_OneOfCase_OneofEnum: + msg.oneofEnum = Message3_Enum_Baz; + break; + default: + XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]); + break; + } + + // Should be set to the correct case. + XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i); + + // Confirm everything is the defaults. + XCTAssertEqual(msg.oneofInt32, 100, "Loop: %zd", i); + XCTAssertEqual(msg.oneofInt64, 101, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint32, 102U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint64, 103U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint32, 104, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint64, 105, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed32, 106U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed64, 107U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed32, 108, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed64, 109, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFloat, 110.0f, "Loop: %zd", i); + XCTAssertEqual(msg.oneofDouble, 111.0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofBool, YES, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i); + // Skip group, no default to consider. + // Skip message, no default to consider. + XCTAssertEqual(msg.oneofEnum, Message2_Enum_Baz, "Loop: %zd", i); + } + + // We special case nil on string, data, group, and message, ensure they work + // as expected. i.e. - it clears the case. + msg.oneofString = nil; + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault); + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + msg.oneofBytes = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault); + msg.oneofGroup = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofGroup); + msg.oneofMessage = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofMessage); + + [msg release]; +} + +- (void)testProto3OneofSetToZero { + + // Normally setting a proto3 field to the zero value should result in it being + // reset/cleared. But in a oneof, it still gets recored so it can go out + // over the wire and the other side can see what was set in the oneof. + + NSString *oneofStringDefault = @""; + NSData *oneofBytesDefault = [NSData data]; + + Message3 *msg = [[Message3 alloc] init]; + + uint32_t values[] = { + Message3_O_OneOfCase_OneofInt32, + Message3_O_OneOfCase_OneofInt64, + Message3_O_OneOfCase_OneofUint32, + Message3_O_OneOfCase_OneofUint64, + Message3_O_OneOfCase_OneofSint32, + Message3_O_OneOfCase_OneofSint64, + Message3_O_OneOfCase_OneofFixed32, + Message3_O_OneOfCase_OneofFixed64, + Message3_O_OneOfCase_OneofSfixed32, + Message3_O_OneOfCase_OneofSfixed64, + Message3_O_OneOfCase_OneofFloat, + Message3_O_OneOfCase_OneofDouble, + Message3_O_OneOfCase_OneofBool, + Message3_O_OneOfCase_OneofString, + Message3_O_OneOfCase_OneofBytes, + Message3_O_OneOfCase_OneofMessage, + Message3_O_OneOfCase_OneofEnum, + }; + + for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) { + switch (values[i]) { + case Message3_O_OneOfCase_OneofInt32: + msg.oneofInt32 = 0; + break; + case Message3_O_OneOfCase_OneofInt64: + msg.oneofInt64 = 0; + break; + case Message3_O_OneOfCase_OneofUint32: + msg.oneofUint32 = 0; + break; + case Message3_O_OneOfCase_OneofUint64: + msg.oneofUint64 = 0; + break; + case Message3_O_OneOfCase_OneofSint32: + msg.oneofSint32 = 0; + break; + case Message3_O_OneOfCase_OneofSint64: + msg.oneofSint64 = 0; + break; + case Message3_O_OneOfCase_OneofFixed32: + msg.oneofFixed32 = 0; + break; + case Message3_O_OneOfCase_OneofFixed64: + msg.oneofFixed64 = 0; + break; + case Message3_O_OneOfCase_OneofSfixed32: + msg.oneofSfixed32 = 0; + break; + case Message3_O_OneOfCase_OneofSfixed64: + msg.oneofSfixed64 = 0; + break; + case Message3_O_OneOfCase_OneofFloat: + msg.oneofFloat = 0.0f; + break; + case Message3_O_OneOfCase_OneofDouble: + msg.oneofDouble = 0.0; + break; + case Message3_O_OneOfCase_OneofBool: + msg.oneofBool = NO; + break; + case Message3_O_OneOfCase_OneofString: + msg.oneofString = oneofStringDefault; + break; + case Message3_O_OneOfCase_OneofBytes: + msg.oneofBytes = oneofBytesDefault; + break; + case Message3_O_OneOfCase_OneofMessage: + msg.oneofMessage.optionalInt32 = 0; + break; + case Message3_O_OneOfCase_OneofEnum: + msg.oneofEnum = Message3_Enum_Foo; + break; + default: + XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]); + break; + } + + // Should be set to the correct case. + XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i); + + // Confirm everything is still zeros. + XCTAssertEqual(msg.oneofInt32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofInt64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint32, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint64, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed32, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed64, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFloat, 0.0f, "Loop: %zd", i); + XCTAssertEqual(msg.oneofDouble, 0.0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofBool, NO, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i); + XCTAssertNotNil(msg.oneofMessage, "Loop: %zd", i); + XCTAssertEqual(msg.oneofEnum, Message3_Enum_Foo, "Loop: %zd", i); + } + + // We special case nil on string, data, message, ensure they work as expected. + msg.oneofString = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault); + msg.oneofBytes = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault); + msg.oneofMessage = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofMessage); + + [msg release]; +} + - (void)testCopyingMakesUniqueObjects { const int repeatCount = 5; TestAllTypes *msg1 = [TestAllTypes message]; diff --git a/objectivec/Tests/GPBUnittestProtos.m b/objectivec/Tests/GPBUnittestProtos.m index d19beee9..8d2948bf 100644 --- a/objectivec/Tests/GPBUnittestProtos.m +++ b/objectivec/Tests/GPBUnittestProtos.m @@ -36,6 +36,7 @@ // a descriptor as it doesn't use the classes/enums. #import "google/protobuf/Descriptor.pbobjc.m" +#import "google/protobuf/AnyTest.pbobjc.m" #import "google/protobuf/MapProto2Unittest.pbobjc.m" #import "google/protobuf/MapUnittest.pbobjc.m" #import "google/protobuf/Unittest.pbobjc.m" @@ -62,3 +63,11 @@ #import "google/protobuf/UnittestPreserveUnknownEnum.pbobjc.m" #import "google/protobuf/UnittestRuntimeProto2.pbobjc.m" #import "google/protobuf/UnittestRuntimeProto3.pbobjc.m" + +#import "google/protobuf/UnittestExtensionChainA.pbobjc.m" +#import "google/protobuf/UnittestExtensionChainB.pbobjc.m" +#import "google/protobuf/UnittestExtensionChainC.pbobjc.m" +#import "google/protobuf/UnittestExtensionChainD.pbobjc.m" +#import "google/protobuf/UnittestExtensionChainE.pbobjc.m" +// See GPBUnittestProtos2.m for for "UnittestExtensionChainF.pbobjc.m" +#import "google/protobuf/UnittestExtensionChainG.pbobjc.m" diff --git a/objectivec/Tests/GPBUnittestProtos2.m b/objectivec/Tests/GPBUnittestProtos2.m new file mode 100644 index 00000000..ef9f0702 --- /dev/null +++ b/objectivec/Tests/GPBUnittestProtos2.m @@ -0,0 +1,34 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// https://developers.google.com/protocol-buffers/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +// This one file in the chain tests is compiled by itself to ensure if was +// generated with the extra #imports needed to pull in the indirect Root class +// used in its Root registry. +#import "google/protobuf/UnittestExtensionChainF.pbobjc.m" diff --git a/objectivec/Tests/GPBWellKnownTypesTest.m b/objectivec/Tests/GPBWellKnownTypesTest.m index 78f4e637..041841dd 100644 --- a/objectivec/Tests/GPBWellKnownTypesTest.m +++ b/objectivec/Tests/GPBWellKnownTypesTest.m @@ -32,6 +32,8 @@ #import <XCTest/XCTest.h> +#import "google/protobuf/AnyTest.pbobjc.h" + // A basically random interval into the future for testing with. static const NSTimeInterval kFutureOffsetInterval = 15000; @@ -99,4 +101,58 @@ static const NSTimeInterval kTimeAccuracy = 1e-9; [duration2 release]; } +- (void)testAnyHelpers { + + // Set and extract covers most of the code. + + TestAny *subMessage = [TestAny message]; + subMessage.int32Value = 12345; + TestAny *message = [TestAny message]; + NSError *err = nil; + message.anyValue = [GPBAny anyWithMessage:subMessage error:&err]; + XCTAssertNil(err); + + NSData *data = message.data; + XCTAssertNotNil(data); + + TestAny *message2 = [TestAny parseFromData:data error:&err]; + XCTAssertNil(err); + XCTAssertNotNil(message2); + XCTAssertTrue(message2.hasAnyValue); + + TestAny *subMessage2 = + (TestAny *)[message.anyValue unpackMessageClass:[TestAny class] + error:&err]; + XCTAssertNil(err); + XCTAssertNotNil(subMessage2); + XCTAssertEqual(subMessage2.int32Value, 12345); + + // NULL errorPtr in the two calls. + + message.anyValue = [GPBAny anyWithMessage:subMessage error:NULL]; + NSData *data2 = message.data; + XCTAssertEqualObjects(data2, data); + + TestAny *subMessage3 = + (TestAny *)[message.anyValue unpackMessageClass:[TestAny class] + error:NULL]; + XCTAssertNotNil(subMessage3); + XCTAssertEqualObjects(subMessage2, subMessage3); + + // Try to extract wrong type. + + GPBTimestamp *wrongMessage = + (GPBTimestamp *)[message.anyValue unpackMessageClass:[GPBTimestamp class] + error:&err]; + XCTAssertNotNil(err); + XCTAssertNil(wrongMessage); + XCTAssertEqualObjects(err.domain, GPBWellKnownTypesErrorDomain); + XCTAssertEqual(err.code, GPBWellKnownTypesErrorCodeTypeURLMismatch); + + wrongMessage = + (GPBTimestamp *)[message.anyValue unpackMessageClass:[GPBTimestamp class] + error:NULL]; + XCTAssertNil(wrongMessage); +} + @end diff --git a/objectivec/Tests/unittest_cycle.proto b/objectivec/Tests/unittest_cycle.proto index 5f6f56a1..afc1b0fe 100644 --- a/objectivec/Tests/unittest_cycle.proto +++ b/objectivec/Tests/unittest_cycle.proto @@ -31,10 +31,8 @@ syntax = "proto2"; package protobuf_unittest; -// Cycles in the Message graph can cause problems for the mutable classes -// since the properties on the mutable class change types. This file just -// needs to generate source, and that source must compile, to ensure the -// generated source works for this sort of case. +// Cycles in the Message graph can cause problems for message class +// initialization order. // You can't make a object graph that spans files, so this can only be done // within a single proto file. diff --git a/objectivec/Tests/unittest_extension_chain_a.proto b/objectivec/Tests/unittest_extension_chain_a.proto new file mode 100644 index 00000000..6a227eb9 --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_a.proto @@ -0,0 +1,51 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "google/protobuf/unittest.proto"; + +import "unittest_extension_chain_b.proto"; +import "unittest_extension_chain_c.proto"; +import "unittest_extension_chain_d.proto"; + +// The Root for this file should end up adding the local extension and merging +// in the extensions from D's Root (unittest and C will come via D's). + +message ChainAMessage { + optional ChainBMessage b = 1; + optional ChainCMessage c = 2; + optional ChainDMessage d = 3; +} + +extend TestAllExtensions { + optional int32 chain_a_extension = 10001; +} diff --git a/objectivec/Tests/unittest_extension_chain_b.proto b/objectivec/Tests/unittest_extension_chain_b.proto new file mode 100644 index 00000000..0da7ed3e --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_b.proto @@ -0,0 +1,47 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "google/protobuf/unittest.proto"; + +import "unittest_extension_chain_c.proto"; + +// The Root for this file should end up adding the local extension and merging +// in the extensions from C's Root (unittest will come via C's). + +message ChainBMessage { + optional ChainCMessage c = 1; +} + +extend TestAllExtensions { + optional int32 chain_b_extension = 10002; +} diff --git a/objectivec/Tests/unittest_extension_chain_c.proto b/objectivec/Tests/unittest_extension_chain_c.proto new file mode 100644 index 00000000..c702900a --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_c.proto @@ -0,0 +1,45 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "google/protobuf/unittest.proto"; + +// The Root for this file should end up adding the local extension and merging +// in the extensions from unittest.proto's Root. + +message ChainCMessage { + optional int32 my_field = 1; +} + +extend TestAllExtensions { + optional int32 chain_c_extension = 10003; +} diff --git a/objectivec/Tests/unittest_extension_chain_d.proto b/objectivec/Tests/unittest_extension_chain_d.proto new file mode 100644 index 00000000..f9abe3ba --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_d.proto @@ -0,0 +1,49 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "google/protobuf/unittest.proto"; + +import "unittest_extension_chain_b.proto"; +import "unittest_extension_chain_c.proto"; + +// The root should end up needing to merge B (C will be merged into B, so it +// doesn't need to be directly merged). + +message ChainDMessage { + optional ChainBMessage b = 1; + optional ChainCMessage c = 2; +} + +extend TestAllExtensions { + optional int32 chain_d_extension = 10004; +} diff --git a/objectivec/Tests/unittest_extension_chain_e.proto b/objectivec/Tests/unittest_extension_chain_e.proto new file mode 100644 index 00000000..fe116631 --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_e.proto @@ -0,0 +1,40 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "google/protobuf/unittest.proto"; + +// The Root for this file should end up just merging in unittest's Root. + +message ChainEMessage { + optional TestAllTypes my_field = 1; +} diff --git a/objectivec/Tests/unittest_extension_chain_f.proto b/objectivec/Tests/unittest_extension_chain_f.proto new file mode 100644 index 00000000..b9bed723 --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_f.proto @@ -0,0 +1,44 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "unittest_extension_chain_g.proto"; + +// The Root for this file should just be merging in the extensions from C's +// Root (because G doens't define anything itself). + +// The generated source will also have to directly import C's .h file so it can +// compile the reference to C's Root class. + +message ChainFMessage { + optional ChainGMessage g = 1; +} diff --git a/objectivec/Tests/unittest_extension_chain_g.proto b/objectivec/Tests/unittest_extension_chain_g.proto new file mode 100644 index 00000000..aee827b1 --- /dev/null +++ b/objectivec/Tests/unittest_extension_chain_g.proto @@ -0,0 +1,41 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2016 Google Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto2"; + +package protobuf_unittest; + +import "unittest_extension_chain_c.proto"; + +// The Root for this file should just be merging in the extensions from C's +// Root. + +message ChainGMessage { + optional ChainCMessage c = 1; +} diff --git a/objectivec/Tests/unittest_objc.proto b/objectivec/Tests/unittest_objc.proto index 914945eb..e5577faf 100644 --- a/objectivec/Tests/unittest_objc.proto +++ b/objectivec/Tests/unittest_objc.proto @@ -34,6 +34,15 @@ import "google/protobuf/unittest.proto"; package protobuf_unittest; +// Used to check that Headerdocs and appledoc work correctly. If these comments +// are not handled correctly, Xcode will fail to build the tests. +message TestGeneratedComments { + // This is a string that could contain stuff like + // mime types as image/* or */plain. Maybe twitter usernames + // like @protobuf, @google or @something. + optional string string_field = 1; +} + // Using the messages in unittest.proto, setup for recursive cases for testing // extensions at various depths. extend TestAllExtensions { diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h index 4253b604..b88b786a 100644 --- a/objectivec/google/protobuf/Any.pbobjc.h +++ b/objectivec/google/protobuf/Any.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBAnyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBAnyRoot : GPBRootObject @end @@ -46,101 +48,105 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { GPBAny_FieldNumber_Value = 2, }; -/// `Any` contains an arbitrary serialized protocol buffer message along with a -/// URL that describes the type of the serialized message. -/// -/// Protobuf library provides support to pack/unpack Any values in the form -/// of utility functions or additional generated methods of the Any type. -/// -/// Example 1: Pack and unpack a message in C++. -/// -/// Foo foo = ...; -/// Any any; -/// any.PackFrom(foo); -/// ... -/// if (any.UnpackTo(&foo)) { -/// ... -/// } -/// -/// Example 2: Pack and unpack a message in Java. -/// -/// Foo foo = ...; -/// Any any = Any.pack(foo); -/// ... -/// if (any.is(Foo.class)) { -/// foo = any.unpack(Foo.class); -/// } -/// -/// Example 3: Pack and unpack a message in Python. -/// -/// foo = Foo(...) -/// any = Any() -/// any.Pack(foo) -/// ... -/// if any.Is(Foo.DESCRIPTOR): -/// any.Unpack(foo) -/// ... -/// -/// The pack methods provided by protobuf library will by default use -/// 'type.googleapis.com/full.type.name' as the type URL and the unpack -/// methods only use the fully qualified type name after the last '/' -/// in the type URL, for example "foo.bar.com/x/y.z" will yield type -/// name "y.z". -/// -/// -/// JSON -/// ==== -/// The JSON representation of an `Any` value uses the regular -/// representation of the deserialized, embedded message, with an -/// additional field `\@type` which contains the type URL. Example: -/// -/// package google.profile; -/// message Person { -/// string first_name = 1; -/// string last_name = 2; -/// } -/// -/// { -/// "\@type": "type.googleapis.com/google.profile.Person", -/// "firstName": <string>, -/// "lastName": <string> -/// } -/// -/// If the embedded message type is well-known and has a custom JSON -/// representation, that representation will be embedded adding a field -/// `value` which holds the custom JSON in addition to the `\@type` -/// field. Example (for message [google.protobuf.Duration][]): -/// -/// { -/// "\@type": "type.googleapis.com/google.protobuf.Duration", -/// "value": "1.212s" -/// } +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * JSON + * ==== + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `\@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "\@type": "type.googleapis.com/google.profile.Person", + * "firstName": <string>, + * "lastName": <string> + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `\@type` + * field. Example (for message [google.protobuf.Duration][]): + * + * { + * "\@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + **/ @interface GPBAny : GPBMessage -/// A URL/resource name whose content describes the type of the -/// serialized protocol buffer message. -/// -/// For URLs which use the scheme `http`, `https`, or no scheme, the -/// following restrictions and interpretations apply: -/// -/// * If no scheme is provided, `https` is assumed. -/// * The last segment of the URL's path must represent the fully -/// qualified name of the type (as in `path/google.protobuf.Duration`). -/// The name should be in a canonical form (e.g., leading "." is -/// not accepted). -/// * An HTTP GET on the URL must yield a [google.protobuf.Type][] -/// value in binary format, or produce an error. -/// * Applications are allowed to cache lookup results based on the -/// URL, or have them precompiled into a binary to avoid any -/// lookup. Therefore, binary compatibility needs to be preserved -/// on changes to types. (Use versioned type names to manage -/// breaking changes.) -/// -/// Schemes other than `http`, `https` (or the empty scheme) might be -/// used with implementation specific semantics. +/** + * A URL/resource name whose content describes the type of the + * serialized protocol buffer message. + * + * For URLs which use the scheme `http`, `https`, or no scheme, the + * following restrictions and interpretations apply: + * + * * If no scheme is provided, `https` is assumed. + * * The last segment of the URL's path must represent the fully + * qualified name of the type (as in `path/google.protobuf.Duration`). + * The name should be in a canonical form (e.g., leading "." is + * not accepted). + * * An HTTP GET on the URL must yield a [google.protobuf.Type][] + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// Must be a valid serialized protocol buffer of the above specified type. +/** Must be a valid serialized protocol buffer of the above specified type. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/objectivec/google/protobuf/Any.pbobjc.m b/objectivec/google/protobuf/Any.pbobjc.m index 25e5b4c4..e1054926 100644 --- a/objectivec/google/protobuf/Any.pbobjc.m +++ b/objectivec/google/protobuf/Any.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBAnyRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBAnyRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBAnyRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -68,7 +72,7 @@ typedef struct GPBAny__storage_ { .number = GPBAny_FieldNumber_TypeURL, .hasIndex = 0, .offset = (uint32_t)offsetof(GPBAny__storage_, typeURL), - .flags = GPBFieldOptional | GPBFieldTextFormatNameCustom, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldTextFormatNameCustom), .dataType = GPBDataTypeString, }, { @@ -88,7 +92,7 @@ typedef struct GPBAny__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBAny__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; #if !GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS static const char *extraTextFormatInfo = "\001\001\004\241!!\000"; diff --git a/objectivec/google/protobuf/Api.pbobjc.h b/objectivec/google/protobuf/Api.pbobjc.h index 04341f47..3750e093 100644 --- a/objectivec/google/protobuf/Api.pbobjc.h +++ b/objectivec/google/protobuf/Api.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -34,14 +34,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBApiRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBApiRoot : GPBRootObject @end @@ -57,67 +59,79 @@ typedef GPB_ENUM(GPBApi_FieldNumber) { GPBApi_FieldNumber_Syntax = 7, }; -/// Api is a light-weight descriptor for a protocol buffer service. +/** + * Api is a light-weight descriptor for a protocol buffer service. + **/ @interface GPBApi : GPBMessage -/// The fully qualified name of this api, including package name -/// followed by the api's simple name. +/** + * The fully qualified name of this api, including package name + * followed by the api's simple name. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The methods of this api, in unspecified order. +/** The methods of this api, in unspecified order. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMethod*> *methodsArray; -/// The number of items in @c methodsArray without causing the array to be created. +/** The number of items in @c methodsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger methodsArray_Count; -/// Any metadata attached to the API. +/** Any metadata attached to the API. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// A version string for this api. If specified, must have the form -/// `major-version.minor-version`, as in `1.10`. If the minor version -/// is omitted, it defaults to zero. If the entire version field is -/// empty, the major version is derived from the package name, as -/// outlined below. If the field is not empty, the version in the -/// package name will be verified to be consistent with what is -/// provided here. -/// -/// The versioning schema uses [semantic -/// versioning](http://semver.org) where the major version number -/// indicates a breaking change and the minor version an additive, -/// non-breaking change. Both version numbers are signals to users -/// what to expect from different versions, and should be carefully -/// chosen based on the product plan. -/// -/// The major version is also reflected in the package name of the -/// API, which must end in `v<major-version>`, as in -/// `google.feature.v1`. For major versions 0 and 1, the suffix can -/// be omitted. Zero major versions must only be used for -/// experimental, none-GA apis. +/** + * A version string for this api. If specified, must have the form + * `major-version.minor-version`, as in `1.10`. If the minor version + * is omitted, it defaults to zero. If the entire version field is + * empty, the major version is derived from the package name, as + * outlined below. If the field is not empty, the version in the + * package name will be verified to be consistent with what is + * provided here. + * + * The versioning schema uses [semantic + * versioning](http://semver.org) where the major version number + * indicates a breaking change and the minor version an additive, + * non-breaking change. Both version numbers are signals to users + * what to expect from different versions, and should be carefully + * chosen based on the product plan. + * + * The major version is also reflected in the package name of the + * API, which must end in `v<major-version>`, as in + * `google.feature.v1`. For major versions 0 and 1, the suffix can + * be omitted. Zero major versions must only be used for + * experimental, none-GA apis. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *version; -/// Source context for the protocol buffer service represented by this -/// message. +/** + * Source context for the protocol buffer service represented by this + * message. + **/ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// Included APIs. See [Mixin][]. +/** Included APIs. See [Mixin][]. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMixin*> *mixinsArray; -/// The number of items in @c mixinsArray without causing the array to be created. +/** The number of items in @c mixinsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger mixinsArray_Count; -/// The source syntax of the service. +/** The source syntax of the service. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBApi's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBApi's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBApi_Syntax_RawValue(GPBApi *message); -/// Sets the raw value of an @c GPBApi's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBApi's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBApi_Syntax_RawValue(GPBApi *message, int32_t value); #pragma mark - GPBMethod @@ -132,40 +146,46 @@ typedef GPB_ENUM(GPBMethod_FieldNumber) { GPBMethod_FieldNumber_Syntax = 7, }; -/// Method represents a method of an api. +/** + * Method represents a method of an api. + **/ @interface GPBMethod : GPBMessage -/// The simple name of this method. +/** The simple name of this method. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// A URL of the input message type. +/** A URL of the input message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *requestTypeURL; -/// If true, the request is streamed. +/** If true, the request is streamed. */ @property(nonatomic, readwrite) BOOL requestStreaming; -/// The URL of the output message type. +/** The URL of the output message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *responseTypeURL; -/// If true, the response is streamed. +/** If true, the response is streamed. */ @property(nonatomic, readwrite) BOOL responseStreaming; -/// Any metadata attached to the method. +/** Any metadata attached to the method. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source syntax of this method. +/** The source syntax of this method. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBMethod's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBMethod's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBMethod_Syntax_RawValue(GPBMethod *message); -/// Sets the raw value of an @c GPBMethod's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBMethod's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBMethod_Syntax_RawValue(GPBMethod *message, int32_t value); #pragma mark - GPBMixin @@ -175,90 +195,94 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) { GPBMixin_FieldNumber_Root = 2, }; -/// Declares an API to be included in this API. The including API must -/// redeclare all the methods from the included API, but documentation -/// and options are inherited as follows: -/// -/// - If after comment and whitespace stripping, the documentation -/// string of the redeclared method is empty, it will be inherited -/// from the original method. -/// -/// - Each annotation belonging to the service config (http, -/// visibility) which is not set in the redeclared method will be -/// inherited. -/// -/// - If an http annotation is inherited, the path pattern will be -/// modified as follows. Any version prefix will be replaced by the -/// version of the including API plus the [root][] path if specified. -/// -/// Example of a simple mixin: -/// -/// package google.acl.v1; -/// service AccessControl { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v1/{resource=**}:getAcl"; -/// } -/// } -/// -/// package google.storage.v2; -/// service Storage { -/// rpc GetAcl(GetAclRequest) returns (Acl); -/// -/// // Get a data record. -/// rpc GetData(GetDataRequest) returns (Data) { -/// option (google.api.http).get = "/v2/{resource=**}"; -/// } -/// } -/// -/// Example of a mixin configuration: -/// -/// apis: -/// - name: google.storage.v2.Storage -/// mixins: -/// - name: google.acl.v1.AccessControl -/// -/// The mixin construct implies that all methods in `AccessControl` are -/// also declared with same name and request/response types in -/// `Storage`. A documentation generator or annotation processor will -/// see the effective `Storage.GetAcl` method after inherting -/// documentation and annotations as follows: -/// -/// service Storage { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v2/{resource=**}:getAcl"; -/// } -/// ... -/// } -/// -/// Note how the version in the path pattern changed from `v1` to `v2`. -/// -/// If the `root` field in the mixin is specified, it should be a -/// relative path under which inherited HTTP paths are placed. Example: -/// -/// apis: -/// - name: google.storage.v2.Storage -/// mixins: -/// - name: google.acl.v1.AccessControl -/// root: acls -/// -/// This implies the following inherited HTTP annotation: -/// -/// service Storage { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; -/// } -/// ... -/// } +/** + * Declares an API to be included in this API. The including API must + * redeclare all the methods from the included API, but documentation + * and options are inherited as follows: + * + * - If after comment and whitespace stripping, the documentation + * string of the redeclared method is empty, it will be inherited + * from the original method. + * + * - Each annotation belonging to the service config (http, + * visibility) which is not set in the redeclared method will be + * inherited. + * + * - If an http annotation is inherited, the path pattern will be + * modified as follows. Any version prefix will be replaced by the + * version of the including API plus the [root][] path if specified. + * + * Example of a simple mixin: + * + * package google.acl.v1; + * service AccessControl { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v1/{resource=**}:getAcl"; + * } + * } + * + * package google.storage.v2; + * service Storage { + * rpc GetAcl(GetAclRequest) returns (Acl); + * + * // Get a data record. + * rpc GetData(GetDataRequest) returns (Data) { + * option (google.api.http).get = "/v2/{resource=**}"; + * } + * } + * + * Example of a mixin configuration: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * + * The mixin construct implies that all methods in `AccessControl` are + * also declared with same name and request/response types in + * `Storage`. A documentation generator or annotation processor will + * see the effective `Storage.GetAcl` method after inherting + * documentation and annotations as follows: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/{resource=**}:getAcl"; + * } + * ... + * } + * + * Note how the version in the path pattern changed from `v1` to `v2`. + * + * If the `root` field in the mixin is specified, it should be a + * relative path under which inherited HTTP paths are placed. Example: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * root: acls + * + * This implies the following inherited HTTP annotation: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; + * } + * ... + * } + **/ @interface GPBMixin : GPBMessage -/// The fully qualified name of the API which is included. +/** The fully qualified name of the API which is included. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// If non-empty specifies a path under which inherited HTTP paths -/// are rooted. +/** + * If non-empty specifies a path under which inherited HTTP paths + * are rooted. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *root; @end diff --git a/objectivec/google/protobuf/Api.pbobjc.m b/objectivec/google/protobuf/Api.pbobjc.m index cd37edaa..70437d49 100644 --- a/objectivec/google/protobuf/Api.pbobjc.m +++ b/objectivec/google/protobuf/Api.pbobjc.m @@ -31,18 +31,8 @@ @implementation GPBApiRoot -+ (GPBExtensionRegistry*)extensionRegistry { - // This is called by +initialize so there is no need to worry - // about thread safety and initialization of registry. - static GPBExtensionRegistry* registry = nil; - if (!registry) { - GPBDebugCheckRuntimeVersion(); - registry = [[GPBExtensionRegistry alloc] init]; - [registry addExtensions:[GPBSourceContextRoot extensionRegistry]]; - [registry addExtensions:[GPBTypeRoot extensionRegistry]]; - } - return registry; -} +// No extensions in the file and none of the imports (direct or indirect) +// defined extensions, so no need to generate +extensionRegistry. @end @@ -55,6 +45,7 @@ static GPBFileDescriptor *GPBApiRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -149,7 +140,7 @@ typedef struct GPBApi__storage_ { .number = GPBApi_FieldNumber_Syntax, .hasIndex = 3, .offset = (uint32_t)offsetof(GPBApi__storage_, syntax), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, }; @@ -160,7 +151,7 @@ typedef struct GPBApi__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBApi__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -223,7 +214,7 @@ typedef struct GPBMethod__storage_ { .number = GPBMethod_FieldNumber_RequestTypeURL, .hasIndex = 1, .offset = (uint32_t)offsetof(GPBMethod__storage_, requestTypeURL), - .flags = GPBFieldOptional | GPBFieldTextFormatNameCustom, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldTextFormatNameCustom), .dataType = GPBDataTypeString, }, { @@ -241,7 +232,7 @@ typedef struct GPBMethod__storage_ { .number = GPBMethod_FieldNumber_ResponseTypeURL, .hasIndex = 4, .offset = (uint32_t)offsetof(GPBMethod__storage_, responseTypeURL), - .flags = GPBFieldOptional | GPBFieldTextFormatNameCustom, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldTextFormatNameCustom), .dataType = GPBDataTypeString, }, { @@ -268,7 +259,7 @@ typedef struct GPBMethod__storage_ { .number = GPBMethod_FieldNumber_Syntax, .hasIndex = 7, .offset = (uint32_t)offsetof(GPBMethod__storage_, syntax), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, }; @@ -279,7 +270,7 @@ typedef struct GPBMethod__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBMethod__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; #if !GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS static const char *extraTextFormatInfo = "\002\002\007\244\241!!\000\004\010\244\241!!\000"; @@ -350,7 +341,7 @@ typedef struct GPBMixin__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBMixin__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Duration.pbobjc.h b/objectivec/google/protobuf/Duration.pbobjc.h index 4c3173d3..090eb002 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.h +++ b/objectivec/google/protobuf/Duration.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBDurationRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBDurationRoot : GPBRootObject @end @@ -46,58 +48,64 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) { GPBDuration_FieldNumber_Nanos = 2, }; -/// A Duration represents a signed, fixed-length span of time represented -/// as a count of seconds and fractions of seconds at nanosecond -/// resolution. It is independent of any calendar and concepts like "day" -/// or "month". It is related to Timestamp in that the difference between -/// two Timestamp values is a Duration and it can be added or subtracted -/// from a Timestamp. Range is approximately +-10,000 years. -/// -/// Example 1: Compute Duration from two Timestamps in pseudo code. -/// -/// Timestamp start = ...; -/// Timestamp end = ...; -/// Duration duration = ...; -/// -/// duration.seconds = end.seconds - start.seconds; -/// duration.nanos = end.nanos - start.nanos; -/// -/// if (duration.seconds < 0 && duration.nanos > 0) { -/// duration.seconds += 1; -/// duration.nanos -= 1000000000; -/// } else if (durations.seconds > 0 && duration.nanos < 0) { -/// duration.seconds -= 1; -/// duration.nanos += 1000000000; -/// } -/// -/// Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. -/// -/// Timestamp start = ...; -/// Duration duration = ...; -/// Timestamp end = ...; -/// -/// end.seconds = start.seconds + duration.seconds; -/// end.nanos = start.nanos + duration.nanos; -/// -/// if (end.nanos < 0) { -/// end.seconds -= 1; -/// end.nanos += 1000000000; -/// } else if (end.nanos >= 1000000000) { -/// end.seconds += 1; -/// end.nanos -= 1000000000; -/// } +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + **/ @interface GPBDuration : GPBMessage -/// Signed seconds of the span of time. Must be from -315,576,000,000 -/// to +315,576,000,000 inclusive. +/** + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Signed fractions of a second at nanosecond resolution of the span -/// of time. Durations less than one second are represented with a 0 -/// `seconds` field and a positive or negative `nanos` field. For durations -/// of one second or more, a non-zero value for the `nanos` field must be -/// of the same sign as the `seconds` field. Must be from -999,999,999 -/// to +999,999,999 inclusive. +/** + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Duration.pbobjc.m b/objectivec/google/protobuf/Duration.pbobjc.m index 35daa3df..f87d35db 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.m +++ b/objectivec/google/protobuf/Duration.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBDurationRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBDurationRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBDurationRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -88,7 +92,7 @@ typedef struct GPBDuration__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBDuration__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Empty.pbobjc.h b/objectivec/google/protobuf/Empty.pbobjc.h index 2d2a86bc..e0ed3e16 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.h +++ b/objectivec/google/protobuf/Empty.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,28 +28,32 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBEmptyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBEmptyRoot : GPBRootObject @end #pragma mark - GPBEmpty -/// A generic empty message that you can re-use to avoid defining duplicated -/// empty messages in your APIs. A typical example is to use it as the request -/// or the response type of an API method. For instance: -/// -/// service Foo { -/// rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); -/// } -/// -/// The JSON representation for `Empty` is empty JSON object `{}`. +/** + * A generic empty message that you can re-use to avoid defining duplicated + * empty messages in your APIs. A typical example is to use it as the request + * or the response type of an API method. For instance: + * + * service Foo { + * rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); + * } + * + * The JSON representation for `Empty` is empty JSON object `{}`. + **/ @interface GPBEmpty : GPBMessage @end diff --git a/objectivec/google/protobuf/Empty.pbobjc.m b/objectivec/google/protobuf/Empty.pbobjc.m index 1bdd4949..9b60f36d 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.m +++ b/objectivec/google/protobuf/Empty.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBEmptyRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBEmptyRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBEmptyRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -64,7 +68,7 @@ typedef struct GPBEmpty__storage_ { fields:NULL fieldCount:0 storageSize:sizeof(GPBEmpty__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.h b/objectivec/google/protobuf/FieldMask.pbobjc.h index 06053f1a..14ed5379 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBFieldMaskRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBFieldMaskRoot : GPBRootObject @end @@ -45,212 +47,214 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { GPBFieldMask_FieldNumber_PathsArray = 1, }; -/// `FieldMask` represents a set of symbolic field paths, for example: -/// -/// paths: "f.a" -/// paths: "f.b.d" -/// -/// Here `f` represents a field in some root message, `a` and `b` -/// fields in the message found in `f`, and `d` a field found in the -/// message in `f.b`. -/// -/// Field masks are used to specify a subset of fields that should be -/// returned by a get operation or modified by an update operation. -/// Field masks also have a custom JSON encoding (see below). -/// -/// # Field Masks in Projections -/// -/// When used in the context of a projection, a response message or -/// sub-message is filtered by the API to only contain those fields as -/// specified in the mask. For example, if the mask in the previous -/// example is applied to a response message as follows: -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// x : 2 -/// } -/// y : 13 -/// } -/// z: 8 -/// -/// The result will not contain specific values for fields x,y and z -/// (their value will be set to the default, and omitted in proto text -/// output): -/// -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// } -/// } -/// -/// A repeated field is not allowed except at the last position of a -/// field mask. -/// -/// If a FieldMask object is not present in a get operation, the -/// operation applies to all fields (as if a FieldMask of all fields -/// had been specified). -/// -/// Note that a field mask does not necessarily apply to the -/// top-level response message. In case of a REST get operation, the -/// field mask applies directly to the response, but in case of a REST -/// list operation, the mask instead applies to each individual message -/// in the returned resource list. In case of a REST custom method, -/// other definitions may be used. Where the mask applies will be -/// clearly documented together with its declaration in the API. In -/// any case, the effect on the returned resource/resources is required -/// behavior for APIs. -/// -/// # Field Masks in Update Operations -/// -/// A field mask in update operations specifies which fields of the -/// targeted resource are going to be updated. The API is required -/// to only change the values of the fields as specified in the mask -/// and leave the others untouched. If a resource is passed in to -/// describe the updated values, the API ignores the values of all -/// fields not covered by the mask. -/// -/// If a repeated field is specified for an update operation, the existing -/// repeated values in the target resource will be overwritten by the new values. -/// Note that a repeated field is only allowed in the last position of a field -/// mask. -/// -/// If a sub-message is specified in the last position of the field mask for an -/// update operation, then the existing sub-message in the target resource is -/// overwritten. Given the target message: -/// -/// f { -/// b { -/// d : 1 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// And an update message: -/// -/// f { -/// b { -/// d : 10 -/// } -/// } -/// -/// then if the field mask is: -/// -/// paths: "f.b" -/// -/// then the result will be: -/// -/// f { -/// b { -/// d : 10 -/// } -/// c : 1 -/// } -/// -/// However, if the update mask was: -/// -/// paths: "f.b.d" -/// -/// then the result would be: -/// -/// f { -/// b { -/// d : 10 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// In order to reset a field's value to the default, the field must -/// be in the mask and set to the default value in the provided resource. -/// Hence, in order to reset all fields of a resource, provide a default -/// instance of the resource and set all fields in the mask, or do -/// not provide a mask as described below. -/// -/// If a field mask is not present on update, the operation applies to -/// all fields (as if a field mask of all fields has been specified). -/// Note that in the presence of schema evolution, this may mean that -/// fields the client does not know and has therefore not filled into -/// the request will be reset to their default. If this is unwanted -/// behavior, a specific service may require a client to always specify -/// a field mask, producing an error if not. -/// -/// As with get operations, the location of the resource which -/// describes the updated values in the request message depends on the -/// operation kind. In any case, the effect of the field mask is -/// required to be honored by the API. -/// -/// ## Considerations for HTTP REST -/// -/// The HTTP kind of an update operation which uses a field mask must -/// be set to PATCH instead of PUT in order to satisfy HTTP semantics -/// (PUT must only be used for full updates). -/// -/// # JSON Encoding of Field Masks -/// -/// In JSON, a field mask is encoded as a single string where paths are -/// separated by a comma. Fields name in each path are converted -/// to/from lower-camel naming conventions. -/// -/// As an example, consider the following message declarations: -/// -/// message Profile { -/// User user = 1; -/// Photo photo = 2; -/// } -/// message User { -/// string display_name = 1; -/// string address = 2; -/// } -/// -/// In proto a field mask for `Profile` may look as such: -/// -/// mask { -/// paths: "user.display_name" -/// paths: "photo" -/// } -/// -/// In JSON, the same mask is represented as below: -/// -/// { -/// mask: "user.displayName,photo" -/// } -/// -/// # Field Masks and Oneof Fields -/// -/// Field masks treat fields in oneofs just as regular fields. Consider the -/// following message: -/// -/// message SampleMessage { -/// oneof test_oneof { -/// string name = 4; -/// SubMessage sub_message = 9; -/// } -/// } -/// -/// The field mask can be: -/// -/// mask { -/// paths: "name" -/// } -/// -/// Or: -/// -/// mask { -/// paths: "sub_message" -/// } -/// -/// Note that oneof type names ("test_oneof" in this case) cannot be used in -/// paths. +/** + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * field mask. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, the existing + * repeated values in the target resource will be overwritten by the new values. + * Note that a repeated field is only allowed in the last position of a field + * mask. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then the existing sub-message in the target resource is + * overwritten. Given the target message: + * + * f { + * b { + * d : 1 + * x : 2 + * } + * c : 1 + * } + * + * And an update message: + * + * f { + * b { + * d : 10 + * } + * } + * + * then if the field mask is: + * + * paths: "f.b" + * + * then the result will be: + * + * f { + * b { + * d : 10 + * } + * c : 1 + * } + * + * However, if the update mask was: + * + * paths: "f.b.d" + * + * then the result would be: + * + * f { + * b { + * d : 10 + * x : 2 + * } + * c : 1 + * } + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + **/ @interface GPBFieldMask : GPBMessage -/// The set of field mask paths. +/** The set of field mask paths. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *pathsArray; -/// The number of items in @c pathsArray without causing the array to be created. +/** The number of items in @c pathsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger pathsArray_Count; @end diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.m b/objectivec/google/protobuf/FieldMask.pbobjc.m index 2721fdfa..4dc8409c 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.m +++ b/objectivec/google/protobuf/FieldMask.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBFieldMaskRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBFieldMaskRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBFieldMaskRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -77,7 +81,7 @@ typedef struct GPBFieldMask__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBFieldMask__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/SourceContext.pbobjc.h b/objectivec/google/protobuf/SourceContext.pbobjc.h index 4514fa9f..417562c0 100644 --- a/objectivec/google/protobuf/SourceContext.pbobjc.h +++ b/objectivec/google/protobuf/SourceContext.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBSourceContextRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBSourceContextRoot : GPBRootObject @end @@ -45,12 +47,16 @@ typedef GPB_ENUM(GPBSourceContext_FieldNumber) { GPBSourceContext_FieldNumber_FileName = 1, }; -/// `SourceContext` represents information about the source of a -/// protobuf element, like the file in which it is defined. +/** + * `SourceContext` represents information about the source of a + * protobuf element, like the file in which it is defined. + **/ @interface GPBSourceContext : GPBMessage -/// The path-qualified name of the .proto file that contained the associated -/// protobuf element. For example: `"google/protobuf/source_context.proto"`. +/** + * The path-qualified name of the .proto file that contained the associated + * protobuf element. For example: `"google/protobuf/source_context.proto"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *fileName; @end diff --git a/objectivec/google/protobuf/SourceContext.pbobjc.m b/objectivec/google/protobuf/SourceContext.pbobjc.m index 6e3c9c07..648d736c 100644 --- a/objectivec/google/protobuf/SourceContext.pbobjc.m +++ b/objectivec/google/protobuf/SourceContext.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBSourceContextRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBSourceContextRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBSourceContextRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -77,7 +81,7 @@ typedef struct GPBSourceContext__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBSourceContext__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Struct.pbobjc.h b/objectivec/google/protobuf/Struct.pbobjc.h index 3e2d55fd..163b39ba 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.h +++ b/objectivec/google/protobuf/Struct.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -32,35 +32,43 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBNullValue -/// `NullValue` is a singleton enumeration to represent the null value for the -/// `Value` type union. -/// -/// The JSON representation for `NullValue` is JSON `null`. +/** + * `NullValue` is a singleton enumeration to represent the null value for the + * `Value` type union. + * + * The JSON representation for `NullValue` is JSON `null`. + **/ typedef GPB_ENUM(GPBNullValue) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBNullValue_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Null value. + /** Null value. */ GPBNullValue_NullValue = 0, }; GPBEnumDescriptor *GPBNullValue_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBNullValue_IsValidValue(int32_t value); #pragma mark - GPBStructRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBStructRoot : GPBRootObject @end @@ -70,19 +78,21 @@ typedef GPB_ENUM(GPBStruct_FieldNumber) { GPBStruct_FieldNumber_Fields = 1, }; -/// `Struct` represents a structured data value, consisting of fields -/// which map to dynamically typed values. In some languages, `Struct` -/// might be supported by a native representation. For example, in -/// scripting languages like JS a struct is represented as an -/// object. The details of that representation are described together -/// with the proto support for the language. -/// -/// The JSON representation for `Struct` is JSON object. +/** + * `Struct` represents a structured data value, consisting of fields + * which map to dynamically typed values. In some languages, `Struct` + * might be supported by a native representation. For example, in + * scripting languages like JS a struct is represented as an + * object. The details of that representation are described together + * with the proto support for the language. + * + * The JSON representation for `Struct` is JSON object. + **/ @interface GPBStruct : GPBMessage -/// Unordered map of dynamically typed values. +/** Unordered map of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableDictionary<NSString*, GPBValue*> *fields; -/// The number of items in @c fields without causing the array to be created. +/** The number of items in @c fields without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fields_Count; @end @@ -108,46 +118,54 @@ typedef GPB_ENUM(GPBValue_Kind_OneOfCase) { GPBValue_Kind_OneOfCase_ListValue = 6, }; -/// `Value` represents a dynamically typed value which can be either -/// null, a number, a string, a boolean, a recursive struct value, or a -/// list of values. A producer of value is expected to set one of that -/// variants, absence of any variant indicates an error. -/// -/// The JSON representation for `Value` is JSON value. +/** + * `Value` represents a dynamically typed value which can be either + * null, a number, a string, a boolean, a recursive struct value, or a + * list of values. A producer of value is expected to set one of that + * variants, absence of any variant indicates an error. + * + * The JSON representation for `Value` is JSON value. + **/ @interface GPBValue : GPBMessage -/// The kind of value. +/** The kind of value. */ @property(nonatomic, readonly) GPBValue_Kind_OneOfCase kindOneOfCase; -/// Represents a null value. +/** Represents a null value. */ @property(nonatomic, readwrite) GPBNullValue nullValue; -/// Represents a double value. +/** Represents a double value. */ @property(nonatomic, readwrite) double numberValue; -/// Represents a string value. +/** Represents a string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *stringValue; -/// Represents a boolean value. +/** Represents a boolean value. */ @property(nonatomic, readwrite) BOOL boolValue; -/// Represents a structured value. +/** Represents a structured value. */ @property(nonatomic, readwrite, strong, null_resettable) GPBStruct *structValue; -/// Represents a repeated `Value`. +/** Represents a repeated `Value`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBListValue *listValue; @end -/// Fetches the raw value of a @c GPBValue's @c nullValue property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBValue's @c nullValue property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBValue_NullValue_RawValue(GPBValue *message); -/// Sets the raw value of an @c GPBValue's @c nullValue property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBValue's @c nullValue property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value); -/// Clears whatever value was set for the oneof 'kind'. +/** + * Clears whatever value was set for the oneof 'kind'. + **/ void GPBValue_ClearKindOneOfCase(GPBValue *message); #pragma mark - GPBListValue @@ -156,14 +174,16 @@ typedef GPB_ENUM(GPBListValue_FieldNumber) { GPBListValue_FieldNumber_ValuesArray = 1, }; -/// `ListValue` is a wrapper around a repeated field of values. -/// -/// The JSON representation for `ListValue` is JSON array. +/** + * `ListValue` is a wrapper around a repeated field of values. + * + * The JSON representation for `ListValue` is JSON array. + **/ @interface GPBListValue : GPBMessage -/// Repeated field of dynamically typed values. +/** Repeated field of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBValue*> *valuesArray; -/// The number of items in @c valuesArray without causing the array to be created. +/** The number of items in @c valuesArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger valuesArray_Count; @end diff --git a/objectivec/google/protobuf/Struct.pbobjc.m b/objectivec/google/protobuf/Struct.pbobjc.m index 538faab3..bc9f23ff 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.m +++ b/objectivec/google/protobuf/Struct.pbobjc.m @@ -28,6 +28,9 @@ @implementation GPBStructRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBStructRoot_FileDescriptor @@ -39,6 +42,7 @@ static GPBFileDescriptor *GPBStructRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -110,7 +114,7 @@ typedef struct GPBStruct__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBStruct__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -152,7 +156,7 @@ typedef struct GPBValue__storage_ { .number = GPBValue_FieldNumber_NullValue, .hasIndex = -1, .offset = (uint32_t)offsetof(GPBValue__storage_, nullValue), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, { @@ -208,7 +212,7 @@ typedef struct GPBValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; static const char *oneofs[] = { "kind", }; @@ -237,7 +241,7 @@ void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value) { void GPBValue_ClearKindOneOfCase(GPBValue *message) { GPBDescriptor *descriptor = [message descriptor]; - GPBOneofDescriptor *oneof = descriptor->oneofs_[0]; + GPBOneofDescriptor *oneof = [descriptor.oneofs objectAtIndex:0]; GPBMaybeClearOneof(message, oneof, -1, 0); } #pragma mark - GPBListValue @@ -274,7 +278,7 @@ typedef struct GPBListValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBListValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.h b/objectivec/google/protobuf/Timestamp.pbobjc.h index d15de7c7..094e9b6b 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.h +++ b/objectivec/google/protobuf/Timestamp.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBTimestampRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTimestampRoot : GPBRootObject @end @@ -46,70 +48,76 @@ typedef GPB_ENUM(GPBTimestamp_FieldNumber) { GPBTimestamp_FieldNumber_Nanos = 2, }; -/// A Timestamp represents a point in time independent of any time zone -/// or calendar, represented as seconds and fractions of seconds at -/// nanosecond resolution in UTC Epoch time. It is encoded using the -/// Proleptic Gregorian Calendar which extends the Gregorian calendar -/// backwards to year one. It is encoded assuming all minutes are 60 -/// seconds long, i.e. leap seconds are "smeared" so that no leap second -/// table is needed for interpretation. Range is from -/// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. -/// By restricting to that range, we ensure that we can convert to -/// and from RFC 3339 date strings. -/// See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). -/// -/// Example 1: Compute Timestamp from POSIX `time()`. -/// -/// Timestamp timestamp; -/// timestamp.set_seconds(time(NULL)); -/// timestamp.set_nanos(0); -/// -/// Example 2: Compute Timestamp from POSIX `gettimeofday()`. -/// -/// struct timeval tv; -/// gettimeofday(&tv, NULL); -/// -/// Timestamp timestamp; -/// timestamp.set_seconds(tv.tv_sec); -/// timestamp.set_nanos(tv.tv_usec * 1000); -/// -/// Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. -/// -/// FILETIME ft; -/// GetSystemTimeAsFileTime(&ft); -/// UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; -/// -/// // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z -/// // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. -/// Timestamp timestamp; -/// timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); -/// timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); -/// -/// Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. -/// -/// long millis = System.currentTimeMillis(); -/// -/// Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) -/// .setNanos((int) ((millis % 1000) * 1000000)).build(); -/// -/// -/// Example 5: Compute Timestamp from current time in Python. -/// -/// now = time.time() -/// seconds = int(now) -/// nanos = int((now - seconds) * 10**9) -/// timestamp = Timestamp(seconds=seconds, nanos=nanos) +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * now = time.time() + * seconds = int(now) + * nanos = int((now - seconds) * 10**9) + * timestamp = Timestamp(seconds=seconds, nanos=nanos) + **/ @interface GPBTimestamp : GPBMessage -/// Represents seconds of UTC time since Unix epoch -/// 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to -/// 9999-12-31T23:59:59Z inclusive. +/** + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Non-negative fractions of a second at nanosecond resolution. Negative -/// second values with fractions must still have non-negative nanos values -/// that count forward in time. Must be from 0 to 999,999,999 -/// inclusive. +/** + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.m b/objectivec/google/protobuf/Timestamp.pbobjc.m index 06e3ef94..1506dff3 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.m +++ b/objectivec/google/protobuf/Timestamp.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBTimestampRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBTimestampRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBTimestampRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -88,7 +92,7 @@ typedef struct GPBTimestamp__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBTimestamp__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Type.pbobjc.h b/objectivec/google/protobuf/Type.pbobjc.h index 93ee3cec..da923c30 100644 --- a/objectivec/google/protobuf/Type.pbobjc.h +++ b/objectivec/google/protobuf/Type.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -34,134 +34,148 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBSyntax -/// The syntax in which a protocol buffer element is defined. +/** The syntax in which a protocol buffer element is defined. */ typedef GPB_ENUM(GPBSyntax) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBSyntax_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Syntax `proto2`. + /** Syntax `proto2`. */ GPBSyntax_SyntaxProto2 = 0, - /// Syntax `proto3`. + /** Syntax `proto3`. */ GPBSyntax_SyntaxProto3 = 1, }; GPBEnumDescriptor *GPBSyntax_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBSyntax_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Kind -/// Basic field types. +/** Basic field types. */ typedef GPB_ENUM(GPBField_Kind) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Kind_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Field type unknown. + /** Field type unknown. */ GPBField_Kind_TypeUnknown = 0, - /// Field type double. + /** Field type double. */ GPBField_Kind_TypeDouble = 1, - /// Field type float. + /** Field type float. */ GPBField_Kind_TypeFloat = 2, - /// Field type int64. + /** Field type int64. */ GPBField_Kind_TypeInt64 = 3, - /// Field type uint64. + /** Field type uint64. */ GPBField_Kind_TypeUint64 = 4, - /// Field type int32. + /** Field type int32. */ GPBField_Kind_TypeInt32 = 5, - /// Field type fixed64. + /** Field type fixed64. */ GPBField_Kind_TypeFixed64 = 6, - /// Field type fixed32. + /** Field type fixed32. */ GPBField_Kind_TypeFixed32 = 7, - /// Field type bool. + /** Field type bool. */ GPBField_Kind_TypeBool = 8, - /// Field type string. + /** Field type string. */ GPBField_Kind_TypeString = 9, - /// Field type group. Proto2 syntax only, and deprecated. + /** Field type group. Proto2 syntax only, and deprecated. */ GPBField_Kind_TypeGroup = 10, - /// Field type message. + /** Field type message. */ GPBField_Kind_TypeMessage = 11, - /// Field type bytes. + /** Field type bytes. */ GPBField_Kind_TypeBytes = 12, - /// Field type uint32. + /** Field type uint32. */ GPBField_Kind_TypeUint32 = 13, - /// Field type enum. + /** Field type enum. */ GPBField_Kind_TypeEnum = 14, - /// Field type sfixed32. + /** Field type sfixed32. */ GPBField_Kind_TypeSfixed32 = 15, - /// Field type sfixed64. + /** Field type sfixed64. */ GPBField_Kind_TypeSfixed64 = 16, - /// Field type sint32. + /** Field type sint32. */ GPBField_Kind_TypeSint32 = 17, - /// Field type sint64. + /** Field type sint64. */ GPBField_Kind_TypeSint64 = 18, }; GPBEnumDescriptor *GPBField_Kind_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Kind_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Cardinality -/// Whether a field is optional, required, or repeated. +/** Whether a field is optional, required, or repeated. */ typedef GPB_ENUM(GPBField_Cardinality) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Cardinality_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// For fields with unknown cardinality. + /** For fields with unknown cardinality. */ GPBField_Cardinality_CardinalityUnknown = 0, - /// For optional fields. + /** For optional fields. */ GPBField_Cardinality_CardinalityOptional = 1, - /// For required fields. Proto2 syntax only. + /** For required fields. Proto2 syntax only. */ GPBField_Cardinality_CardinalityRequired = 2, - /// For repeated fields. + /** For repeated fields. */ GPBField_Cardinality_CardinalityRepeated = 3, }; GPBEnumDescriptor *GPBField_Cardinality_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Cardinality_IsValidValue(int32_t value); #pragma mark - GPBTypeRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTypeRoot : GPBRootObject @end @@ -176,43 +190,49 @@ typedef GPB_ENUM(GPBType_FieldNumber) { GPBType_FieldNumber_Syntax = 6, }; -/// A protocol buffer message type. +/** + * A protocol buffer message type. + **/ @interface GPBType : GPBMessage -/// The fully qualified message name. +/** The fully qualified message name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The list of fields. +/** The list of fields. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBField*> *fieldsArray; -/// The number of items in @c fieldsArray without causing the array to be created. +/** The number of items in @c fieldsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fieldsArray_Count; -/// The list of types appearing in `oneof` definitions in this type. +/** The list of types appearing in `oneof` definitions in this type. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *oneofsArray; -/// The number of items in @c oneofsArray without causing the array to be created. +/** The number of items in @c oneofsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger oneofsArray_Count; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBType's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBType's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBType_Syntax_RawValue(GPBType *message); -/// Sets the raw value of an @c GPBType's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBType's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBType_Syntax_RawValue(GPBType *message, int32_t value); #pragma mark - GPBField @@ -230,59 +250,73 @@ typedef GPB_ENUM(GPBField_FieldNumber) { GPBField_FieldNumber_DefaultValue = 11, }; -/// A single field of a message type. +/** + * A single field of a message type. + **/ @interface GPBField : GPBMessage -/// The field type. +/** The field type. */ @property(nonatomic, readwrite) GPBField_Kind kind; -/// The field cardinality. +/** The field cardinality. */ @property(nonatomic, readwrite) GPBField_Cardinality cardinality; -/// The field number. +/** The field number. */ @property(nonatomic, readwrite) int32_t number; -/// The field name. +/** The field name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The field type URL, without the scheme, for message or enumeration -/// types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. +/** + * The field type URL, without the scheme, for message or enumeration + * types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// The index of the field type in `Type.oneofs`, for message or enumeration -/// types. The first type has index 1; zero means the type is not in the list. +/** + * The index of the field type in `Type.oneofs`, for message or enumeration + * types. The first type has index 1; zero means the type is not in the list. + **/ @property(nonatomic, readwrite) int32_t oneofIndex; -/// Whether to use alternative packed wire representation. +/** Whether to use alternative packed wire representation. */ @property(nonatomic, readwrite) BOOL packed; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The field JSON name. +/** The field JSON name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *jsonName; -/// The string value of the default value of this field. Proto2 syntax only. +/** The string value of the default value of this field. Proto2 syntax only. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *defaultValue; @end -/// Fetches the raw value of a @c GPBField's @c kind property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c kind property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Kind_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c kind property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c kind property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Kind_RawValue(GPBField *message, int32_t value); -/// Fetches the raw value of a @c GPBField's @c cardinality property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c cardinality property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Cardinality_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c cardinality property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c cardinality property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Cardinality_RawValue(GPBField *message, int32_t value); #pragma mark - GPBEnum @@ -295,38 +329,44 @@ typedef GPB_ENUM(GPBEnum_FieldNumber) { GPBEnum_FieldNumber_Syntax = 5, }; -/// Enum type definition. +/** + * Enum type definition. + **/ @interface GPBEnum : GPBMessage -/// Enum type name. +/** Enum type name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value definitions. +/** Enum value definitions. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBEnumValue*> *enumvalueArray; -/// The number of items in @c enumvalueArray without causing the array to be created. +/** The number of items in @c enumvalueArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger enumvalueArray_Count; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBEnum's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBEnum's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBEnum_Syntax_RawValue(GPBEnum *message); -/// Sets the raw value of an @c GPBEnum's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBEnum's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBEnum_Syntax_RawValue(GPBEnum *message, int32_t value); #pragma mark - GPBEnumValue @@ -337,18 +377,20 @@ typedef GPB_ENUM(GPBEnumValue_FieldNumber) { GPBEnumValue_FieldNumber_OptionsArray = 3, }; -/// Enum value definition. +/** + * Enum value definition. + **/ @interface GPBEnumValue : GPBMessage -/// Enum value name. +/** Enum value name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value number. +/** Enum value number. */ @property(nonatomic, readwrite) int32_t number; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; @end @@ -360,16 +402,18 @@ typedef GPB_ENUM(GPBOption_FieldNumber) { GPBOption_FieldNumber_Value = 2, }; -/// A protocol buffer option, which can be attached to a message, field, -/// enumeration, etc. +/** + * A protocol buffer option, which can be attached to a message, field, + * enumeration, etc. + **/ @interface GPBOption : GPBMessage -/// The option's name. For example, `"java_package"`. +/** The option's name. For example, `"java_package"`. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The option's value. For example, `"com.google.protobuf"`. +/** The option's value. For example, `"com.google.protobuf"`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBAny *value; -/// Test to see if @c value has been set. +/** Test to see if @c value has been set. */ @property(nonatomic, readwrite) BOOL hasValue; @end diff --git a/objectivec/google/protobuf/Type.pbobjc.m b/objectivec/google/protobuf/Type.pbobjc.m index 6c7b4efd..a36f1cd4 100644 --- a/objectivec/google/protobuf/Type.pbobjc.m +++ b/objectivec/google/protobuf/Type.pbobjc.m @@ -31,18 +31,8 @@ @implementation GPBTypeRoot -+ (GPBExtensionRegistry*)extensionRegistry { - // This is called by +initialize so there is no need to worry - // about thread safety and initialization of registry. - static GPBExtensionRegistry* registry = nil; - if (!registry) { - GPBDebugCheckRuntimeVersion(); - registry = [[GPBExtensionRegistry alloc] init]; - [registry addExtensions:[GPBAnyRoot extensionRegistry]]; - [registry addExtensions:[GPBSourceContextRoot extensionRegistry]]; - } - return registry; -} +// No extensions in the file and none of the imports (direct or indirect) +// defined extensions, so no need to generate +extensionRegistry. @end @@ -55,6 +45,7 @@ static GPBFileDescriptor *GPBTypeRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -172,7 +163,7 @@ typedef struct GPBType__storage_ { .number = GPBType_FieldNumber_Syntax, .hasIndex = 2, .offset = (uint32_t)offsetof(GPBType__storage_, syntax), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, }; @@ -183,7 +174,7 @@ typedef struct GPBType__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBType__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -244,7 +235,7 @@ typedef struct GPBField__storage_ { .number = GPBField_FieldNumber_Kind, .hasIndex = 0, .offset = (uint32_t)offsetof(GPBField__storage_, kind), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, { @@ -253,7 +244,7 @@ typedef struct GPBField__storage_ { .number = GPBField_FieldNumber_Cardinality, .hasIndex = 1, .offset = (uint32_t)offsetof(GPBField__storage_, cardinality), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, { @@ -280,7 +271,7 @@ typedef struct GPBField__storage_ { .number = GPBField_FieldNumber_TypeURL, .hasIndex = 4, .offset = (uint32_t)offsetof(GPBField__storage_, typeURL), - .flags = GPBFieldOptional | GPBFieldTextFormatNameCustom, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldTextFormatNameCustom), .dataType = GPBDataTypeString, }, { @@ -336,7 +327,7 @@ typedef struct GPBField__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBField__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; #if !GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS static const char *extraTextFormatInfo = "\001\006\004\241!!\000"; @@ -553,7 +544,7 @@ typedef struct GPBEnum__storage_ { .number = GPBEnum_FieldNumber_Syntax, .hasIndex = 2, .offset = (uint32_t)offsetof(GPBEnum__storage_, syntax), - .flags = GPBFieldOptional | GPBFieldHasEnumDescriptor, + .flags = (GPBFieldFlags)(GPBFieldOptional | GPBFieldHasEnumDescriptor), .dataType = GPBDataTypeEnum, }, }; @@ -564,7 +555,7 @@ typedef struct GPBEnum__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBEnum__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -641,7 +632,7 @@ typedef struct GPBEnumValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBEnumValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -695,7 +686,7 @@ typedef struct GPBOption__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBOption__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.h b/objectivec/google/protobuf/Wrappers.pbobjc.h index 5593d348..2bf6fd29 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.h +++ b/objectivec/google/protobuf/Wrappers.pbobjc.h @@ -13,7 +13,7 @@ #import "GPBProtocolBuffers.h" #endif -#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30001 +#if GOOGLE_PROTOBUF_OBJC_GEN_VERSION != 30002 #error This file was generated by a different version of protoc which is incompatible with your Protocol Buffer library sources. #endif @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBWrappersRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBWrappersRoot : GPBRootObject @end @@ -45,12 +47,14 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) { GPBDoubleValue_FieldNumber_Value = 1, }; -/// Wrapper message for `double`. -/// -/// The JSON representation for `DoubleValue` is JSON number. +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + **/ @interface GPBDoubleValue : GPBMessage -/// The double value. +/** The double value. */ @property(nonatomic, readwrite) double value; @end @@ -61,12 +65,14 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) { GPBFloatValue_FieldNumber_Value = 1, }; -/// Wrapper message for `float`. -/// -/// The JSON representation for `FloatValue` is JSON number. +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + **/ @interface GPBFloatValue : GPBMessage -/// The float value. +/** The float value. */ @property(nonatomic, readwrite) float value; @end @@ -77,12 +83,14 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) { GPBInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int64`. -/// -/// The JSON representation for `Int64Value` is JSON string. +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + **/ @interface GPBInt64Value : GPBMessage -/// The int64 value. +/** The int64 value. */ @property(nonatomic, readwrite) int64_t value; @end @@ -93,12 +101,14 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) { GPBUInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint64`. -/// -/// The JSON representation for `UInt64Value` is JSON string. +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + **/ @interface GPBUInt64Value : GPBMessage -/// The uint64 value. +/** The uint64 value. */ @property(nonatomic, readwrite) uint64_t value; @end @@ -109,12 +119,14 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) { GPBInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int32`. -/// -/// The JSON representation for `Int32Value` is JSON number. +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + **/ @interface GPBInt32Value : GPBMessage -/// The int32 value. +/** The int32 value. */ @property(nonatomic, readwrite) int32_t value; @end @@ -125,12 +137,14 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) { GPBUInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint32`. -/// -/// The JSON representation for `UInt32Value` is JSON number. +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + **/ @interface GPBUInt32Value : GPBMessage -/// The uint32 value. +/** The uint32 value. */ @property(nonatomic, readwrite) uint32_t value; @end @@ -141,12 +155,14 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) { GPBBoolValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bool`. -/// -/// The JSON representation for `BoolValue` is JSON `true` and `false`. +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + **/ @interface GPBBoolValue : GPBMessage -/// The bool value. +/** The bool value. */ @property(nonatomic, readwrite) BOOL value; @end @@ -157,12 +173,14 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) { GPBStringValue_FieldNumber_Value = 1, }; -/// Wrapper message for `string`. -/// -/// The JSON representation for `StringValue` is JSON string. +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + **/ @interface GPBStringValue : GPBMessage -/// The string value. +/** The string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *value; @end @@ -173,12 +191,14 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) { GPBBytesValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bytes`. -/// -/// The JSON representation for `BytesValue` is JSON string. +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + **/ @interface GPBBytesValue : GPBMessage -/// The bytes value. +/** The bytes value. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.m b/objectivec/google/protobuf/Wrappers.pbobjc.m index b5405a7d..c8fdeb08 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.m +++ b/objectivec/google/protobuf/Wrappers.pbobjc.m @@ -27,6 +27,9 @@ @implementation GPBWrappersRoot +// No extensions in the file and no imports, so no need to generate +// +extensionRegistry. + @end #pragma mark - GPBWrappersRoot_FileDescriptor @@ -38,6 +41,7 @@ static GPBFileDescriptor *GPBWrappersRoot_FileDescriptor(void) { if (!descriptor) { GPBDebugCheckRuntimeVersion(); descriptor = [[GPBFileDescriptor alloc] initWithPackage:@"google.protobuf" + objcPrefix:@"GPB" syntax:GPBFileSyntaxProto3]; } return descriptor; @@ -77,7 +81,7 @@ typedef struct GPBDoubleValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBDoubleValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -120,7 +124,7 @@ typedef struct GPBFloatValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBFloatValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -163,7 +167,7 @@ typedef struct GPBInt64Value__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBInt64Value__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -206,7 +210,7 @@ typedef struct GPBUInt64Value__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBUInt64Value__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -249,7 +253,7 @@ typedef struct GPBInt32Value__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBInt32Value__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -292,7 +296,7 @@ typedef struct GPBUInt32Value__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBUInt32Value__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -334,7 +338,7 @@ typedef struct GPBBoolValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBBoolValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -377,7 +381,7 @@ typedef struct GPBStringValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBStringValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } @@ -420,7 +424,7 @@ typedef struct GPBBytesValue__storage_ { fields:fields fieldCount:(uint32_t)(sizeof(fields) / sizeof(GPBMessageFieldDescription)) storageSize:sizeof(GPBBytesValue__storage_) - flags:0]; + flags:GPBDescriptorInitializationFlag_None]; NSAssert(descriptor == nil, @"Startup recursed!"); descriptor = localDescriptor; } |