diff options
62 files changed, 10097 insertions, 870 deletions
diff --git a/.travis.yml b/.travis.yml index 1417cb98..094235e0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -57,6 +57,10 @@ matrix: # tests on jenkins running in parallel. - os: linux env: CONFIG=cpp_distcheck + # The Java compatibility test currently only runs on Linux because it will + # fetch pre-built Linux protoc binaries in the test. + - os: linux + env: CONFIG=java_compatibility allow_failures: # These currently do not work on OS X but are being worked on by @haberman. - os: osx @@ -2,6 +2,8 @@ licenses(["notice"]) +exports_files(["LICENSE"]) + ################################################################################ # Protobuf Runtime Library ################################################################################ diff --git a/CHANGES.txt b/CHANGES.txt index 04fa418e..822136c0 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,3 +1,54 @@ +2016-07-27 version 3.0.0 (C++/Java/Python/Ruby/Objective-C/C#/JavaScript/Lite) + General + * This log only contains changes since the beta-4 release. Summarized change + log since the last stable release (v2.6.1) can be found in the github + release page. + + Compatibility Notice + * v3.0.0 is the first API stable release of the v3.x series. We do not expect + any future API breaking changes. + * For C++, Java Lite and Objective-C, source level compatibility is + guaranteed. Upgrading from v3.0.0 to newer minor version releases will be + source compatible. For example, if your code compiles against protobuf + v3.0.0, it will continue to compile after you upgrade protobuf library to + v3.1.0. + * For other languages, both source level compatibility and binary level + compatibility are guaranteed. For example, if you have a Java binary built + against protobuf v3.0.0. After switching the protobuf runtime binary to + v3.1.0, your built binary should continue to work. + * Compatibility is only guaranteed for documented API and documented + behaviors. If you are using undocumented API (e.g., use anything in the C++ + internal namespace), it can be broken by minor version releases in an + undetermined manner. + + Ruby + * When you assign a string field `a.string_field = "X"`, we now call + #encode(UTF-8) on the string and freeze the copy. This saves you from + needing to ensure the string is already encoded as UTF-8. It also prevents + you from mutating the string after it has been assigned (this is how we + ensure it stays valid UTF-8). + * The generated file for `foo.proto` is now `foo_pb.rb` instead of just + `foo.rb`. This makes it easier to see which imports/requires are from + protobuf generated code, and also prevents conflicts with any `foo.rb` file + you might have written directly in Ruby. It is a backward-incompatible + change: you will need to update all of your `require` statements. + * For package names like `foo_bar`, we now translate this to the Ruby module + `FooBar`. This is more idiomatic Ruby than what we used to do (`Foo_bar`). + + JavaScript + * Scalar fields like numbers and boolean now return defaults instead of + `undefined` or `null` when they are unset. You can test for presence + explicitly by calling `hasFoo()`, which we now generate for scalar fields. + + Java Lite + * Java Lite is now implemented as a separate plugin, maintained in the + `javalite` branch. Both lite runtime and protoc artifacts will be available + in Maven. + + C# + * Target platforms now .NET 4.5, selected portable subsets and .NET Core. + * legacy_enum_values option is no longer supported. + 2016-07-15 version 3.0.0-beta-4 (C++/Java/Python/Ruby/Objective-C/C#/JavaScript) General * Added a deterministic serialization API for C++. The deterministic diff --git a/Makefile.am b/Makefile.am index ccbfd065..41d25823 100644 --- a/Makefile.am +++ b/Makefile.am @@ -656,6 +656,7 @@ python_EXTRA_DIST= \ python/google/protobuf/text_encoding.py \ python/google/protobuf/text_format.py \ python/mox.py \ + python/setup.cfg \ python/setup.py \ python/stubout.py \ python/tox.ini \ @@ -681,6 +682,7 @@ ruby_EXTRA_DIST= \ ruby/google-protobuf.gemspec \ ruby/lib/google/protobuf/message_exts.rb \ ruby/lib/google/protobuf/repeated_field.rb \ + ruby/lib/google/protobuf/well_known_types.rb \ ruby/lib/google/protobuf.rb \ ruby/pom.xml \ ruby/src/main/java/com/google/protobuf/jruby/RubyBuilder.java \ @@ -707,6 +709,7 @@ ruby_EXTRA_DIST= \ ruby/tests/generated_code.proto \ ruby/tests/test_import.proto \ ruby/tests/generated_code_test.rb \ + ruby/tests/well_known_types_test.rb \ ruby/travis-test.sh js_EXTRA_DIST= \ diff --git a/Protobuf.podspec b/Protobuf.podspec index ac27f03e..72e6dd0a 100644 --- a/Protobuf.podspec +++ b/Protobuf.podspec @@ -5,7 +5,7 @@ # dependent projects use the :git notation to refer to the library. Pod::Spec.new do |s| s.name = 'Protobuf' - s.version = '3.0.0-beta-4' + s.version = '3.0.0' s.summary = 'Protocol Buffers v.3 runtime library for Objective-C.' s.homepage = 'https://github.com/google/protobuf' s.license = 'New BSD' @@ -36,5 +36,6 @@ Pod::Spec.new do |s| s.ios.deployment_target = '7.1' s.osx.deployment_target = '10.9' + s.watchos.deployment_target = '2.0' s.requires_arc = false end diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 07b176d9..f947b741 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -86,6 +86,7 @@ if (CMAKE_USE_PTHREADS_INIT) add_definitions(-DHAVE_PTHREAD) endif (CMAKE_USE_PTHREADS_INIT) +set(_protobuf_FIND_ZLIB) if (protobuf_WITH_ZLIB) find_package(ZLIB) if (ZLIB_FOUND) @@ -96,6 +97,7 @@ if (protobuf_WITH_ZLIB) # Using imported target if exists if (TARGET ZLIB::ZLIB) set(ZLIB_LIBRARIES ZLIB::ZLIB) + set(_protobuf_FIND_ZLIB "if(NOT ZLIB_FOUND)\n find_package(ZLIB)\nendif()") endif (TARGET ZLIB::ZLIB) else (ZLIB_FOUND) set(HAVE_ZLIB 0) diff --git a/cmake/extract_includes.bat.in b/cmake/extract_includes.bat.in index c76973c9..9edafca8 100644 --- a/cmake/extract_includes.bat.in +++ b/cmake/extract_includes.bat.in @@ -69,7 +69,6 @@ copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\metadata.h include\goo copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\reflection.h include\google\protobuf\reflection.h copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\reflection_ops.h include\google\protobuf\reflection_ops.h copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\repeated_field.h include\google\protobuf\repeated_field.h -copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\repeated_field_reflection.h include\google\protobuf\repeated_field_reflection.h copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\service.h include\google\protobuf\service.h copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\source_context.pb.h include\google\protobuf\source_context.pb.h copy ${PROTOBUF_SOURCE_WIN32_PATH}\..\src\google\protobuf\struct.pb.h include\google\protobuf\struct.pb.h diff --git a/cmake/libprotobuf.cmake b/cmake/libprotobuf.cmake index 8930c1ca..26e1f356 100644 --- a/cmake/libprotobuf.cmake +++ b/cmake/libprotobuf.cmake @@ -56,7 +56,10 @@ set(libprotobuf_files add_library(libprotobuf ${protobuf_SHARED_OR_STATIC} ${libprotobuf_lite_files} ${libprotobuf_files}) -target_link_libraries(libprotobuf ${CMAKE_THREAD_LIBS_INIT} ${ZLIB_LIBRARIES}) +target_link_libraries(libprotobuf ${CMAKE_THREAD_LIBS_INIT}) +if(protobuf_WITH_ZLIB) + target_link_libraries(libprotobuf ${ZLIB_LIBRARIES}) +endif() target_include_directories(libprotobuf PUBLIC ${protobuf_source_dir}/src) if(MSVC AND protobuf_BUILD_SHARED_LIBS) target_compile_definitions(libprotobuf diff --git a/cmake/protobuf-config.cmake.in b/cmake/protobuf-config.cmake.in index 37315510..a044fe5c 100644 --- a/cmake/protobuf-config.cmake.in +++ b/cmake/protobuf-config.cmake.in @@ -1,6 +1,9 @@ # User options include("${CMAKE_CURRENT_LIST_DIR}/protobuf-options.cmake") +# Depend packages +@_protobuf_FIND_ZLIB@ + # Imported targets include("${CMAKE_CURRENT_LIST_DIR}/protobuf-targets.cmake") diff --git a/cmake/protobuf-module.cmake.in b/cmake/protobuf-module.cmake.in index 6e0bcf90..614e4c04 100644 --- a/cmake/protobuf-module.cmake.in +++ b/cmake/protobuf-module.cmake.in @@ -147,7 +147,6 @@ function(_protobuf_find_libraries name filename) LOCATION_RELEASE) get_target_property(${name}_LIBRARY_DEBUG protobuf::lib${filename} LOCATION_DEBUG) - endif() select_library_configurations(${name}) set(${name}_LIBRARY ${${name}_LIBRARY} PARENT_SCOPE) diff --git a/configure.ac b/configure.ac index 7ae4a88b..41887997 100644 --- a/configure.ac +++ b/configure.ac @@ -17,7 +17,7 @@ AC_PREREQ(2.59) # In the SVN trunk, the version should always be the next anticipated release # version with the "-pre" suffix. (We used to use "-SNAPSHOT" but this pushed # the size of one file name in the dist tarfile over the 99-char limit.) -AC_INIT([Protocol Buffers],[3.0.0-beta-4],[protobuf@googlegroups.com],[protobuf]) +AC_INIT([Protocol Buffers],[3.0.0],[protobuf@googlegroups.com],[protobuf]) AM_MAINTAINER_MODE([enable]) diff --git a/conformance/conformance_test.cc b/conformance/conformance_test.cc index 59a61e51..598ef732 100644 --- a/conformance/conformance_test.cc +++ b/conformance/conformance_test.cc @@ -814,18 +814,26 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, "Uint64FieldMaxValue", R"({"optionalUint64": "18446744073709551615"})", "optional_uint64: 18446744073709551615"); + // While not the largest Int64, this is the largest + // Int64 which can be exactly represented within an + // IEEE-754 64-bit float, which is the expected level + // of interoperability guarantee. Larger values may + // work in some implementations, but should not be + // relied upon. RunValidJsonTest( "Int64FieldMaxValueNotQuoted", - R"({"optionalInt64": 9223372036854775807})", - "optional_int64: 9223372036854775807"); + R"({"optionalInt64": 9223372036854774784})", + "optional_int64: 9223372036854774784"); RunValidJsonTest( "Int64FieldMinValueNotQuoted", R"({"optionalInt64": -9223372036854775808})", "optional_int64: -9223372036854775808"); + // Largest interoperable Uint64; see comment above + // for Int64FieldMaxValueNotQuoted. RunValidJsonTest( "Uint64FieldMaxValueNotQuoted", - R"({"optionalUint64": 18446744073709551615})", - "optional_uint64: 18446744073709551615"); + R"({"optionalUint64": 18446744073709549568})", + "optional_uint64: 18446744073709549568"); // Values can be represented as JSON strings. RunValidJsonTest( "Int32FieldStringValue", diff --git a/conformance/failure_list_csharp.txt b/conformance/failure_list_csharp.txt index e7de4b96..1716bcbd 100644 --- a/conformance/failure_list_csharp.txt +++ b/conformance/failure_list_csharp.txt @@ -4,8 +4,4 @@ JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FieldNameWithMixedCases.JsonOutput JsonInput.FieldNameWithMixedCases.ProtobufOutput JsonInput.FieldNameWithMixedCases.Validator -JsonInput.Int64FieldMaxValueNotQuoted.JsonOutput -JsonInput.Int64FieldMaxValueNotQuoted.ProtobufOutput JsonInput.OriginalProtoFieldName.JsonOutput -JsonInput.Uint64FieldMaxValueNotQuoted.JsonOutput -JsonInput.Uint64FieldMaxValueNotQuoted.ProtobufOutput diff --git a/csharp/Google.Protobuf.Tools.nuspec b/csharp/Google.Protobuf.Tools.nuspec index 659b2e77..24b4a776 100644 --- a/csharp/Google.Protobuf.Tools.nuspec +++ b/csharp/Google.Protobuf.Tools.nuspec @@ -5,7 +5,7 @@ <title>Google Protocol Buffers tools</title> <summary>Tools for Protocol Buffers - Google's data interchange format.</summary> <description>See project site for more info.</description> - <version>3.0.0-beta4</version> + <version>3.0.0</version> <authors>Google Inc.</authors> <owners>protobuf-packages</owners> <licenseUrl>https://github.com/google/protobuf/blob/master/LICENSE</licenseUrl> diff --git a/csharp/src/Google.Protobuf.Test/JsonFormatterTest.cs b/csharp/src/Google.Protobuf.Test/JsonFormatterTest.cs index 51b3ca2d..261ac6a7 100644 --- a/csharp/src/Google.Protobuf.Test/JsonFormatterTest.cs +++ b/csharp/src/Google.Protobuf.Test/JsonFormatterTest.cs @@ -230,6 +230,12 @@ namespace Google.Protobuf [TestCase("foo_bar", "fooBar")] [TestCase("bananaBanana", "bananaBanana")] [TestCase("BANANABanana", "bananaBanana")] + [TestCase("simple", "simple")] + [TestCase("ACTION_AND_ADVENTURE", "actionAndAdventure")] + [TestCase("action_and_adventure", "actionAndAdventure")] + [TestCase("kFoo", "kFoo")] + [TestCase("HTTPServer", "httpServer")] + [TestCase("CLIENT", "client")] public void ToCamelCase(string original, string expected) { Assert.AreEqual(expected, JsonFormatter.ToCamelCase(original)); diff --git a/csharp/src/Google.Protobuf/JsonFormatter.cs b/csharp/src/Google.Protobuf/JsonFormatter.cs index a894ffa1..d8a814d9 100644 --- a/csharp/src/Google.Protobuf/JsonFormatter.cs +++ b/csharp/src/Google.Protobuf/JsonFormatter.cs @@ -274,7 +274,6 @@ namespace Google.Protobuf } // Converted from src/google/protobuf/util/internal/utility.cc ToCamelCase - // TODO: Use the new field in FieldDescriptor. internal static string ToCamelCase(string input) { bool capitalizeNext = false; @@ -305,6 +304,7 @@ namespace Google.Protobuf (!wasCap || (i + 1 < input.Length && char.IsLower(input[i + 1])))) { firstWord = false; + result.Append(input[i]); } else { @@ -320,8 +320,16 @@ namespace Google.Protobuf result.Append(char.ToUpperInvariant(input[i])); continue; } + else + { + result.Append(input[i]); + continue; + } + } + else + { + result.Append(char.ToLowerInvariant(input[i])); } - result.Append(input[i]); } return result.ToString(); } diff --git a/csharp/src/Google.Protobuf/project.json b/csharp/src/Google.Protobuf/project.json index c8eae6d0..9b831f12 100644 --- a/csharp/src/Google.Protobuf/project.json +++ b/csharp/src/Google.Protobuf/project.json @@ -1,5 +1,5 @@ { - "version": "3.0.0-beta4", + "version": "3.0.0", "title": "Google Protocol Buffers", "description": "See project site for more info.", "authors": [ "Google Inc." ], diff --git a/editors/protobuf-mode.el b/editors/protobuf-mode.el index f615a0af..1cef4137 100644 --- a/editors/protobuf-mode.el +++ b/editors/protobuf-mode.el @@ -64,12 +64,13 @@ ;;; Code: (require 'cc-mode) +(require 'cl) (eval-when-compile (require 'cc-langs) (require 'cc-fonts)) -;; This mode does not inherit properties from other modes. So, we do not use +;; This mode does not inherit properties from other modes. So, we do not use ;; the usual `c-add-language' function. (eval-and-compile (put 'protobuf-mode 'c-mode-prefix "protobuf-")) diff --git a/java/compatibility_tests/v2.5.0/test.sh b/java/compatibility_tests/v2.5.0/test.sh index 08df12ef..5d5e9ed4 100755 --- a/java/compatibility_tests/v2.5.0/test.sh +++ b/java/compatibility_tests/v2.5.0/test.sh @@ -21,23 +21,23 @@ case "$1" in ;; 2.6.1) OLD_VERSION=2.6.1 - OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/2.6.1-build2/protoc-2.6.1-build2-linux-x86_32.exe + OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/2.6.1-build2/protoc-2.6.1-build2-linux-x86_64.exe ;; 3.0.0-beta-1) OLD_VERSION=3.0.0-beta-1 - OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-1/protoc-3.0.0-beta-1-linux-x86_32.exe + OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-1/protoc-3.0.0-beta-1-linux-x86_64.exe ;; 3.0.0-beta-2) OLD_VERSION=3.0.0-beta-2 - OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-2/protoc-3.0.0-beta-2-linux-x86_32.exe + OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-2/protoc-3.0.0-beta-2-linux-x86_64.exe ;; 3.0.0-beta-3) OLD_VERSION=3.0.0-beta-3 - OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-3/protoc-3.0.0-beta-3-linux-x86_32.exe + OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-3/protoc-3.0.0-beta-3-linux-x86_64.exe ;; 3.0.0-beta-4) OLD_VERSION=3.0.0-beta-4 - OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-4/protoc-3.0.0-beta-4-linux-x86_32.exe + OLD_VERSION_PROTOC=http://repo1.maven.org/maven2/com/google/protobuf/protoc/3.0.0-beta-4/protoc-3.0.0-beta-4-linux-x86_64.exe ;; *) echo "[ERROR]: Unknown version number: $1" diff --git a/java/core/pom.xml b/java/core/pom.xml index 422bde82..39d67818 100644 --- a/java/core/pom.xml +++ b/java/core/pom.xml @@ -6,7 +6,7 @@ <parent> <groupId>com.google.protobuf</groupId> <artifactId>protobuf-parent</artifactId> - <version>3.0.0-beta-4</version> + <version>3.0.0</version> </parent> <artifactId>protobuf-java</artifactId> diff --git a/java/lite/pom.xml b/java/lite/pom.xml index 87a5c44d..9862cd94 100644 --- a/java/lite/pom.xml +++ b/java/lite/pom.xml @@ -6,7 +6,7 @@ <parent> <groupId>com.google.protobuf</groupId> <artifactId>protobuf-parent</artifactId> - <version>3.0.0-beta-4</version> + <version>3.0.0</version> </parent> <artifactId>protobuf-lite</artifactId> diff --git a/java/pom.xml b/java/pom.xml index 2d8e9a13..3a91a0ba 100644 --- a/java/pom.xml +++ b/java/pom.xml @@ -11,7 +11,7 @@ <groupId>com.google.protobuf</groupId> <artifactId>protobuf-parent</artifactId> - <version>3.0.0-beta-4</version> + <version>3.0.0</version> <packaging>pom</packaging> <name>Protocol Buffers [Parent]</name> diff --git a/java/util/pom.xml b/java/util/pom.xml index d8f64eb1..0d5e8e37 100644 --- a/java/util/pom.xml +++ b/java/util/pom.xml @@ -6,7 +6,7 @@ <parent> <groupId>com.google.protobuf</groupId> <artifactId>protobuf-parent</artifactId> - <version>3.0.0-beta-4</version> + <version>3.0.0</version> </parent> <artifactId>protobuf-java-util</artifactId> diff --git a/js/README.md b/js/README.md index 15d48c87..f4184621 100644 --- a/js/README.md +++ b/js/README.md @@ -152,8 +152,7 @@ idea of how the library generally works: // Serializes to a UInt8Array. bytes = message.serializeBinary(); - var message2 = new MyMessage(); - message2.deserializeBinary(bytes); + var message2 = MyMessage.deserializeBinary(bytes); For more examples, see the tests. You can also look at the generated code to see what methods are defined for your generated messages. @@ -365,7 +365,7 @@ jspb.Map.prototype.serializeBinary = function( valueWriterFn.call(writer, 2, this.wrapEntry_(entry), opt_valueWriterCallback); } else { - valueWriterFn_.call(writer, 2, entry.value); + valueWriterFn.call(writer, 2, entry.value); } writer.endSubMessage(); } diff --git a/js/package.json b/js/package.json index 76ce0c1d..3f51d96b 100644 --- a/js/package.json +++ b/js/package.json @@ -1,6 +1,6 @@ { "name": "google-protobuf", - "version": "3.0.0-alpha.7", + "version": "3.0.0", "description": "Protocol Buffers for JavaScript", "main": "google-protobuf.js", "files": [ 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/GPBBootstrap.h b/objectivec/GPBBootstrap.h index 4db08e80..2e5bdc71 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. +// +// Meant to be used internally by generated code. #define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30001 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/GPBDescriptor.h b/objectivec/GPBDescriptor.h index fe4ff390..36fb4eae 100644 --- a/objectivec/GPBDescriptor.h +++ b/objectivec/GPBDescriptor.h @@ -39,104 +39,241 @@ 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; +/** + * 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 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/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..b395db17 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 GPBExtensionDescripto 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 7e0f58a3..0cb74f9f 100644 --- a/objectivec/GPBMessage.h +++ b/objectivec/GPBMessage.h @@ -44,285 +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; -/// Returns an array with the currently set GPBExtensionDescriptors. +/** + * @return An array with the extension descriptors that are currently set on the + * message. + **/ - (NSArray *)extensionsCurrentlySet; -/// Test to see if the given extension is set on the message. +/** + * 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/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/GPBWellKnownTypes.h b/objectivec/GPBWellKnownTypes.h index 311ac58e..96d51d9e 100644 --- a/objectivec/GPBWellKnownTypes.h +++ b/objectivec/GPBWellKnownTypes.h @@ -46,18 +46,54 @@ NS_ASSUME_NONNULL_BEGIN -// Extension to GPBTimestamp to work with standard Foundation time/date types. +/** + * 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. */ @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. +/** + * Category for GPBDuration to work with standard Foundation time type. + **/ @interface GPBDuration (GBPWellKnownTypes) + +/** The NSTimeInterval representation of this GPBTimestamp. */ @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 GPBTimestamp. + **/ - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970; + @end NS_ASSUME_NONNULL_END diff --git a/protoc-artifacts/build-protoc.sh b/protoc-artifacts/build-protoc.sh index 88e6ae50..e31948e9 100755 --- a/protoc-artifacts/build-protoc.sh +++ b/protoc-artifacts/build-protoc.sh @@ -1,17 +1,30 @@ #!/bin/bash -# Builds protoc executable into target/protoc.exe +# Builds protoc executable into target/protoc.exe; optionally build protoc +# plugins into target/protoc-gen-*.exe # To be run from Maven. -# Usage: build-protoc.sh <OS> <ARCH> +# Usage: build-protoc.sh <OS> <ARCH> <TARGET> # <OS> and <ARCH> are ${os.detected.name} and ${os.detected.arch} from os-maven-plugin +# <TARGET> can be "protoc" or "protoc-gen-javalite" OS=$1 ARCH=$2 +MAKE_TARGET=$3 -if [[ $# < 2 ]]; then +if [[ $# < 3 ]]; then echo "No arguments provided. This script is intended to be run from Maven." exit 1 fi +case $MAKE_TARGET in + protoc-gen-javalite) + ;; + protoc) + ;; + *) + echo "Target ""$TARGET"" invalid." + exit 1 +esac + # Under Cygwin, bash doesn't have these in PATH when called from Maven which # runs in Windows version of Java. export PATH="/bin:/usr/bin:$PATH" @@ -126,7 +139,7 @@ checkDependencies () } ############################################################################ -echo "Building protoc, OS=$OS ARCH=$ARCH" +echo "Building protoc, OS=$OS ARCH=$ARCH TARGET=$TARGET" # Nested double quotes are unintuitive, but it works. cd "$(dirname "$0")" @@ -134,7 +147,7 @@ cd "$(dirname "$0")" WORKING_DIR=$(pwd) CONFIGURE_ARGS="--disable-shared" -MAKE_TARGET="protoc" +TARGET_FILE=target/$MAKE_TARGET.exe if [[ "$OS" == windows ]]; then MAKE_TARGET="${MAKE_TARGET}.exe" fi @@ -209,12 +222,10 @@ fi export CXXFLAGS LDFLAGS -TARGET_FILE=target/protoc.exe - cd "$WORKING_DIR"/.. && ./configure $CONFIGURE_ARGS && cd src && make clean && make $MAKE_TARGET && cd "$WORKING_DIR" && mkdir -p target && - (cp ../src/protoc $TARGET_FILE || cp ../src/protoc.exe $TARGET_FILE) || + cp ../src/$MAKE_TARGET $TARGET_FILE || exit 1 if [[ "$OS" == osx ]]; then diff --git a/protoc-artifacts/build-zip.sh b/protoc-artifacts/build-zip.sh index 054e2ea1..3c5e887b 100755 --- a/protoc-artifacts/build-zip.sh +++ b/protoc-artifacts/build-zip.sh @@ -1,26 +1,30 @@ #!/bin/bash -if [ $# -eq 0 ]; then +if [ $# -ne 2 ]; then cat <<EOF -Usage: $0 <VERSION_NUMBER> +Usage: $0 <TARGET> <VERSION_NUMBER> + +TARGET: protoc | protoc-gen-javalite Example: - $ $0 3.0.0-beta-4 + $ $0 protoc 3.0.0 + $ $0 protoc-gen-javalite 3.0.0 -This script will download pre-built protoc binaries from maven repository -and package them with well-known type .proto files to create .zip packages -suitable to be included in the github release page. Each invocation will -create 5 zip packages: - dist/protoc-<VERSION_NUMBER>-win32.zip - dist/protoc-<VERSION_NUMBER>-osx-x86_32.zip - dist/protoc-<VERSION_NUMBER>-osx-x86_64.zip - dist/protoc-<VERSION_NUMBER>-linux-x86_32.zip - dist/protoc-<VERSION_NUMBER>-linux-x86_64.zip +This script will download pre-built protoc or protoc plugin binaries from maven +repository and create .zip packages suitable to be included in the github +release page. If the target is protoc, well-known type .proto files will also be +included. Each invocation will create 5 zip packages: + dist/<TARGET>-<VERSION_NUMBER>-win32.zip + dist/<TARGET>-<VERSION_NUMBER>-osx-x86_32.zip + dist/<TARGET>-<VERSION_NUMBER>-osx-x86_64.zip + dist/<TARGET>-<VERSION_NUMBER>-linux-x86_32.zip + dist/<TARGET>-<VERSION_NUMBER>-linux-x86_64.zip EOF exit 1 fi -VERSION_NUMBER=$1 +TARGET=$1 +VERSION_NUMBER=$2 # <zip file name> <binary file name> pairs. declare -a FILE_NAMES=( \ @@ -78,17 +82,27 @@ mkdir -p ${DIR}/bin # Create a zip file for each binary. for((i=0;i<${#FILE_NAMES[@]};i+=2));do ZIP_NAME=${FILE_NAMES[$i]} + if [ ${ZIP_NAME:0:3} = "win" ]; then + BINARY="$TARGET.exe" + else + BINARY="$TARGET" + fi BINARY_NAME=${FILE_NAMES[$(($i+1))]} - BINARY_URL=http://repo1.maven.org/maven2/com/google/protobuf/protoc/${VERSION_NUMBER}/protoc-${VERSION_NUMBER}-${BINARY_NAME} - if ! wget ${BINARY_URL} -O ${DIR}/bin/protoc &> /dev/null; then + BINARY_URL=http://repo1.maven.org/maven2/com/google/protobuf/$TARGET/${VERSION_NUMBER}/$TARGET-${VERSION_NUMBER}-${BINARY_NAME} + if ! wget ${BINARY_URL} -O ${DIR}/bin/$BINARY &> /dev/null; then echo "[ERROR] Failed to download ${BINARY_URL}" >&2 - echo "[ERROR] Skipped protoc-${VERSION_NAME}-${ZIP_NAME}" >&2 + echo "[ERROR] Skipped $TARGET-${VERSION_NAME}-${ZIP_NAME}" >&2 continue fi - TARGET_ZIP_FILE=`pwd`/dist/protoc-${VERSION_NUMBER}-${ZIP_NAME} + TARGET_ZIP_FILE=`pwd`/dist/$TARGET-${VERSION_NUMBER}-${ZIP_NAME} pushd $DIR &> /dev/null - chmod +x bin/protoc - zip -r ${TARGET_ZIP_FILE} include bin readme.txt &> /dev/null + chmod +x bin/$BINARY + if [ "$TARGET" = "protoc" ]; then + zip -r ${TARGET_ZIP_FILE} include bin readme.txt &> /dev/null + else + zip -r ${TARGET_ZIP_FILE} bin &> /dev/null + fi + rm bin/$BINARY popd &> /dev/null echo "[INFO] Successfully created ${TARGET_ZIP_FILE}" done diff --git a/protoc-artifacts/pom.xml b/protoc-artifacts/pom.xml index 8fad896a..840bc60a 100644 --- a/protoc-artifacts/pom.xml +++ b/protoc-artifacts/pom.xml @@ -10,7 +10,7 @@ </parent> <groupId>com.google.protobuf</groupId> <artifactId>protoc</artifactId> - <version>3.0.0-beta-4</version> + <version>3.0.0</version> <packaging>pom</packaging> <name>Protobuf Compiler</name> <description> @@ -59,6 +59,7 @@ <argument>build-protoc.sh</argument> <argument>${os.detected.name}</argument> <argument>${os.detected.arch}</argument> + <argument>protoc</argument> </arguments> </configuration> </plugin> diff --git a/python/google/protobuf/__init__.py b/python/google/protobuf/__init__.py index 7213496e..6210a404 100755 --- a/python/google/protobuf/__init__.py +++ b/python/google/protobuf/__init__.py @@ -30,7 +30,7 @@ # Copyright 2007 Google Inc. All Rights Reserved. -__version__ = '3.0.0b4' +__version__ = '3.0.0' if __name__ != '__main__': try: diff --git a/python/google/protobuf/json_format.py b/python/google/protobuf/json_format.py index bb6a1998..edc0cb50 100644 --- a/python/google/protobuf/json_format.py +++ b/python/google/protobuf/json_format.py @@ -310,7 +310,7 @@ def Parse(text, message, ignore_unknown_fields=False): Args: text: Message JSON representation. - message: A protocol beffer message to merge into. + message: A protocol buffer message to merge into. ignore_unknown_fields: If True, do not raise errors for unknown fields. Returns: diff --git a/python/setup.cfg b/python/setup.cfg new file mode 100644 index 00000000..2a9acf13 --- /dev/null +++ b/python/setup.cfg @@ -0,0 +1,2 @@ +[bdist_wheel] +universal = 1 diff --git a/ruby/google-protobuf.gemspec b/ruby/google-protobuf.gemspec index 8cf40e3f..286d8fe3 100644 --- a/ruby/google-protobuf.gemspec +++ b/ruby/google-protobuf.gemspec @@ -1,6 +1,6 @@ Gem::Specification.new do |s| s.name = "google-protobuf" - s.version = "3.0.0.alpha.7.0.0" + s.version = "3.0.0" s.licenses = ["BSD"] s.summary = "Protocol Buffers" s.description = "Protocol Buffers are Google's data interchange format." diff --git a/ruby/lib/google/protobuf/well_known_types.rb b/ruby/lib/google/protobuf/well_known_types.rb new file mode 100644 index 00000000..547de874 --- /dev/null +++ b/ruby/lib/google/protobuf/well_known_types.rb @@ -0,0 +1,212 @@ +#!/usr/bin/ruby +# Protocol Buffers - Google's data interchange format +# Copyright 2008 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. + +require 'google/protobuf/any_pb' +require 'google/protobuf/duration_pb' +require 'google/protobuf/field_mask_pb' +require 'google/protobuf/struct_pb' +require 'google/protobuf/timestamp_pb' + +module Google + module Protobuf + + Any.class_eval do + def pack(msg, type_url_prefix='type.googleapis.com/') + if type_url_prefix.empty? or type_url_prefix[-1] != '/' then + self.type_url = "#{type_url_prefix}/#{msg.class.descriptor.name}" + else + self.type_url = "#{type_url_prefix}#{msg.class.descriptor.name}" + end + self.value = msg.to_proto + end + + def unpack(klass) + if self.is(klass) then + klass.decode(self.value) + else + nil + end + end + + def type_name + return self.type_url.split("/")[-1] + end + + def is(klass) + return self.type_name == klass.descriptor.name + end + end + + Timestamp.class_eval do + def to_time + Time.at(self.to_f) + end + + def from_time(time) + self.seconds = time.to_i + self.nanos = time.nsec + end + + def to_i + self.seconds + end + + def to_f + self.seconds + (self.nanos.to_f / 1_000_000_000) + end + end + + Duration.class_eval do + def to_f + self.seconds + (self.nanos.to_f / 1_000_000_000) + end + end + + class UnexpectedStructType < Google::Protobuf::Error; end + + Value.class_eval do + def to_ruby(recursive = false) + case self.kind + when :struct_value + if recursive + self.struct_value.to_h + else + self.struct_value + end + when :list_value + if recursive + self.list_value.to_a + else + self.list_value + end + when :null_value + nil + when :number_value + self.number_value + when :string_value + self.string_value + when :bool_value + self.bool_value + else + raise UnexpectedStructType + end + end + + def from_ruby(value) + case value + when NilClass + self.null_value = 0 + when Numeric + self.number_value = value + when String + self.string_value = value + when TrueClass + self.bool_value = true + when FalseClass + self.bool_value = false + when Struct + self.struct_value = value + when Hash + self.struct_value = Struct.from_hash(value) + when ListValue + self.list_value = value + when Array + self.list_value = ListValue.from_a(value) + else + raise UnexpectedStructType + end + end + end + + Struct.class_eval do + def [](key) + self.fields[key].to_ruby + end + + def []=(key, value) + unless key.is_a?(String) + raise UnexpectedStructType, "Struct keys must be strings." + end + self.fields[key] ||= Google::Protobuf::Value.new + self.fields[key].from_ruby(value) + end + + def to_h + ret = {} + self.fields.each { |key, val| ret[key] = val.to_ruby(true) } + ret + end + + def self.from_hash(hash) + ret = Struct.new + hash.each { |key, val| ret[key] = val } + ret + end + end + + ListValue.class_eval do + include Enumerable + + def length + self.values.length + end + + def [](index) + self.values[index].to_ruby + end + + def []=(index, value) + self.values[index].from_ruby(value) + end + + def <<(value) + wrapper = Google::Protobuf::Value.new + wrapper.from_ruby(value) + self.values << wrapper + end + + def each + self.values.each { |x| yield(x.to_ruby) } + end + + def to_a + self.values.map { |x| x.to_ruby(true) } + end + + def self.from_a(arr) + ret = ListValue.new + arr.each { |val| ret << val } + ret + end + end + + end +end diff --git a/ruby/pom.xml b/ruby/pom.xml index 62845815..99e8449b 100644 --- a/ruby/pom.xml +++ b/ruby/pom.xml @@ -86,7 +86,7 @@ <dependency> <groupId>com.google.protobuf</groupId> <artifactId>protobuf-java</artifactId> - <version>3.0.0-beta-3</version> + <version>3.0.0-beta-4</version> </dependency> </dependencies> </project> diff --git a/ruby/tests/basic.rb b/ruby/tests/basic.rb index f81e456c..8b6d329e 100644 --- a/ruby/tests/basic.rb +++ b/ruby/tests/basic.rb @@ -468,9 +468,9 @@ module BasicTest assert m.length == 2 m2 = m.dup - assert m == m2 + assert_equal m, m2 assert m.hash != 0 - assert m.hash == m2.hash + assert_equal m.hash, m2.hash collected = {} m.each { |k,v| collected[v] = k } diff --git a/ruby/tests/well_known_types_test.rb b/ruby/tests/well_known_types_test.rb new file mode 100644 index 00000000..9b46632b --- /dev/null +++ b/ruby/tests/well_known_types_test.rb @@ -0,0 +1,122 @@ +#!/usr/bin/ruby + +require 'test/unit' +require 'google/protobuf/well_known_types' + +class TestWellKnownTypes < Test::Unit::TestCase + def test_timestamp + ts = Google::Protobuf::Timestamp.new + + assert_equal Time.at(0), ts.to_time + + ts.seconds = 12345 + assert_equal Time.at(12345), ts.to_time + assert_equal 12345, ts.to_i + + ts.from_time(Time.at(123456, 654321)) + assert_equal 123456, ts.seconds + assert_equal 654321000, ts.nanos + assert_equal Time.at(123456.654321), ts.to_time + end + + def test_duration + duration = Google::Protobuf::Duration.new(seconds: 123, nanos: 456) + assert_equal 123.000000456, duration.to_f + end + + def test_struct + struct = Google::Protobuf::Struct.new + + substruct = { + "subkey" => 999, + "subkey2" => false + } + + sublist = ["abc", 123, {"deepkey" => "deepval"}] + + struct["number"] = 12345 + struct["boolean-true"] = true + struct["boolean-false"] = false + struct["null"] = nil + struct["string"] = "abcdef" + struct["substruct"] = substruct + struct["sublist"] = sublist + + assert_equal 12345, struct["number"] + assert_equal true, struct["boolean-true"] + assert_equal false, struct["boolean-false"] + assert_equal nil, struct["null"] + assert_equal "abcdef", struct["string"] + assert_equal(Google::Protobuf::Struct.from_hash(substruct), + struct["substruct"]) + assert_equal(Google::Protobuf::ListValue.from_a(sublist), + struct["sublist"]) + + should_equal = { + "number" => 12345, + "boolean-true" => true, + "boolean-false" => false, + "null" => nil, + "string" => "abcdef", + "substruct" => { + "subkey" => 999, + "subkey2" => false + }, + "sublist" => ["abc", 123, {"deepkey" => "deepval"}] + } + + list = struct["sublist"] + list.is_a?(Google::Protobuf::ListValue) + assert_equal "abc", list[0] + assert_equal 123, list[1] + assert_equal({"deepkey" => "deepval"}, list[2].to_h) + + # to_h returns a fully-flattened Ruby structure (Hash and Array). + assert_equal(should_equal, struct.to_h) + + # Test that we can assign Struct and ListValue directly. + struct["substruct"] = Google::Protobuf::Struct.from_hash(substruct) + struct["sublist"] = Google::Protobuf::ListValue.from_a(sublist) + + assert_equal(should_equal, struct.to_h) + + struct["sublist"] << nil + should_equal["sublist"] << nil + + assert_equal(should_equal, struct.to_h) + assert_equal(should_equal["sublist"].length, struct["sublist"].length) + + assert_raise Google::Protobuf::UnexpectedStructType do + struct[123] = 5 + end + + assert_raise Google::Protobuf::UnexpectedStructType do + struct[5] = Time.new + end + + assert_raise Google::Protobuf::UnexpectedStructType do + struct[5] = [Time.new] + end + + assert_raise Google::Protobuf::UnexpectedStructType do + struct[5] = {123 => 456} + end + + assert_raise Google::Protobuf::UnexpectedStructType do + struct = Google::Protobuf::Struct.new + struct.fields["foo"] = Google::Protobuf::Value.new + # Tries to return a Ruby value for a Value class whose type + # hasn't been filled in. + struct["foo"] + end + end + + def test_any + any = Google::Protobuf::Any.new + ts = Google::Protobuf::Timestamp.new(seconds: 12345, nanos: 6789) + any.pack(ts) + + assert any.is(Google::Protobuf::Timestamp) + assert_equal ts, any.unpack(Google::Protobuf::Timestamp) + end +end diff --git a/src/Makefile.am b/src/Makefile.am index 6e7dacfc..f70e9550 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -33,6 +33,10 @@ AM_LDFLAGS = $(PTHREAD_CFLAGS) # If I say "dist_include_DATA", automake complains that $(includedir) is not # a "legitimate" directory for DATA. Screw you, automake. protodir = $(includedir) + +# If you are adding new files here, also remember to change the build files for +# all other languages, //protoc-artifacts/build-zip.sh and run +# //update_file_list.sh for bazel. nobase_dist_proto_DATA = google/protobuf/descriptor.proto \ google/protobuf/any.proto \ google/protobuf/api.proto \ @@ -547,7 +551,7 @@ EXTRA_DIST = \ google/protobuf/package_info.h \ google/protobuf/io/package_info.h \ google/protobuf/compiler/ruby/ruby_generated_code.proto \ - google/protobuf/compiler/ruby/ruby_generated_code.rb \ + google/protobuf/compiler/ruby/ruby_generated_code_pb.rb \ google/protobuf/compiler/package_info.h \ google/protobuf/compiler/zip_output_unittest.sh \ README.md diff --git a/src/google/protobuf/compiler/csharp/csharp_enum.cc b/src/google/protobuf/compiler/csharp/csharp_enum.cc index 64381d0f..9e4da1ed 100644 --- a/src/google/protobuf/compiler/csharp/csharp_enum.cc +++ b/src/google/protobuf/compiler/csharp/csharp_enum.cc @@ -68,9 +68,7 @@ void EnumGenerator::Generate(io::Printer* printer) { for (int i = 0; i < descriptor_->value_count(); i++) { WriteEnumValueDocComment(printer, descriptor_->value(i)); string original_name = descriptor_->value(i)->name(); - string name = options()->legacy_enum_values - ? descriptor_->value(i)->name() - : GetEnumValueName(descriptor_->name(), descriptor_->value(i)->name()); + string name = GetEnumValueName(descriptor_->name(), descriptor_->value(i)->name()); // Make sure we don't get any duplicate names due to prefix removal. while (!used_names.insert(name).second) { // It's possible we'll end up giving this warning multiple times, but that's better than not at all. diff --git a/src/google/protobuf/compiler/csharp/csharp_generator.cc b/src/google/protobuf/compiler/csharp/csharp_generator.cc index d74e8c88..c13ed65b 100644 --- a/src/google/protobuf/compiler/csharp/csharp_generator.cc +++ b/src/google/protobuf/compiler/csharp/csharp_generator.cc @@ -83,9 +83,6 @@ bool Generator::Generate( cli_options.base_namespace_specified = true; } else if (options[i].first == "internal_access") { cli_options.internal_access = true; - } else if (options[i].first == "legacy_enum_values") { - // TODO: Remove this before final release - cli_options.legacy_enum_values = true; } else { *error = "Unknown generator option: " + options[i].first; return false; diff --git a/src/google/protobuf/compiler/csharp/csharp_options.h b/src/google/protobuf/compiler/csharp/csharp_options.h index 4079bf7f..426fb3b5 100644 --- a/src/google/protobuf/compiler/csharp/csharp_options.h +++ b/src/google/protobuf/compiler/csharp/csharp_options.h @@ -45,8 +45,7 @@ struct Options { file_extension(".cs"), base_namespace(""), base_namespace_specified(false), - internal_access(false), - legacy_enum_values(false) { + internal_access(false) { } // Extension of the generated file. Defaults to ".cs" string file_extension; @@ -69,12 +68,6 @@ struct Options { // Whether the generated classes should have accessibility level of "internal". // Defaults to false that generates "public" classes. bool internal_access; - // By default, C# codegen now uses PascalCased enum values names, after - // removing the enum type name as a prefix (if it *is* a prefix of the value). - // Setting this option reverts to the previous behavior of just copying the - // value name specified in the .proto file, allowing gradual migration. - // This option will be removed before final release. - bool legacy_enum_values; }; } // namespace csharp diff --git a/src/google/protobuf/stubs/atomicops_internals_generic_gcc.h b/src/google/protobuf/stubs/atomicops_internals_generic_gcc.h index a0116a60..7314ee4f 100644 --- a/src/google/protobuf/stubs/atomicops_internals_generic_gcc.h +++ b/src/google/protobuf/stubs/atomicops_internals_generic_gcc.h @@ -128,6 +128,24 @@ inline Atomic64 NoBarrier_CompareAndSwap(volatile Atomic64* ptr, return old_value; } +inline Atomic64 NoBarrier_AtomicIncrement(volatile Atomic64* ptr, + Atomic64 increment) { + return __atomic_add_fetch(ptr, increment, __ATOMIC_RELAXED); +} + +inline void NoBarrier_Store(volatile Atomic64* ptr, Atomic64 value) { + __atomic_store_n(ptr, value, __ATOMIC_RELAXED); +} + +inline Atomic64 NoBarrier_AtomicExchange(volatile Atomic64* ptr, + Atomic64 new_value) { + return __atomic_exchange_n(ptr, new_value, __ATOMIC_RELAXED); +} + +inline Atomic64 NoBarrier_Load(volatile const Atomic64* ptr) { + return __atomic_load_n(ptr, __ATOMIC_RELAXED); +} + #endif // defined(__LP64__) } // namespace internal diff --git a/src/google/protobuf/stubs/int128.cc b/src/google/protobuf/stubs/int128.cc index 3a36b4b1..a5090801 100644 --- a/src/google/protobuf/stubs/int128.cc +++ b/src/google/protobuf/stubs/int128.cc @@ -145,15 +145,15 @@ std::ostream& operator<<(std::ostream& o, const uint128& b) { std::streamsize div_base_log; switch (flags & std::ios::basefield) { case std::ios::hex: - div = GOOGLE_ULONGLONG(0x1000000000000000); // 16^15 + div = static_cast<uint64>(GOOGLE_ULONGLONG(0x1000000000000000)); // 16^15 div_base_log = 15; break; case std::ios::oct: - div = GOOGLE_ULONGLONG(01000000000000000000000); // 8^21 + div = static_cast<uint64>(GOOGLE_ULONGLONG(01000000000000000000000)); // 8^21 div_base_log = 21; break; default: // std::ios::dec - div = GOOGLE_ULONGLONG(10000000000000000000); // 10^19 + div = static_cast<uint64>(GOOGLE_ULONGLONG(10000000000000000000)); // 10^19 div_base_log = 19; break; } diff --git a/src/google/protobuf/stubs/map_util.h b/src/google/protobuf/stubs/map_util.h index 4cccbbed..887f12a6 100644 --- a/src/google/protobuf/stubs/map_util.h +++ b/src/google/protobuf/stubs/map_util.h @@ -208,7 +208,7 @@ typename Collection::value_type::second_type::element_type& FindLinkedPtrOrDie(const Collection& collection, const typename Collection::value_type::first_type& key) { typename Collection::const_iterator it = collection.find(key); - CHECK(it != collection.end()) << "key not found: " << key; + GOOGLE_CHECK(it != collection.end()) << "key not found: " << key; // Since linked_ptr::operator*() is a const member returning a non const, // we do not need a version of this function taking a non const collection. return *it->second; @@ -337,14 +337,15 @@ bool InsertIfNotPresent( template <class Collection> void InsertOrDie(Collection* const collection, const typename Collection::value_type& value) { - CHECK(InsertIfNotPresent(collection, value)) << "duplicate value: " << value; + GOOGLE_CHECK(InsertIfNotPresent(collection, value)) + << "duplicate value: " << value; } // Same as above except doesn't log the value on error. template <class Collection> void InsertOrDieNoPrint(Collection* const collection, const typename Collection::value_type& value) { - CHECK(InsertIfNotPresent(collection, value)) << "duplicate value."; + GOOGLE_CHECK(InsertIfNotPresent(collection, value)) << "duplicate value."; } // Inserts the key-value pair into the collection. Dies if key was already diff --git a/src/google/protobuf/stubs/port.h b/src/google/protobuf/stubs/port.h index 328258b7..d7f93b4c 100644 --- a/src/google/protobuf/stubs/port.h +++ b/src/google/protobuf/stubs/port.h @@ -109,15 +109,15 @@ typedef unsigned __int16 uint16; typedef unsigned __int32 uint32; typedef unsigned __int64 uint64; #else -typedef signed char int8; -typedef short int16; -typedef int int32; -typedef long long int64; - -typedef unsigned char uint8; -typedef unsigned short uint16; -typedef unsigned int uint32; -typedef unsigned long long uint64; +typedef int8_t int8; +typedef int16_t int16; +typedef int32_t int32; +typedef int64_t int64; + +typedef uint8_t uint8; +typedef uint16_t uint16; +typedef uint32_t uint32; +typedef uint64_t uint64; #endif // long long macros to be used because gcc and vc++ use different suffixes, @@ -131,8 +131,10 @@ typedef unsigned long long uint64; #define GOOGLE_ULONGLONG(x) x##UI64 #define GOOGLE_LL_FORMAT "I64" // As in printf("%I64d", ...) #else +// By long long, we actually mean int64. #define GOOGLE_LONGLONG(x) x##LL #define GOOGLE_ULONGLONG(x) x##ULL +// Used to format real long long integers. #define GOOGLE_LL_FORMAT "ll" // As in "%lld". Note that "q" is poor form also. #endif diff --git a/src/google/protobuf/testing/file.cc b/src/google/protobuf/testing/file.cc index 3d07b127..bc76c844 100644 --- a/src/google/protobuf/testing/file.cc +++ b/src/google/protobuf/testing/file.cc @@ -91,6 +91,7 @@ bool File::WriteStringToFile(const string& contents, const string& name) { if (fwrite(contents.data(), 1, contents.size(), file) != contents.size()) { GOOGLE_LOG(ERROR) << "fwrite(" << name << "): " << strerror(errno); + fclose(file); return false; } diff --git a/src/google/protobuf/util/time_util.cc b/src/google/protobuf/util/time_util.cc index c782d691..031d019a 100644 --- a/src/google/protobuf/util/time_util.cc +++ b/src/google/protobuf/util/time_util.cc @@ -142,6 +142,13 @@ int64 RoundTowardZero(int64 value, int64 divider) { } } // namespace +// Actually define these static const integers. Required by C++ standard (but +// omitting them may still work with some compilers). +const int64 TimeUtil::kTimestampMinSeconds; +const int64 TimeUtil::kTimestampMaxSeconds; +const int64 TimeUtil::kDurationMaxSeconds; +const int64 TimeUtil::kDurationMinSeconds; + string TimeUtil::ToString(const Timestamp& timestamp) { return FormatTime(timestamp.seconds(), timestamp.nanos()); } @@ -174,7 +181,7 @@ string TimeUtil::ToString(const Duration& duration) { seconds = -seconds; nanos = -nanos; } - result += StringPrintf("%" GOOGLE_LL_FORMAT "d", seconds); + result += SimpleItoa(seconds); if (nanos != 0) { result += "." + FormatNanos(nanos); } @@ -195,6 +195,14 @@ build_java_oracle7() { use_java oracle7 build_java oracle7 } +build_java_compatibility() { + use_java jdk7 + internal_build_cpp + # Use the unit-tests extraced from 2.5.0 to test the compatibilty between + # 3.0.0-beta-4 and the current version. + cd java/compatibility_tests/v2.5.0 + ./test.sh 3.0.0-beta-4 +} build_javanano_jdk7() { use_java jdk7 @@ -340,6 +348,7 @@ Usage: $0 { cpp | csharp | java_jdk7 | java_oracle7 | + java_compatibility | javanano_jdk7 | javanano_oracle7 | objectivec_ios | |