diff options
67 files changed, 12196 insertions, 2086 deletions
@@ -64,6 +64,8 @@ src/protoc src/unittest_proto_middleman # Generated test scaffolding +src/no_warning_test.cc +src/no-warning-test src/protobuf*-test src/test_plugin src/testzip.* @@ -108,8 +110,11 @@ conformance/conformance.pb.cc conformance/conformance.pb.h conformance/Conformance.pbobjc.h conformance/Conformance.pbobjc.m -conformance/conformance.rb +conformance/conformance_pb.rb +conformance/failing_tests.txt conformance/google/ conformance/javac_middleman conformance/lite/ +conformance/nonexistent_tests.txt conformance/protoc_middleman +conformance/succeeding_tests.txt @@ -2,6 +2,8 @@ licenses(["notice"]) +exports_files(["LICENSE"]) + ################################################################################ # Protobuf Runtime Library ################################################################################ diff --git a/Protobuf.podspec b/Protobuf.podspec index 642fc3e2..72e6dd0a 100644 --- a/Protobuf.podspec +++ b/Protobuf.podspec @@ -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 @@ -1,7 +1,7 @@ Protocol Buffers - Google's data interchange format =================================================== -[](https://travis-ci.org/google/protobuf) [](https://ci.appveyor.com/project/protobuf/protobuf) +[](https://travis-ci.org/google/protobuf) [](https://ci.appveyor.com/project/protobuf/protobuf) [](https://grpc-testing.appspot.com/job/protobuf_branch) Copyright 2008 Google Inc. diff --git a/appveyor.yml b/appveyor.yml index ce797c69..2ea3cb78 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -19,9 +19,15 @@ environment: test: off install: - - ps: Start-FileDownload https://googlemock.googlecode.com/files/gmock-1.7.0.zip - - 7z x gmock-1.7.0.zip - - rename gmock-1.7.0 gmock + - ps: Start-FileDownload https://github.com/google/googlemock/archive/release-1.7.0.zip + - 7z x release-1.7.0.zip + - del /Q release-1.7.0.zip + - rename googlemock-release-1.7.0 gmock + - ps: Start-FileDownload https://github.com/google/googletest/archive/release-1.7.0.zip + - 7z x release-1.7.0.zip + - del /Q release-1.7.0.zip + - rename googletest-release-1.7.0 gtest + - move gtest gmock - ps: Start-FileDownload https://go.microsoft.com/fwlink/?LinkID=809122 -FileName dotnetsdk.exe - dotnetsdk.exe /install /quiet /norestart @@ -31,10 +31,15 @@ fi # directory is set up as an SVN external. if test ! -e gmock; then echo "Google Mock not present. Fetching gmock-1.7.0 from the web..." - curl $curlopts -O https://googlemock.googlecode.com/files/gmock-1.7.0.zip - unzip -q gmock-1.7.0.zip - rm gmock-1.7.0.zip - mv gmock-1.7.0 gmock + curl $curlopts -L -O https://github.com/google/googlemock/archive/release-1.7.0.zip + unzip -q release-1.7.0.zip + rm release-1.7.0.zip + mv googlemock-release-1.7.0 gmock + + curl $curlopts -L -O https://github.com/google/googletest/archive/release-1.7.0.zip + unzip -q release-1.7.0.zip + rm release-1.7.0.zip + mv googletest-release-1.7.0 gmock/gtest fi set -ex diff --git a/cmake/install.cmake b/cmake/install.cmake index 94ef2198..73e31984 100644 --- a/cmake/install.cmake +++ b/cmake/install.cmake @@ -110,7 +110,7 @@ install(EXPORT protobuf-targets NAMESPACE protobuf:: COMPONENT protobuf-export) -install(DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_CMAKEDIR}/ +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_CMAKEDIR}/ DESTINATION "${CMAKE_INSTALL_CMAKEDIR}" COMPONENT protobuf-export PATTERN protobuf-targets.cmake EXCLUDE diff --git a/conformance/Makefile.am b/conformance/Makefile.am index b76407ee..28ac3c8a 100644 --- a/conformance/Makefile.am +++ b/conformance/Makefile.am @@ -20,7 +20,7 @@ other_language_protoc_outputs = \ conformance_pb2.py \ Conformance.pbobjc.h \ Conformance.pbobjc.m \ - conformance.rb \ + conformance_pb.rb \ com/google/protobuf/Any.java \ com/google/protobuf/AnyOrBuilder.java \ com/google/protobuf/AnyProto.java \ diff --git a/conformance/conformance.proto b/conformance/conformance.proto index fc96074a..95a8fd13 100644 --- a/conformance/conformance.proto +++ b/conformance/conformance.proto @@ -210,6 +210,11 @@ message TestAllTypes { NestedMessage oneof_nested_message = 112; string oneof_string = 113; bytes oneof_bytes = 114; + bool oneof_bool = 115; + uint64 oneof_uint64 = 116; + float oneof_float = 117; + double oneof_double = 118; + NestedEnum oneof_enum = 119; } // Well-known types @@ -248,6 +253,7 @@ message TestAllTypes { repeated google.protobuf.Value repeated_value = 316; // Test field-name-to-JSON-name convention. + // (protobuf says names can be any valid C/C++ identifier.) int32 fieldname1 = 401; int32 field_name2 = 402; int32 _field_name3 = 403; @@ -260,6 +266,12 @@ message TestAllTypes { int32 Field_Name10 = 410; int32 FIELD_NAME11 = 411; int32 FIELD_name12 = 412; + int32 __field_name13 = 413; + int32 __Field_name14 = 414; + int32 field__name15 = 415; + int32 field__Name16 = 416; + int32 field_name17__ = 417; + int32 Field_name18__ = 418; } message ForeignMessage { diff --git a/conformance/conformance_test.cc b/conformance/conformance_test.cc index 598ef732..fb963f68 100644 --- a/conformance/conformance_test.cc +++ b/conformance/conformance_test.cc @@ -272,11 +272,16 @@ void ConformanceTestSuite::RunValidInputTest( TestAllTypes test_message; switch (response.result_case()) { + case ConformanceResponse::RESULT_NOT_SET: + ReportFailure(test_name, request, response, + "Response didn't have any field in the Response."); + return; + case ConformanceResponse::kParseError: case ConformanceResponse::kRuntimeError: case ConformanceResponse::kSerializeError: ReportFailure(test_name, request, response, - "Failed to parse JSON input or produce JSON output."); + "Failed to parse input or produce output."); return; case ConformanceResponse::kSkipped: @@ -400,6 +405,17 @@ void ConformanceTestSuite::RunValidJsonTestWithProtobufInput( equivalent_text_format, conformance::JSON); } +void ConformanceTestSuite::RunValidProtobufTest( + const string& test_name, const TestAllTypes& input, + const string& equivalent_text_format) { + RunValidInputTest("ProtobufInput." + test_name + ".ProtobufOutput", + input.SerializeAsString(), conformance::PROTOBUF, + equivalent_text_format, conformance::PROTOBUF); + RunValidInputTest("ProtobufInput." + test_name + ".JsonOutput", + input.SerializeAsString(), conformance::PROTOBUF, + equivalent_text_format, conformance::JSON); +} + // According to proto3 JSON specification, JSON serializers follow more strict // rules than parsers (e.g., a serializer must serialize int32 values as JSON // numbers while the parser is allowed to accept them as JSON strings). This @@ -638,18 +654,22 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, RunValidJsonTest("HelloWorld", "{\"optionalString\":\"Hello, World!\"}", "optional_string: 'Hello, World!'"); + // NOTE: The spec for JSON support is still being sorted out, these may not + // all be correct. // Test field name conventions. RunValidJsonTest( "FieldNameInSnakeCase", R"({ "fieldname1": 1, "fieldName2": 2, - "FieldName3": 3 + "fieldName3": 3, + "fieldName4": 4 })", R"( fieldname1: 1 field_name2: 2 _field_name3: 3 + field__name4_: 4 )"); RunValidJsonTest( "FieldNameWithNumbers", @@ -679,6 +699,24 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, FIELD_NAME11: 11 FIELD_name12: 12 )"); + RunValidJsonTest( + "FieldNameWithDoubleUnderscores", + R"({ + "fieldName13": 13, + "fieldName14": 14, + "fieldName15": 15, + "fieldName16": 16, + "fieldName17": 17, + "fieldName18": 18 + })", + R"( + __field_name13: 13 + __Field_name14: 14 + field__name15: 15 + field__Name16: 16 + field_name17__: 17 + Field_name18__: 18 + )"); // Using the original proto field name in JSON is also allowed. RunValidJsonTest( "OriginalProtoFieldName", @@ -686,6 +724,7 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, "fieldname1": 1, "field_name2": 2, "_field_name3": 3, + "field__name4_": 4, "field0name5": 5, "field_0_name6": 6, "fieldName7": 7, @@ -693,12 +732,19 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, "field_Name9": 9, "Field_Name10": 10, "FIELD_NAME11": 11, - "FIELD_name12": 12 + "FIELD_name12": 12, + "__field_name13": 13, + "__Field_name14": 14, + "field__name15": 15, + "field__Name16": 16, + "field_name17__": 17, + "Field_name18__": 18 })", R"( fieldname1: 1 field_name2: 2 _field_name3: 3 + field__name4_: 4 field0name5: 5 field_0_name6: 6 fieldName7: 7 @@ -707,12 +753,22 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, Field_Name10: 10 FIELD_NAME11: 11 FIELD_name12: 12 + __field_name13: 13 + __Field_name14: 14 + field__name15: 15 + field__Name16: 16 + field_name17__: 17 + Field_name18__: 18 )"); // Field names can be escaped. RunValidJsonTest( "FieldNameEscaped", R"({"fieldn\u0061me1": 1})", "fieldname1: 1"); + // String ends with escape character. + ExpectParseFailureForJson( + "StringEndsWithEscapeChar", + "{\"optionalString\": \"abc\\"); // Field names must be quoted (or it's not valid JSON). ExpectParseFailureForJson( "FieldNameNotQuoted", @@ -721,6 +777,17 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, ExpectParseFailureForJson( "TrailingCommaInAnObject", R"({"fieldname1":1,})"); + ExpectParseFailureForJson( + "TrailingCommaInAnObjectWithSpace", + R"({"fieldname1":1 ,})"); + ExpectParseFailureForJson( + "TrailingCommaInAnObjectWithSpaceCommaSpace", + R"({"fieldname1":1 , })"); + ExpectParseFailureForJson( + "TrailingCommaInAnObjectWithNewlines", + R"({ + "fieldname1":1, + })"); // JSON doesn't support comments. ExpectParseFailureForJson( "JsonWithComments", @@ -728,6 +795,42 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, // This is a comment. "fieldname1": 1 })"); + // JSON spec says whitespace doesn't matter, so try a few spacings to be sure. + RunValidJsonTest( + "OneLineNoSpaces", + "{\"optionalInt32\":1,\"optionalInt64\":2}", + R"( + optional_int32: 1 + optional_int64: 2 + )"); + RunValidJsonTest( + "OneLineWithSpaces", + "{ \"optionalInt32\" : 1 , \"optionalInt64\" : 2 }", + R"( + optional_int32: 1 + optional_int64: 2 + )"); + RunValidJsonTest( + "MultilineNoSpaces", + "{\n\"optionalInt32\"\n:\n1\n,\n\"optionalInt64\"\n:\n2\n}", + R"( + optional_int32: 1 + optional_int64: 2 + )"); + RunValidJsonTest( + "MultilineWithSpaces", + "{\n \"optionalInt32\" : 1\n ,\n \"optionalInt64\" : 2\n}\n", + R"( + optional_int32: 1 + optional_int64: 2 + )"); + // Missing comma between key/value pairs. + ExpectParseFailureForJson( + "MissingCommaOneLine", + "{ \"optionalInt32\": 1 \"optionalInt64\": 2 }"); + ExpectParseFailureForJson( + "MissingCommaMultiline", + "{\n \"optionalInt32\": 1\n \"optionalInt64\": 2\n}"); // Duplicated field names are not allowed. ExpectParseFailureForJson( "FieldNameDuplicate", @@ -747,18 +850,22 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, "optionalNestedMessage": {a: 1}, "optional_nested_message": {} })"); + // NOTE: The spec for JSON support is still being sorted out, these may not + // all be correct. // Serializers should use lowerCamelCase by default. RunValidJsonTestWithValidator( "FieldNameInLowerCamelCase", R"({ "fieldname1": 1, "fieldName2": 2, - "FieldName3": 3 + "fieldName3": 3, + "fieldName4": 4 })", [](const Json::Value& value) { return value.isMember("fieldname1") && value.isMember("fieldName2") && - value.isMember("FieldName3"); + value.isMember("fieldName3") && + value.isMember("fieldName4"); }); RunValidJsonTestWithValidator( "FieldNameWithNumbers", @@ -788,6 +895,24 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, value.isMember("fIELDNAME11") && value.isMember("fIELDName12"); }); + RunValidJsonTestWithValidator( + "FieldNameWithDoubleUnderscores", + R"({ + "fieldName13": 13, + "fieldName14": 14, + "fieldName15": 15, + "fieldName16": 16, + "fieldName17": 17, + "fieldName18": 18 + })", + [](const Json::Value& value) { + return value.isMember("fieldName13") && + value.isMember("fieldName14") && + value.isMember("fieldName15") && + value.isMember("fieldName16") && + value.isMember("fieldName17") && + value.isMember("fieldName18"); + }); // Integer fields. RunValidJsonTest( @@ -1225,6 +1350,64 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, ExpectParseFailureForJson( "OneofFieldDuplicate", R"({"oneofUint32": 1, "oneofString": "test"})"); + // Ensure zero values for oneof make it out/backs. + { + TestAllTypes message; + message.set_oneof_uint32(0); + RunValidProtobufTest( + "OneofZeroUint32", message, "oneof_uint32: 0"); + message.mutable_oneof_nested_message()->set_a(0); + RunValidProtobufTest( + "OneofZeroMessage", message, "oneof_nested_message: {}"); + message.set_oneof_string(""); + RunValidProtobufTest( + "OneofZeroString", message, "oneof_string: \"\""); + message.set_oneof_bytes(""); + RunValidProtobufTest( + "OneofZeroBytes", message, "oneof_bytes: \"\""); + message.set_oneof_bool(false); + RunValidProtobufTest( + "OneofZeroBool", message, "oneof_bool: false"); + message.set_oneof_uint64(0); + RunValidProtobufTest( + "OneofZeroUint64", message, "oneof_uint64: 0"); + message.set_oneof_float(0.0f); + RunValidProtobufTest( + "OneofZeroFloat", message, "oneof_float: 0"); + message.set_oneof_double(0.0); + RunValidProtobufTest( + "OneofZeroDouble", message, "oneof_double: 0"); + message.set_oneof_enum(TestAllTypes::FOO); + RunValidProtobufTest( + "OneofZeroEnum", message, "oneof_enum: FOO"); + } + RunValidJsonTest( + "OneofZeroUint32", + R"({"oneofUint32": 0})", "oneof_uint32: 0"); + RunValidJsonTest( + "OneofZeroMessage", + R"({"oneofNestedMessage": {}})", "oneof_nested_message: {}"); + RunValidJsonTest( + "OneofZeroString", + R"({"oneofString": ""})", "oneof_string: \"\""); + RunValidJsonTest( + "OneofZeroBytes", + R"({"oneofBytes": ""})", "oneof_bytes: \"\""); + RunValidJsonTest( + "OneofZeroBool", + R"({"oneofBool": false})", "oneof_bool: false"); + RunValidJsonTest( + "OneofZeroUint64", + R"({"oneofUint64": 0})", "oneof_uint64: 0"); + RunValidJsonTest( + "OneofZeroFloat", + R"({"oneofFloat": 0.0})", "oneof_float: 0"); + RunValidJsonTest( + "OneofZeroDouble", + R"({"oneofDouble": 0.0})", "oneof_double: 0"); + RunValidJsonTest( + "OneofZeroEnum", + R"({"oneofEnum":"FOO"})", "oneof_enum: FOO"); // Repeated fields. RunValidJsonTest( @@ -1281,6 +1464,15 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, ExpectParseFailureForJson( "RepeatedFieldTrailingComma", R"({"repeatedInt32": [1, 2, 3, 4,]})"); + ExpectParseFailureForJson( + "RepeatedFieldTrailingCommaWithSpace", + "{\"repeatedInt32\": [1, 2, 3, 4 ,]}"); + ExpectParseFailureForJson( + "RepeatedFieldTrailingCommaWithSpaceCommaSpace", + "{\"repeatedInt32\": [1, 2, 3, 4 , ]}"); + ExpectParseFailureForJson( + "RepeatedFieldTrailingCommaWithNewlines", + "{\"repeatedInt32\": [\n 1,\n 2,\n 3,\n 4,\n]}"); // Map fields. RunValidJsonTest( @@ -1399,6 +1591,18 @@ bool ConformanceTestSuite::RunSuite(ConformanceTestRunner* runner, "MapFieldValueIsNull", R"({"mapInt32Int32": {"0": null}})"); + // http://www.rfc-editor.org/rfc/rfc7159.txt says strings have to use double + // quotes. + ExpectParseFailureForJson( + "StringFieldSingleQuoteKey", + R"({'optionalString': "Hello world!"})"); + ExpectParseFailureForJson( + "StringFieldSingleQuoteValue", + R"({"optionalString": 'Hello world!'})"); + ExpectParseFailureForJson( + "StringFieldSingleQuoteBoth", + R"({'optionalString': 'Hello world!'})"); + // Wrapper types. RunValidJsonTest( "OptionalBoolWrapper", diff --git a/conformance/conformance_test.h b/conformance/conformance_test.h index c9c5213c..56689318 100644 --- a/conformance/conformance_test.h +++ b/conformance/conformance_test.h @@ -133,6 +133,9 @@ class ConformanceTestSuite { void RunValidJsonTestWithProtobufInput(const string& test_name, const conformance::TestAllTypes& input, const string& equivalent_text_format); + void RunValidProtobufTest(const string& test_name, + const conformance::TestAllTypes& input, + const string& equivalent_text_format); typedef std::function<bool(const Json::Value&)> Validator; void RunValidJsonTestWithValidator(const string& test_name, diff --git a/conformance/failure_list_cpp.txt b/conformance/failure_list_cpp.txt index 839e5210..5e17176e 100644 --- a/conformance/failure_list_cpp.txt +++ b/conformance/failure_list_cpp.txt @@ -22,16 +22,22 @@ JsonInput.FieldMaskInvalidCharacter JsonInput.FieldNameDuplicate JsonInput.FieldNameDuplicateDifferentCasing1 JsonInput.FieldNameDuplicateDifferentCasing2 -JsonInput.FieldNameInLowerCamelCase.Validator -JsonInput.FieldNameInSnakeCase.JsonOutput -JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FieldNameNotQuoted JsonInput.MapFieldValueIsNull JsonInput.RepeatedFieldMessageElementIsNull JsonInput.RepeatedFieldPrimitiveElementIsNull JsonInput.RepeatedFieldTrailingComma +JsonInput.RepeatedFieldTrailingCommaWithNewlines +JsonInput.RepeatedFieldTrailingCommaWithSpace +JsonInput.RepeatedFieldTrailingCommaWithSpaceCommaSpace +JsonInput.StringFieldSingleQuoteBoth +JsonInput.StringFieldSingleQuoteKey +JsonInput.StringFieldSingleQuoteValue JsonInput.StringFieldUppercaseEscapeLetter JsonInput.TrailingCommaInAnObject +JsonInput.TrailingCommaInAnObjectWithNewlines +JsonInput.TrailingCommaInAnObjectWithSpace +JsonInput.TrailingCommaInAnObjectWithSpaceCommaSpace JsonInput.WrapperTypesWithNullValue.JsonOutput JsonInput.WrapperTypesWithNullValue.ProtobufOutput ProtobufInput.PrematureEofBeforeKnownRepeatedValue.MESSAGE diff --git a/conformance/failure_list_csharp.txt b/conformance/failure_list_csharp.txt index 1716bcbd..d8bfe1bb 100644 --- a/conformance/failure_list_csharp.txt +++ b/conformance/failure_list_csharp.txt @@ -1,6 +1,3 @@ -JsonInput.FieldNameInLowerCamelCase.Validator -JsonInput.FieldNameInSnakeCase.JsonOutput -JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FieldNameWithMixedCases.JsonOutput JsonInput.FieldNameWithMixedCases.ProtobufOutput JsonInput.FieldNameWithMixedCases.Validator diff --git a/conformance/failure_list_java.txt b/conformance/failure_list_java.txt index 850712bd..b2122c8b 100644 --- a/conformance/failure_list_java.txt +++ b/conformance/failure_list_java.txt @@ -20,8 +20,13 @@ JsonInput.DoubleFieldNegativeInfinityNotQuoted JsonInput.EnumFieldNotQuoted JsonInput.FieldMaskInvalidCharacter JsonInput.FieldNameDuplicate +JsonInput.FieldNameInLowerCamelCase.Validator JsonInput.FieldNameInSnakeCase.JsonOutput +JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FieldNameNotQuoted +JsonInput.FieldNameWithDoubleUnderscores.JsonOutput +JsonInput.FieldNameWithDoubleUnderscores.ProtobufOutput +JsonInput.FieldNameWithDoubleUnderscores.Validator JsonInput.FloatFieldInfinityNotQuoted JsonInput.FloatFieldNanNotQuoted JsonInput.FloatFieldNegativeInfinityNotQuoted @@ -35,6 +40,9 @@ JsonInput.OriginalProtoFieldName.JsonOutput JsonInput.RepeatedFieldWrongElementTypeExpectingStringsGotBool JsonInput.RepeatedFieldWrongElementTypeExpectingStringsGotInt JsonInput.StringFieldNotAString +JsonInput.StringFieldSingleQuoteBoth +JsonInput.StringFieldSingleQuoteKey +JsonInput.StringFieldSingleQuoteValue JsonInput.StringFieldSurrogateInWrongOrder JsonInput.StringFieldUnpairedHighSurrogate JsonInput.StringFieldUnpairedLowSurrogate diff --git a/conformance/failure_list_objc.txt b/conformance/failure_list_objc.txt index 5dac3501..dd538c10 100644 --- a/conformance/failure_list_objc.txt +++ b/conformance/failure_list_objc.txt @@ -1,4 +1,4 @@ -# No tests currently failing. +# All tests currently passing. # -# json input or output tests are skipped (in conformance_objc.m) as mobile -# platforms don't support json wire format to avoid code bloat. +# JSON input or output tests are skipped (in conformance_objc.m) as mobile +# platforms don't support JSON wire format to avoid code bloat. diff --git a/conformance/failure_list_python.txt b/conformance/failure_list_python.txt index 550a043f..d38b7828 100644 --- a/conformance/failure_list_python.txt +++ b/conformance/failure_list_python.txt @@ -19,9 +19,6 @@ JsonInput.EnumFieldNumericValueZero.ProtobufOutput JsonInput.EnumFieldUnknownValue.Validator JsonInput.FieldMask.ProtobufOutput JsonInput.FieldMaskInvalidCharacter -JsonInput.FieldNameInLowerCamelCase.Validator -JsonInput.FieldNameInSnakeCase.JsonOutput -JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FloatFieldInfinityNotQuoted JsonInput.FloatFieldNanNotQuoted JsonInput.FloatFieldNegativeInfinityNotQuoted @@ -35,6 +32,8 @@ JsonInput.Int32FieldMaxFloatValue.JsonOutput JsonInput.Int32FieldMaxFloatValue.ProtobufOutput JsonInput.Int32FieldMinFloatValue.JsonOutput JsonInput.Int32FieldMinFloatValue.ProtobufOutput +JsonInput.OneofZeroMessage.JsonOutput +JsonInput.OneofZeroMessage.ProtobufOutput JsonInput.OriginalProtoFieldName.JsonOutput JsonInput.OriginalProtoFieldName.ProtobufOutput JsonInput.RepeatedFieldWrongElementTypeExpectingIntegersGotBool diff --git a/conformance/failure_list_python_cpp.txt b/conformance/failure_list_python_cpp.txt index 1eb916ab..84d9fccd 100644 --- a/conformance/failure_list_python_cpp.txt +++ b/conformance/failure_list_python_cpp.txt @@ -28,9 +28,6 @@ JsonInput.EnumFieldNumericValueZero.ProtobufOutput JsonInput.EnumFieldUnknownValue.Validator JsonInput.FieldMask.ProtobufOutput JsonInput.FieldMaskInvalidCharacter -JsonInput.FieldNameInLowerCamelCase.Validator -JsonInput.FieldNameInSnakeCase.JsonOutput -JsonInput.FieldNameInSnakeCase.ProtobufOutput JsonInput.FloatFieldInfinityNotQuoted JsonInput.FloatFieldNanNotQuoted JsonInput.FloatFieldNegativeInfinityNotQuoted @@ -44,6 +41,8 @@ JsonInput.Int32FieldMaxFloatValue.JsonOutput JsonInput.Int32FieldMaxFloatValue.ProtobufOutput JsonInput.Int32FieldMinFloatValue.JsonOutput JsonInput.Int32FieldMinFloatValue.ProtobufOutput +JsonInput.OneofZeroMessage.JsonOutput +JsonInput.OneofZeroMessage.ProtobufOutput JsonInput.OriginalProtoFieldName.JsonOutput JsonInput.OriginalProtoFieldName.ProtobufOutput JsonInput.RepeatedFieldWrongElementTypeExpectingIntegersGotBool diff --git a/conformance/failure_list_ruby.txt b/conformance/failure_list_ruby.txt index 7c12da06..2a533aa5 100644 --- a/conformance/failure_list_ruby.txt +++ b/conformance/failure_list_ruby.txt @@ -58,7 +58,12 @@ JsonInput.EnumFieldNumericValueZero.ProtobufOutput JsonInput.EnumFieldUnknownValue.Validator JsonInput.FieldMask.JsonOutput JsonInput.FieldMask.ProtobufOutput +JsonInput.FieldNameInLowerCamelCase.Validator JsonInput.FieldNameInSnakeCase.JsonOutput +JsonInput.FieldNameInSnakeCase.ProtobufOutput +JsonInput.FieldNameWithDoubleUnderscores.JsonOutput +JsonInput.FieldNameWithDoubleUnderscores.ProtobufOutput +JsonInput.FieldNameWithDoubleUnderscores.Validator JsonInput.FieldNameWithMixedCases.JsonOutput JsonInput.FieldNameWithMixedCases.ProtobufOutput JsonInput.FieldNameWithMixedCases.Validator @@ -103,6 +108,14 @@ JsonInput.MessageMapField.JsonOutput JsonInput.MessageMapField.ProtobufOutput JsonInput.MessageRepeatedField.JsonOutput JsonInput.MessageRepeatedField.ProtobufOutput +JsonInput.OneofZeroDouble.JsonOutput +JsonInput.OneofZeroDouble.ProtobufOutput +JsonInput.OneofZeroFloat.JsonOutput +JsonInput.OneofZeroFloat.ProtobufOutput +JsonInput.OneofZeroUint32.JsonOutput +JsonInput.OneofZeroUint32.ProtobufOutput +JsonInput.OneofZeroUint64.JsonOutput +JsonInput.OneofZeroUint64.ProtobufOutput JsonInput.OptionalBoolWrapper.JsonOutput JsonInput.OptionalBoolWrapper.ProtobufOutput JsonInput.OptionalBytesWrapper.JsonOutput @@ -145,6 +158,7 @@ JsonInput.RepeatedUint32Wrapper.JsonOutput JsonInput.RepeatedUint32Wrapper.ProtobufOutput JsonInput.RepeatedUint64Wrapper.JsonOutput JsonInput.RepeatedUint64Wrapper.ProtobufOutput +JsonInput.StringEndsWithEscapeChar JsonInput.StringFieldNotAString JsonInput.StringFieldSurrogateInWrongOrder JsonInput.StringFieldSurrogatePair.JsonOutput diff --git a/csharp/src/Google.Protobuf.Conformance/Conformance.cs b/csharp/src/Google.Protobuf.Conformance/Conformance.cs index 5fcbff7c..431ac4fb 100644 --- a/csharp/src/Google.Protobuf.Conformance/Conformance.cs +++ b/csharp/src/Google.Protobuf.Conformance/Conformance.cs @@ -34,7 +34,7 @@ namespace Conformance { "IAEoCUgAEhkKD3NlcmlhbGl6ZV9lcnJvchgGIAEoCUgAEhcKDXJ1bnRpbWVf", "ZXJyb3IYAiABKAlIABIaChBwcm90b2J1Zl9wYXlsb2FkGAMgASgMSAASFgoM", "anNvbl9wYXlsb2FkGAQgASgJSAASEQoHc2tpcHBlZBgFIAEoCUgAQggKBnJl", - "c3VsdCLVMgoMVGVzdEFsbFR5cGVzEhYKDm9wdGlvbmFsX2ludDMyGAEgASgF", + "c3VsdCKCNQoMVGVzdEFsbFR5cGVzEhYKDm9wdGlvbmFsX2ludDMyGAEgASgF", "EhYKDm9wdGlvbmFsX2ludDY0GAIgASgDEhcKD29wdGlvbmFsX3VpbnQzMhgD", "IAEoDRIXCg9vcHRpb25hbF91aW50NjQYBCABKAQSFwoPb3B0aW9uYWxfc2lu", "dDMyGAUgASgREhcKD29wdGlvbmFsX3NpbnQ2NBgGIAEoEhIYChBvcHRpb25h", @@ -102,93 +102,100 @@ namespace Conformance { "TWFwU3RyaW5nRm9yZWlnbkVudW1FbnRyeRIWCgxvbmVvZl91aW50MzIYbyAB", "KA1IABJHChRvbmVvZl9uZXN0ZWRfbWVzc2FnZRhwIAEoCzInLmNvbmZvcm1h", "bmNlLlRlc3RBbGxUeXBlcy5OZXN0ZWRNZXNzYWdlSAASFgoMb25lb2Zfc3Ry", - "aW5nGHEgASgJSAASFQoLb25lb2ZfYnl0ZXMYciABKAxIABI6ChVvcHRpb25h", - "bF9ib29sX3dyYXBwZXIYyQEgASgLMhouZ29vZ2xlLnByb3RvYnVmLkJvb2xW", - "YWx1ZRI8ChZvcHRpb25hbF9pbnQzMl93cmFwcGVyGMoBIAEoCzIbLmdvb2ds", - "ZS5wcm90b2J1Zi5JbnQzMlZhbHVlEjwKFm9wdGlvbmFsX2ludDY0X3dyYXBw", - "ZXIYywEgASgLMhsuZ29vZ2xlLnByb3RvYnVmLkludDY0VmFsdWUSPgoXb3B0", - "aW9uYWxfdWludDMyX3dyYXBwZXIYzAEgASgLMhwuZ29vZ2xlLnByb3RvYnVm", - "LlVJbnQzMlZhbHVlEj4KF29wdGlvbmFsX3VpbnQ2NF93cmFwcGVyGM0BIAEo", - "CzIcLmdvb2dsZS5wcm90b2J1Zi5VSW50NjRWYWx1ZRI8ChZvcHRpb25hbF9m", - "bG9hdF93cmFwcGVyGM4BIAEoCzIbLmdvb2dsZS5wcm90b2J1Zi5GbG9hdFZh", - "bHVlEj4KF29wdGlvbmFsX2RvdWJsZV93cmFwcGVyGM8BIAEoCzIcLmdvb2ds", - "ZS5wcm90b2J1Zi5Eb3VibGVWYWx1ZRI+ChdvcHRpb25hbF9zdHJpbmdfd3Jh", - "cHBlchjQASABKAsyHC5nb29nbGUucHJvdG9idWYuU3RyaW5nVmFsdWUSPAoW", - "b3B0aW9uYWxfYnl0ZXNfd3JhcHBlchjRASABKAsyGy5nb29nbGUucHJvdG9i", - "dWYuQnl0ZXNWYWx1ZRI6ChVyZXBlYXRlZF9ib29sX3dyYXBwZXIY0wEgAygL", - "MhouZ29vZ2xlLnByb3RvYnVmLkJvb2xWYWx1ZRI8ChZyZXBlYXRlZF9pbnQz", - "Ml93cmFwcGVyGNQBIAMoCzIbLmdvb2dsZS5wcm90b2J1Zi5JbnQzMlZhbHVl", - "EjwKFnJlcGVhdGVkX2ludDY0X3dyYXBwZXIY1QEgAygLMhsuZ29vZ2xlLnBy", - "b3RvYnVmLkludDY0VmFsdWUSPgoXcmVwZWF0ZWRfdWludDMyX3dyYXBwZXIY", - "1gEgAygLMhwuZ29vZ2xlLnByb3RvYnVmLlVJbnQzMlZhbHVlEj4KF3JlcGVh", - "dGVkX3VpbnQ2NF93cmFwcGVyGNcBIAMoCzIcLmdvb2dsZS5wcm90b2J1Zi5V", - "SW50NjRWYWx1ZRI8ChZyZXBlYXRlZF9mbG9hdF93cmFwcGVyGNgBIAMoCzIb", - "Lmdvb2dsZS5wcm90b2J1Zi5GbG9hdFZhbHVlEj4KF3JlcGVhdGVkX2RvdWJs", - "ZV93cmFwcGVyGNkBIAMoCzIcLmdvb2dsZS5wcm90b2J1Zi5Eb3VibGVWYWx1", - "ZRI+ChdyZXBlYXRlZF9zdHJpbmdfd3JhcHBlchjaASADKAsyHC5nb29nbGUu", - "cHJvdG9idWYuU3RyaW5nVmFsdWUSPAoWcmVwZWF0ZWRfYnl0ZXNfd3JhcHBl", - "chjbASADKAsyGy5nb29nbGUucHJvdG9idWYuQnl0ZXNWYWx1ZRI1ChFvcHRp", - "b25hbF9kdXJhdGlvbhitAiABKAsyGS5nb29nbGUucHJvdG9idWYuRHVyYXRp", - "b24SNwoSb3B0aW9uYWxfdGltZXN0YW1wGK4CIAEoCzIaLmdvb2dsZS5wcm90", - "b2J1Zi5UaW1lc3RhbXASOAoTb3B0aW9uYWxfZmllbGRfbWFzaxivAiABKAsy", - "Gi5nb29nbGUucHJvdG9idWYuRmllbGRNYXNrEjEKD29wdGlvbmFsX3N0cnVj", - "dBiwAiABKAsyFy5nb29nbGUucHJvdG9idWYuU3RydWN0EisKDG9wdGlvbmFs", - "X2FueRixAiABKAsyFC5nb29nbGUucHJvdG9idWYuQW55Ei8KDm9wdGlvbmFs", - "X3ZhbHVlGLICIAEoCzIWLmdvb2dsZS5wcm90b2J1Zi5WYWx1ZRI1ChFyZXBl", - "YXRlZF9kdXJhdGlvbhi3AiADKAsyGS5nb29nbGUucHJvdG9idWYuRHVyYXRp", - "b24SNwoScmVwZWF0ZWRfdGltZXN0YW1wGLgCIAMoCzIaLmdvb2dsZS5wcm90", - "b2J1Zi5UaW1lc3RhbXASNwoScmVwZWF0ZWRfZmllbGRtYXNrGLkCIAMoCzIa", - "Lmdvb2dsZS5wcm90b2J1Zi5GaWVsZE1hc2sSMQoPcmVwZWF0ZWRfc3RydWN0", - "GMQCIAMoCzIXLmdvb2dsZS5wcm90b2J1Zi5TdHJ1Y3QSKwoMcmVwZWF0ZWRf", - "YW55GLsCIAMoCzIULmdvb2dsZS5wcm90b2J1Zi5BbnkSLwoOcmVwZWF0ZWRf", - "dmFsdWUYvAIgAygLMhYuZ29vZ2xlLnByb3RvYnVmLlZhbHVlEhMKCmZpZWxk", - "bmFtZTEYkQMgASgFEhQKC2ZpZWxkX25hbWUyGJIDIAEoBRIVCgxfZmllbGRf", - "bmFtZTMYkwMgASgFEhYKDWZpZWxkX19uYW1lNF8YlAMgASgFEhQKC2ZpZWxk", - "MG5hbWU1GJUDIAEoBRIWCg1maWVsZF8wX25hbWU2GJYDIAEoBRITCgpmaWVs", - "ZE5hbWU3GJcDIAEoBRITCgpGaWVsZE5hbWU4GJgDIAEoBRIUCgtmaWVsZF9O", - "YW1lORiZAyABKAUSFQoMRmllbGRfTmFtZTEwGJoDIAEoBRIVCgxGSUVMRF9O", - "QU1FMTEYmwMgASgFEhUKDEZJRUxEX25hbWUxMhicAyABKAUaSgoNTmVzdGVk", - "TWVzc2FnZRIJCgFhGAEgASgFEi4KC2NvcmVjdXJzaXZlGAIgASgLMhkuY29u", - "Zm9ybWFuY2UuVGVzdEFsbFR5cGVzGjQKEk1hcEludDMySW50MzJFbnRyeRIL", - "CgNrZXkYASABKAUSDQoFdmFsdWUYAiABKAU6AjgBGjQKEk1hcEludDY0SW50", - "NjRFbnRyeRILCgNrZXkYASABKAMSDQoFdmFsdWUYAiABKAM6AjgBGjYKFE1h", - "cFVpbnQzMlVpbnQzMkVudHJ5EgsKA2tleRgBIAEoDRINCgV2YWx1ZRgCIAEo", - "DToCOAEaNgoUTWFwVWludDY0VWludDY0RW50cnkSCwoDa2V5GAEgASgEEg0K", - "BXZhbHVlGAIgASgEOgI4ARo2ChRNYXBTaW50MzJTaW50MzJFbnRyeRILCgNr", - "ZXkYASABKBESDQoFdmFsdWUYAiABKBE6AjgBGjYKFE1hcFNpbnQ2NFNpbnQ2", - "NEVudHJ5EgsKA2tleRgBIAEoEhINCgV2YWx1ZRgCIAEoEjoCOAEaOAoWTWFw", - "Rml4ZWQzMkZpeGVkMzJFbnRyeRILCgNrZXkYASABKAcSDQoFdmFsdWUYAiAB", - "KAc6AjgBGjgKFk1hcEZpeGVkNjRGaXhlZDY0RW50cnkSCwoDa2V5GAEgASgG", - "Eg0KBXZhbHVlGAIgASgGOgI4ARo6ChhNYXBTZml4ZWQzMlNmaXhlZDMyRW50", - "cnkSCwoDa2V5GAEgASgPEg0KBXZhbHVlGAIgASgPOgI4ARo6ChhNYXBTZml4", - "ZWQ2NFNmaXhlZDY0RW50cnkSCwoDa2V5GAEgASgQEg0KBXZhbHVlGAIgASgQ", - "OgI4ARo0ChJNYXBJbnQzMkZsb2F0RW50cnkSCwoDa2V5GAEgASgFEg0KBXZh", - "bHVlGAIgASgCOgI4ARo1ChNNYXBJbnQzMkRvdWJsZUVudHJ5EgsKA2tleRgB", - "IAEoBRINCgV2YWx1ZRgCIAEoAToCOAEaMgoQTWFwQm9vbEJvb2xFbnRyeRIL", - "CgNrZXkYASABKAgSDQoFdmFsdWUYAiABKAg6AjgBGjYKFE1hcFN0cmluZ1N0", - "cmluZ0VudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAEaNQoT", - "TWFwU3RyaW5nQnl0ZXNFbnRyeRILCgNrZXkYASABKAkSDQoFdmFsdWUYAiAB", - "KAw6AjgBGmYKG01hcFN0cmluZ05lc3RlZE1lc3NhZ2VFbnRyeRILCgNrZXkY", - "ASABKAkSNgoFdmFsdWUYAiABKAsyJy5jb25mb3JtYW5jZS5UZXN0QWxsVHlw", - "ZXMuTmVzdGVkTWVzc2FnZToCOAEaWwocTWFwU3RyaW5nRm9yZWlnbk1lc3Nh", - "Z2VFbnRyeRILCgNrZXkYASABKAkSKgoFdmFsdWUYAiABKAsyGy5jb25mb3Jt", - "YW5jZS5Gb3JlaWduTWVzc2FnZToCOAEaYAoYTWFwU3RyaW5nTmVzdGVkRW51", - "bUVudHJ5EgsKA2tleRgBIAEoCRIzCgV2YWx1ZRgCIAEoDjIkLmNvbmZvcm1h", - "bmNlLlRlc3RBbGxUeXBlcy5OZXN0ZWRFbnVtOgI4ARpVChlNYXBTdHJpbmdG", - "b3JlaWduRW51bUVudHJ5EgsKA2tleRgBIAEoCRInCgV2YWx1ZRgCIAEoDjIY", - "LmNvbmZvcm1hbmNlLkZvcmVpZ25FbnVtOgI4ASI5CgpOZXN0ZWRFbnVtEgcK", - "A0ZPTxAAEgcKA0JBUhABEgcKA0JBWhACEhAKA05FRxD///////////8BQg0K", - "C29uZW9mX2ZpZWxkIhsKDkZvcmVpZ25NZXNzYWdlEgkKAWMYASABKAUqNQoK", - "V2lyZUZvcm1hdBIPCgtVTlNQRUNJRklFRBAAEgwKCFBST1RPQlVGEAESCAoE", - "SlNPThACKkAKC0ZvcmVpZ25FbnVtEg8KC0ZPUkVJR05fRk9PEAASDwoLRk9S", - "RUlHTl9CQVIQARIPCgtGT1JFSUdOX0JBWhACQiEKH2NvbS5nb29nbGUucHJv", - "dG9idWYuY29uZm9ybWFuY2ViBnByb3RvMw==")); + "aW5nGHEgASgJSAASFQoLb25lb2ZfYnl0ZXMYciABKAxIABIUCgpvbmVvZl9i", + "b29sGHMgASgISAASFgoMb25lb2ZfdWludDY0GHQgASgESAASFQoLb25lb2Zf", + "ZmxvYXQYdSABKAJIABIWCgxvbmVvZl9kb3VibGUYdiABKAFIABI6CgpvbmVv", + "Zl9lbnVtGHcgASgOMiQuY29uZm9ybWFuY2UuVGVzdEFsbFR5cGVzLk5lc3Rl", + "ZEVudW1IABI6ChVvcHRpb25hbF9ib29sX3dyYXBwZXIYyQEgASgLMhouZ29v", + "Z2xlLnByb3RvYnVmLkJvb2xWYWx1ZRI8ChZvcHRpb25hbF9pbnQzMl93cmFw", + "cGVyGMoBIAEoCzIbLmdvb2dsZS5wcm90b2J1Zi5JbnQzMlZhbHVlEjwKFm9w", + "dGlvbmFsX2ludDY0X3dyYXBwZXIYywEgASgLMhsuZ29vZ2xlLnByb3RvYnVm", + "LkludDY0VmFsdWUSPgoXb3B0aW9uYWxfdWludDMyX3dyYXBwZXIYzAEgASgL", + "MhwuZ29vZ2xlLnByb3RvYnVmLlVJbnQzMlZhbHVlEj4KF29wdGlvbmFsX3Vp", + "bnQ2NF93cmFwcGVyGM0BIAEoCzIcLmdvb2dsZS5wcm90b2J1Zi5VSW50NjRW", + "YWx1ZRI8ChZvcHRpb25hbF9mbG9hdF93cmFwcGVyGM4BIAEoCzIbLmdvb2ds", + "ZS5wcm90b2J1Zi5GbG9hdFZhbHVlEj4KF29wdGlvbmFsX2RvdWJsZV93cmFw", + "cGVyGM8BIAEoCzIcLmdvb2dsZS5wcm90b2J1Zi5Eb3VibGVWYWx1ZRI+Chdv", + "cHRpb25hbF9zdHJpbmdfd3JhcHBlchjQASABKAsyHC5nb29nbGUucHJvdG9i", + "dWYuU3RyaW5nVmFsdWUSPAoWb3B0aW9uYWxfYnl0ZXNfd3JhcHBlchjRASAB", + "KAsyGy5nb29nbGUucHJvdG9idWYuQnl0ZXNWYWx1ZRI6ChVyZXBlYXRlZF9i", + "b29sX3dyYXBwZXIY0wEgAygLMhouZ29vZ2xlLnByb3RvYnVmLkJvb2xWYWx1", + "ZRI8ChZyZXBlYXRlZF9pbnQzMl93cmFwcGVyGNQBIAMoCzIbLmdvb2dsZS5w", + "cm90b2J1Zi5JbnQzMlZhbHVlEjwKFnJlcGVhdGVkX2ludDY0X3dyYXBwZXIY", + "1QEgAygLMhsuZ29vZ2xlLnByb3RvYnVmLkludDY0VmFsdWUSPgoXcmVwZWF0", + "ZWRfdWludDMyX3dyYXBwZXIY1gEgAygLMhwuZ29vZ2xlLnByb3RvYnVmLlVJ", + "bnQzMlZhbHVlEj4KF3JlcGVhdGVkX3VpbnQ2NF93cmFwcGVyGNcBIAMoCzIc", + "Lmdvb2dsZS5wcm90b2J1Zi5VSW50NjRWYWx1ZRI8ChZyZXBlYXRlZF9mbG9h", + "dF93cmFwcGVyGNgBIAMoCzIbLmdvb2dsZS5wcm90b2J1Zi5GbG9hdFZhbHVl", + "Ej4KF3JlcGVhdGVkX2RvdWJsZV93cmFwcGVyGNkBIAMoCzIcLmdvb2dsZS5w", + "cm90b2J1Zi5Eb3VibGVWYWx1ZRI+ChdyZXBlYXRlZF9zdHJpbmdfd3JhcHBl", + "chjaASADKAsyHC5nb29nbGUucHJvdG9idWYuU3RyaW5nVmFsdWUSPAoWcmVw", + "ZWF0ZWRfYnl0ZXNfd3JhcHBlchjbASADKAsyGy5nb29nbGUucHJvdG9idWYu", + "Qnl0ZXNWYWx1ZRI1ChFvcHRpb25hbF9kdXJhdGlvbhitAiABKAsyGS5nb29n", + "bGUucHJvdG9idWYuRHVyYXRpb24SNwoSb3B0aW9uYWxfdGltZXN0YW1wGK4C", + "IAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASOAoTb3B0aW9uYWxf", + "ZmllbGRfbWFzaxivAiABKAsyGi5nb29nbGUucHJvdG9idWYuRmllbGRNYXNr", + "EjEKD29wdGlvbmFsX3N0cnVjdBiwAiABKAsyFy5nb29nbGUucHJvdG9idWYu", + "U3RydWN0EisKDG9wdGlvbmFsX2FueRixAiABKAsyFC5nb29nbGUucHJvdG9i", + "dWYuQW55Ei8KDm9wdGlvbmFsX3ZhbHVlGLICIAEoCzIWLmdvb2dsZS5wcm90", + "b2J1Zi5WYWx1ZRI1ChFyZXBlYXRlZF9kdXJhdGlvbhi3AiADKAsyGS5nb29n", + "bGUucHJvdG9idWYuRHVyYXRpb24SNwoScmVwZWF0ZWRfdGltZXN0YW1wGLgC", + "IAMoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASNwoScmVwZWF0ZWRf", + "ZmllbGRtYXNrGLkCIAMoCzIaLmdvb2dsZS5wcm90b2J1Zi5GaWVsZE1hc2sS", + "MQoPcmVwZWF0ZWRfc3RydWN0GMQCIAMoCzIXLmdvb2dsZS5wcm90b2J1Zi5T", + "dHJ1Y3QSKwoMcmVwZWF0ZWRfYW55GLsCIAMoCzIULmdvb2dsZS5wcm90b2J1", + "Zi5BbnkSLwoOcmVwZWF0ZWRfdmFsdWUYvAIgAygLMhYuZ29vZ2xlLnByb3Rv", + "YnVmLlZhbHVlEhMKCmZpZWxkbmFtZTEYkQMgASgFEhQKC2ZpZWxkX25hbWUy", + "GJIDIAEoBRIVCgxfZmllbGRfbmFtZTMYkwMgASgFEhYKDWZpZWxkX19uYW1l", + "NF8YlAMgASgFEhQKC2ZpZWxkMG5hbWU1GJUDIAEoBRIWCg1maWVsZF8wX25h", + "bWU2GJYDIAEoBRITCgpmaWVsZE5hbWU3GJcDIAEoBRITCgpGaWVsZE5hbWU4", + "GJgDIAEoBRIUCgtmaWVsZF9OYW1lORiZAyABKAUSFQoMRmllbGRfTmFtZTEw", + "GJoDIAEoBRIVCgxGSUVMRF9OQU1FMTEYmwMgASgFEhUKDEZJRUxEX25hbWUx", + "MhicAyABKAUSFwoOX19maWVsZF9uYW1lMTMYnQMgASgFEhcKDl9fRmllbGRf", + "bmFtZTE0GJ4DIAEoBRIWCg1maWVsZF9fbmFtZTE1GJ8DIAEoBRIWCg1maWVs", + "ZF9fTmFtZTE2GKADIAEoBRIXCg5maWVsZF9uYW1lMTdfXxihAyABKAUSFwoO", + "RmllbGRfbmFtZTE4X18YogMgASgFGkoKDU5lc3RlZE1lc3NhZ2USCQoBYRgB", + "IAEoBRIuCgtjb3JlY3Vyc2l2ZRgCIAEoCzIZLmNvbmZvcm1hbmNlLlRlc3RB", + "bGxUeXBlcxo0ChJNYXBJbnQzMkludDMyRW50cnkSCwoDa2V5GAEgASgFEg0K", + "BXZhbHVlGAIgASgFOgI4ARo0ChJNYXBJbnQ2NEludDY0RW50cnkSCwoDa2V5", + "GAEgASgDEg0KBXZhbHVlGAIgASgDOgI4ARo2ChRNYXBVaW50MzJVaW50MzJF", + "bnRyeRILCgNrZXkYASABKA0SDQoFdmFsdWUYAiABKA06AjgBGjYKFE1hcFVp", + "bnQ2NFVpbnQ2NEVudHJ5EgsKA2tleRgBIAEoBBINCgV2YWx1ZRgCIAEoBDoC", + "OAEaNgoUTWFwU2ludDMyU2ludDMyRW50cnkSCwoDa2V5GAEgASgREg0KBXZh", + "bHVlGAIgASgROgI4ARo2ChRNYXBTaW50NjRTaW50NjRFbnRyeRILCgNrZXkY", + "ASABKBISDQoFdmFsdWUYAiABKBI6AjgBGjgKFk1hcEZpeGVkMzJGaXhlZDMy", + "RW50cnkSCwoDa2V5GAEgASgHEg0KBXZhbHVlGAIgASgHOgI4ARo4ChZNYXBG", + "aXhlZDY0Rml4ZWQ2NEVudHJ5EgsKA2tleRgBIAEoBhINCgV2YWx1ZRgCIAEo", + "BjoCOAEaOgoYTWFwU2ZpeGVkMzJTZml4ZWQzMkVudHJ5EgsKA2tleRgBIAEo", + "DxINCgV2YWx1ZRgCIAEoDzoCOAEaOgoYTWFwU2ZpeGVkNjRTZml4ZWQ2NEVu", + "dHJ5EgsKA2tleRgBIAEoEBINCgV2YWx1ZRgCIAEoEDoCOAEaNAoSTWFwSW50", + "MzJGbG9hdEVudHJ5EgsKA2tleRgBIAEoBRINCgV2YWx1ZRgCIAEoAjoCOAEa", + "NQoTTWFwSW50MzJEb3VibGVFbnRyeRILCgNrZXkYASABKAUSDQoFdmFsdWUY", + "AiABKAE6AjgBGjIKEE1hcEJvb2xCb29sRW50cnkSCwoDa2V5GAEgASgIEg0K", + "BXZhbHVlGAIgASgIOgI4ARo2ChRNYXBTdHJpbmdTdHJpbmdFbnRyeRILCgNr", + "ZXkYASABKAkSDQoFdmFsdWUYAiABKAk6AjgBGjUKE01hcFN0cmluZ0J5dGVz", + "RW50cnkSCwoDa2V5GAEgASgJEg0KBXZhbHVlGAIgASgMOgI4ARpmChtNYXBT", + "dHJpbmdOZXN0ZWRNZXNzYWdlRW50cnkSCwoDa2V5GAEgASgJEjYKBXZhbHVl", + "GAIgASgLMicuY29uZm9ybWFuY2UuVGVzdEFsbFR5cGVzLk5lc3RlZE1lc3Nh", + "Z2U6AjgBGlsKHE1hcFN0cmluZ0ZvcmVpZ25NZXNzYWdlRW50cnkSCwoDa2V5", + "GAEgASgJEioKBXZhbHVlGAIgASgLMhsuY29uZm9ybWFuY2UuRm9yZWlnbk1l", + "c3NhZ2U6AjgBGmAKGE1hcFN0cmluZ05lc3RlZEVudW1FbnRyeRILCgNrZXkY", + "ASABKAkSMwoFdmFsdWUYAiABKA4yJC5jb25mb3JtYW5jZS5UZXN0QWxsVHlw", + "ZXMuTmVzdGVkRW51bToCOAEaVQoZTWFwU3RyaW5nRm9yZWlnbkVudW1FbnRy", + "eRILCgNrZXkYASABKAkSJwoFdmFsdWUYAiABKA4yGC5jb25mb3JtYW5jZS5G", + "b3JlaWduRW51bToCOAEiOQoKTmVzdGVkRW51bRIHCgNGT08QABIHCgNCQVIQ", + "ARIHCgNCQVoQAhIQCgNORUcQ////////////AUINCgtvbmVvZl9maWVsZCIb", + "Cg5Gb3JlaWduTWVzc2FnZRIJCgFjGAEgASgFKjUKCldpcmVGb3JtYXQSDwoL", + "VU5TUEVDSUZJRUQQABIMCghQUk9UT0JVRhABEggKBEpTT04QAipACgtGb3Jl", + "aWduRW51bRIPCgtGT1JFSUdOX0ZPTxAAEg8KC0ZPUkVJR05fQkFSEAESDwoL", + "Rk9SRUlHTl9CQVoQAkIhCh9jb20uZ29vZ2xlLnByb3RvYnVmLmNvbmZvcm1h", + "bmNlYgZwcm90bzM=")); descriptor = pbr::FileDescriptor.FromGeneratedCode(descriptorData, new pbr::FileDescriptor[] { global::Google.Protobuf.WellKnownTypes.AnyReflection.Descriptor, global::Google.Protobuf.WellKnownTypes.DurationReflection.Descriptor, global::Google.Protobuf.WellKnownTypes.FieldMaskReflection.Descriptor, global::Google.Protobuf.WellKnownTypes.StructReflection.Descriptor, global::Google.Protobuf.WellKnownTypes.TimestampReflection.Descriptor, global::Google.Protobuf.WellKnownTypes.WrappersReflection.Descriptor, }, new pbr::GeneratedClrTypeInfo(new[] {typeof(global::Conformance.WireFormat), typeof(global::Conformance.ForeignEnum), }, new pbr::GeneratedClrTypeInfo[] { new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.ConformanceRequest), global::Conformance.ConformanceRequest.Parser, new[]{ "ProtobufPayload", "JsonPayload", "RequestedOutputFormat" }, new[]{ "Payload" }, null, null), new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.ConformanceResponse), global::Conformance.ConformanceResponse.Parser, new[]{ "ParseError", "SerializeError", "RuntimeError", "ProtobufPayload", "JsonPayload", "Skipped" }, new[]{ "Result" }, null, null), - new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.TestAllTypes), global::Conformance.TestAllTypes.Parser, new[]{ "OptionalInt32", "OptionalInt64", "OptionalUint32", "OptionalUint64", "OptionalSint32", "OptionalSint64", "OptionalFixed32", "OptionalFixed64", "OptionalSfixed32", "OptionalSfixed64", "OptionalFloat", "OptionalDouble", "OptionalBool", "OptionalString", "OptionalBytes", "OptionalNestedMessage", "OptionalForeignMessage", "OptionalNestedEnum", "OptionalForeignEnum", "OptionalStringPiece", "OptionalCord", "RecursiveMessage", "RepeatedInt32", "RepeatedInt64", "RepeatedUint32", "RepeatedUint64", "RepeatedSint32", "RepeatedSint64", "RepeatedFixed32", "RepeatedFixed64", "RepeatedSfixed32", "RepeatedSfixed64", "RepeatedFloat", "RepeatedDouble", "RepeatedBool", "RepeatedString", "RepeatedBytes", "RepeatedNestedMessage", "RepeatedForeignMessage", "RepeatedNestedEnum", "RepeatedForeignEnum", "RepeatedStringPiece", "RepeatedCord", "MapInt32Int32", "MapInt64Int64", "MapUint32Uint32", "MapUint64Uint64", "MapSint32Sint32", "MapSint64Sint64", "MapFixed32Fixed32", "MapFixed64Fixed64", "MapSfixed32Sfixed32", "MapSfixed64Sfixed64", "MapInt32Float", "MapInt32Double", "MapBoolBool", "MapStringString", "MapStringBytes", "MapStringNestedMessage", "MapStringForeignMessage", "MapStringNestedEnum", "MapStringForeignEnum", "OneofUint32", "OneofNestedMessage", "OneofString", "OneofBytes", "OptionalBoolWrapper", "OptionalInt32Wrapper", "OptionalInt64Wrapper", "OptionalUint32Wrapper", "OptionalUint64Wrapper", "OptionalFloatWrapper", "OptionalDoubleWrapper", "OptionalStringWrapper", "OptionalBytesWrapper", "RepeatedBoolWrapper", "RepeatedInt32Wrapper", "RepeatedInt64Wrapper", "RepeatedUint32Wrapper", "RepeatedUint64Wrapper", "RepeatedFloatWrapper", "RepeatedDoubleWrapper", "RepeatedStringWrapper", "RepeatedBytesWrapper", "OptionalDuration", "OptionalTimestamp", "OptionalFieldMask", "OptionalStruct", "OptionalAny", "OptionalValue", "RepeatedDuration", "RepeatedTimestamp", "RepeatedFieldmask", "RepeatedStruct", "RepeatedAny", "RepeatedValue", "Fieldname1", "FieldName2", "FieldName3", "FieldName4", "Field0Name5", "Field0Name6", "FieldName7", "FieldName8", "FieldName9", "FieldName10", "FIELDNAME11", "FIELDName12" }, new[]{ "OneofField" }, new[]{ typeof(global::Conformance.TestAllTypes.Types.NestedEnum) }, new pbr::GeneratedClrTypeInfo[] { new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.TestAllTypes.Types.NestedMessage), global::Conformance.TestAllTypes.Types.NestedMessage.Parser, new[]{ "A", "Corecursive" }, null, null, null), + new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.TestAllTypes), global::Conformance.TestAllTypes.Parser, new[]{ "OptionalInt32", "OptionalInt64", "OptionalUint32", "OptionalUint64", "OptionalSint32", "OptionalSint64", "OptionalFixed32", "OptionalFixed64", "OptionalSfixed32", "OptionalSfixed64", "OptionalFloat", "OptionalDouble", "OptionalBool", "OptionalString", "OptionalBytes", "OptionalNestedMessage", "OptionalForeignMessage", "OptionalNestedEnum", "OptionalForeignEnum", "OptionalStringPiece", "OptionalCord", "RecursiveMessage", "RepeatedInt32", "RepeatedInt64", "RepeatedUint32", "RepeatedUint64", "RepeatedSint32", "RepeatedSint64", "RepeatedFixed32", "RepeatedFixed64", "RepeatedSfixed32", "RepeatedSfixed64", "RepeatedFloat", "RepeatedDouble", "RepeatedBool", "RepeatedString", "RepeatedBytes", "RepeatedNestedMessage", "RepeatedForeignMessage", "RepeatedNestedEnum", "RepeatedForeignEnum", "RepeatedStringPiece", "RepeatedCord", "MapInt32Int32", "MapInt64Int64", "MapUint32Uint32", "MapUint64Uint64", "MapSint32Sint32", "MapSint64Sint64", "MapFixed32Fixed32", "MapFixed64Fixed64", "MapSfixed32Sfixed32", "MapSfixed64Sfixed64", "MapInt32Float", "MapInt32Double", "MapBoolBool", "MapStringString", "MapStringBytes", "MapStringNestedMessage", "MapStringForeignMessage", "MapStringNestedEnum", "MapStringForeignEnum", "OneofUint32", "OneofNestedMessage", "OneofString", "OneofBytes", "OneofBool", "OneofUint64", "OneofFloat", "OneofDouble", "OneofEnum", "OptionalBoolWrapper", "OptionalInt32Wrapper", "OptionalInt64Wrapper", "OptionalUint32Wrapper", "OptionalUint64Wrapper", "OptionalFloatWrapper", "OptionalDoubleWrapper", "OptionalStringWrapper", "OptionalBytesWrapper", "RepeatedBoolWrapper", "RepeatedInt32Wrapper", "RepeatedInt64Wrapper", "RepeatedUint32Wrapper", "RepeatedUint64Wrapper", "RepeatedFloatWrapper", "RepeatedDoubleWrapper", "RepeatedStringWrapper", "RepeatedBytesWrapper", "OptionalDuration", "OptionalTimestamp", "OptionalFieldMask", "OptionalStruct", "OptionalAny", "OptionalValue", "RepeatedDuration", "RepeatedTimestamp", "RepeatedFieldmask", "RepeatedStruct", "RepeatedAny", "RepeatedValue", "Fieldname1", "FieldName2", "FieldName3", "FieldName4", "Field0Name5", "Field0Name6", "FieldName7", "FieldName8", "FieldName9", "FieldName10", "FIELDNAME11", "FIELDName12", "FieldName13", "FieldName14", "FieldName15", "FieldName16", "FieldName17", "FieldName18" }, new[]{ "OneofField" }, new[]{ typeof(global::Conformance.TestAllTypes.Types.NestedEnum) }, new pbr::GeneratedClrTypeInfo[] { new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.TestAllTypes.Types.NestedMessage), global::Conformance.TestAllTypes.Types.NestedMessage.Parser, new[]{ "A", "Corecursive" }, null, null, null), null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, }), new pbr::GeneratedClrTypeInfo(typeof(global::Conformance.ForeignMessage), global::Conformance.ForeignMessage.Parser, new[]{ "C" }, null, null, null) })); @@ -890,6 +897,12 @@ namespace Conformance { fieldName10_ = other.fieldName10_; fIELDNAME11_ = other.fIELDNAME11_; fIELDName12_ = other.fIELDName12_; + FieldName13_ = other.FieldName13_; + FieldName14_ = other.FieldName14_; + fieldName15_ = other.fieldName15_; + fieldName16_ = other.fieldName16_; + fieldName17_ = other.fieldName17_; + fieldName18_ = other.fieldName18_; switch (other.OneofFieldCase) { case OneofFieldOneofCase.OneofUint32: OneofUint32 = other.OneofUint32; @@ -903,6 +916,21 @@ namespace Conformance { case OneofFieldOneofCase.OneofBytes: OneofBytes = other.OneofBytes; break; + case OneofFieldOneofCase.OneofBool: + OneofBool = other.OneofBool; + break; + case OneofFieldOneofCase.OneofUint64: + OneofUint64 = other.OneofUint64; + break; + case OneofFieldOneofCase.OneofFloat: + OneofFloat = other.OneofFloat; + break; + case OneofFieldOneofCase.OneofDouble: + OneofDouble = other.OneofDouble; + break; + case OneofFieldOneofCase.OneofEnum: + OneofEnum = other.OneofEnum; + break; } } @@ -1607,6 +1635,61 @@ namespace Conformance { } } + /// <summary>Field number for the "oneof_bool" field.</summary> + public const int OneofBoolFieldNumber = 115; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public bool OneofBool { + get { return oneofFieldCase_ == OneofFieldOneofCase.OneofBool ? (bool) oneofField_ : false; } + set { + oneofField_ = value; + oneofFieldCase_ = OneofFieldOneofCase.OneofBool; + } + } + + /// <summary>Field number for the "oneof_uint64" field.</summary> + public const int OneofUint64FieldNumber = 116; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public ulong OneofUint64 { + get { return oneofFieldCase_ == OneofFieldOneofCase.OneofUint64 ? (ulong) oneofField_ : 0UL; } + set { + oneofField_ = value; + oneofFieldCase_ = OneofFieldOneofCase.OneofUint64; + } + } + + /// <summary>Field number for the "oneof_float" field.</summary> + public const int OneofFloatFieldNumber = 117; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public float OneofFloat { + get { return oneofFieldCase_ == OneofFieldOneofCase.OneofFloat ? (float) oneofField_ : 0F; } + set { + oneofField_ = value; + oneofFieldCase_ = OneofFieldOneofCase.OneofFloat; + } + } + + /// <summary>Field number for the "oneof_double" field.</summary> + public const int OneofDoubleFieldNumber = 118; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public double OneofDouble { + get { return oneofFieldCase_ == OneofFieldOneofCase.OneofDouble ? (double) oneofField_ : 0D; } + set { + oneofField_ = value; + oneofFieldCase_ = OneofFieldOneofCase.OneofDouble; + } + } + + /// <summary>Field number for the "oneof_enum" field.</summary> + public const int OneofEnumFieldNumber = 119; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public global::Conformance.TestAllTypes.Types.NestedEnum OneofEnum { + get { return oneofFieldCase_ == OneofFieldOneofCase.OneofEnum ? (global::Conformance.TestAllTypes.Types.NestedEnum) oneofField_ : 0; } + set { + oneofField_ = value; + oneofFieldCase_ = OneofFieldOneofCase.OneofEnum; + } + } + /// <summary>Field number for the "optional_bool_wrapper" field.</summary> public const int OptionalBoolWrapperFieldNumber = 201; private static readonly pb::FieldCodec<bool?> _single_optionalBoolWrapper_codec = pb::FieldCodec.ForStructWrapper<bool>(1610); @@ -1939,6 +2022,7 @@ namespace Conformance { private int fieldname1_; /// <summary> /// Test field-name-to-JSON-name convention. + /// (protobuf says names can be any valid C/C++ identifier.) /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute] public int Fieldname1 { @@ -2069,6 +2153,72 @@ namespace Conformance { } } + /// <summary>Field number for the "__field_name13" field.</summary> + public const int FieldName13FieldNumber = 413; + private int FieldName13_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName13 { + get { return FieldName13_; } + set { + FieldName13_ = value; + } + } + + /// <summary>Field number for the "__Field_name14" field.</summary> + public const int FieldName14FieldNumber = 414; + private int FieldName14_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName14 { + get { return FieldName14_; } + set { + FieldName14_ = value; + } + } + + /// <summary>Field number for the "field__name15" field.</summary> + public const int FieldName15FieldNumber = 415; + private int fieldName15_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName15 { + get { return fieldName15_; } + set { + fieldName15_ = value; + } + } + + /// <summary>Field number for the "field__Name16" field.</summary> + public const int FieldName16FieldNumber = 416; + private int fieldName16_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName16 { + get { return fieldName16_; } + set { + fieldName16_ = value; + } + } + + /// <summary>Field number for the "field_name17__" field.</summary> + public const int FieldName17FieldNumber = 417; + private int fieldName17_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName17 { + get { return fieldName17_; } + set { + fieldName17_ = value; + } + } + + /// <summary>Field number for the "Field_name18__" field.</summary> + public const int FieldName18FieldNumber = 418; + private int fieldName18_; + [global::System.Diagnostics.DebuggerNonUserCodeAttribute] + public int FieldName18 { + get { return fieldName18_; } + set { + fieldName18_ = value; + } + } + private object oneofField_; /// <summary>Enum of possible cases for the "oneof_field" oneof.</summary> public enum OneofFieldOneofCase { @@ -2077,6 +2227,11 @@ namespace Conformance { OneofNestedMessage = 112, OneofString = 113, OneofBytes = 114, + OneofBool = 115, + OneofUint64 = 116, + OneofFloat = 117, + OneofDouble = 118, + OneofEnum = 119, } private OneofFieldOneofCase oneofFieldCase_ = OneofFieldOneofCase.None; [global::System.Diagnostics.DebuggerNonUserCodeAttribute] @@ -2169,6 +2324,11 @@ namespace Conformance { if (!object.Equals(OneofNestedMessage, other.OneofNestedMessage)) return false; if (OneofString != other.OneofString) return false; if (OneofBytes != other.OneofBytes) return false; + if (OneofBool != other.OneofBool) return false; + if (OneofUint64 != other.OneofUint64) return false; + if (OneofFloat != other.OneofFloat) return false; + if (OneofDouble != other.OneofDouble) return false; + if (OneofEnum != other.OneofEnum) return false; if (OptionalBoolWrapper != other.OptionalBoolWrapper) return false; if (OptionalInt32Wrapper != other.OptionalInt32Wrapper) return false; if (OptionalInt64Wrapper != other.OptionalInt64Wrapper) return false; @@ -2211,6 +2371,12 @@ namespace Conformance { if (FieldName10 != other.FieldName10) return false; if (FIELDNAME11 != other.FIELDNAME11) return false; if (FIELDName12 != other.FIELDName12) return false; + if (FieldName13 != other.FieldName13) return false; + if (FieldName14 != other.FieldName14) return false; + if (FieldName15 != other.FieldName15) return false; + if (FieldName16 != other.FieldName16) return false; + if (FieldName17 != other.FieldName17) return false; + if (FieldName18 != other.FieldName18) return false; if (OneofFieldCase != other.OneofFieldCase) return false; return true; } @@ -2284,6 +2450,11 @@ namespace Conformance { if (oneofFieldCase_ == OneofFieldOneofCase.OneofNestedMessage) hash ^= OneofNestedMessage.GetHashCode(); if (oneofFieldCase_ == OneofFieldOneofCase.OneofString) hash ^= OneofString.GetHashCode(); if (oneofFieldCase_ == OneofFieldOneofCase.OneofBytes) hash ^= OneofBytes.GetHashCode(); + if (oneofFieldCase_ == OneofFieldOneofCase.OneofBool) hash ^= OneofBool.GetHashCode(); + if (oneofFieldCase_ == OneofFieldOneofCase.OneofUint64) hash ^= OneofUint64.GetHashCode(); + if (oneofFieldCase_ == OneofFieldOneofCase.OneofFloat) hash ^= OneofFloat.GetHashCode(); + if (oneofFieldCase_ == OneofFieldOneofCase.OneofDouble) hash ^= OneofDouble.GetHashCode(); + if (oneofFieldCase_ == OneofFieldOneofCase.OneofEnum) hash ^= OneofEnum.GetHashCode(); if (optionalBoolWrapper_ != null) hash ^= OptionalBoolWrapper.GetHashCode(); if (optionalInt32Wrapper_ != null) hash ^= OptionalInt32Wrapper.GetHashCode(); if (optionalInt64Wrapper_ != null) hash ^= OptionalInt64Wrapper.GetHashCode(); @@ -2326,6 +2497,12 @@ namespace Conformance { if (FieldName10 != 0) hash ^= FieldName10.GetHashCode(); if (FIELDNAME11 != 0) hash ^= FIELDNAME11.GetHashCode(); if (FIELDName12 != 0) hash ^= FIELDName12.GetHashCode(); + if (FieldName13 != 0) hash ^= FieldName13.GetHashCode(); + if (FieldName14 != 0) hash ^= FieldName14.GetHashCode(); + if (FieldName15 != 0) hash ^= FieldName15.GetHashCode(); + if (FieldName16 != 0) hash ^= FieldName16.GetHashCode(); + if (FieldName17 != 0) hash ^= FieldName17.GetHashCode(); + if (FieldName18 != 0) hash ^= FieldName18.GetHashCode(); hash ^= (int) oneofFieldCase_; return hash; } @@ -2481,6 +2658,26 @@ namespace Conformance { output.WriteRawTag(146, 7); output.WriteBytes(OneofBytes); } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofBool) { + output.WriteRawTag(152, 7); + output.WriteBool(OneofBool); + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofUint64) { + output.WriteRawTag(160, 7); + output.WriteUInt64(OneofUint64); + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofFloat) { + output.WriteRawTag(173, 7); + output.WriteFloat(OneofFloat); + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofDouble) { + output.WriteRawTag(177, 7); + output.WriteDouble(OneofDouble); + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofEnum) { + output.WriteRawTag(184, 7); + output.WriteEnum((int) OneofEnum); + } if (optionalBoolWrapper_ != null) { _single_optionalBoolWrapper_codec.WriteTagAndValue(output, OptionalBoolWrapper); } @@ -2595,6 +2792,30 @@ namespace Conformance { output.WriteRawTag(224, 25); output.WriteInt32(FIELDName12); } + if (FieldName13 != 0) { + output.WriteRawTag(232, 25); + output.WriteInt32(FieldName13); + } + if (FieldName14 != 0) { + output.WriteRawTag(240, 25); + output.WriteInt32(FieldName14); + } + if (FieldName15 != 0) { + output.WriteRawTag(248, 25); + output.WriteInt32(FieldName15); + } + if (FieldName16 != 0) { + output.WriteRawTag(128, 26); + output.WriteInt32(FieldName16); + } + if (FieldName17 != 0) { + output.WriteRawTag(136, 26); + output.WriteInt32(FieldName17); + } + if (FieldName18 != 0) { + output.WriteRawTag(144, 26); + output.WriteInt32(FieldName18); + } } [global::System.Diagnostics.DebuggerNonUserCodeAttribute] @@ -2718,6 +2939,21 @@ namespace Conformance { if (oneofFieldCase_ == OneofFieldOneofCase.OneofBytes) { size += 2 + pb::CodedOutputStream.ComputeBytesSize(OneofBytes); } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofBool) { + size += 2 + 1; + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofUint64) { + size += 2 + pb::CodedOutputStream.ComputeUInt64Size(OneofUint64); + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofFloat) { + size += 2 + 4; + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofDouble) { + size += 2 + 8; + } + if (oneofFieldCase_ == OneofFieldOneofCase.OneofEnum) { + size += 2 + pb::CodedOutputStream.ComputeEnumSize((int) OneofEnum); + } if (optionalBoolWrapper_ != null) { size += _single_optionalBoolWrapper_codec.CalculateSizeWithTag(OptionalBoolWrapper); } @@ -2814,6 +3050,24 @@ namespace Conformance { if (FIELDName12 != 0) { size += 2 + pb::CodedOutputStream.ComputeInt32Size(FIELDName12); } + if (FieldName13 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName13); + } + if (FieldName14 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName14); + } + if (FieldName15 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName15); + } + if (FieldName16 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName16); + } + if (FieldName17 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName17); + } + if (FieldName18 != 0) { + size += 2 + pb::CodedOutputStream.ComputeInt32Size(FieldName18); + } return size; } @@ -3069,6 +3323,24 @@ namespace Conformance { if (other.FIELDName12 != 0) { FIELDName12 = other.FIELDName12; } + if (other.FieldName13 != 0) { + FieldName13 = other.FieldName13; + } + if (other.FieldName14 != 0) { + FieldName14 = other.FieldName14; + } + if (other.FieldName15 != 0) { + FieldName15 = other.FieldName15; + } + if (other.FieldName16 != 0) { + FieldName16 = other.FieldName16; + } + if (other.FieldName17 != 0) { + FieldName17 = other.FieldName17; + } + if (other.FieldName18 != 0) { + FieldName18 = other.FieldName18; + } switch (other.OneofFieldCase) { case OneofFieldOneofCase.OneofUint32: OneofUint32 = other.OneofUint32; @@ -3082,6 +3354,21 @@ namespace Conformance { case OneofFieldOneofCase.OneofBytes: OneofBytes = other.OneofBytes; break; + case OneofFieldOneofCase.OneofBool: + OneofBool = other.OneofBool; + break; + case OneofFieldOneofCase.OneofUint64: + OneofUint64 = other.OneofUint64; + break; + case OneofFieldOneofCase.OneofFloat: + OneofFloat = other.OneofFloat; + break; + case OneofFieldOneofCase.OneofDouble: + OneofDouble = other.OneofDouble; + break; + case OneofFieldOneofCase.OneofEnum: + OneofEnum = other.OneofEnum; + break; } } @@ -3387,6 +3674,27 @@ namespace Conformance { OneofBytes = input.ReadBytes(); break; } + case 920: { + OneofBool = input.ReadBool(); + break; + } + case 928: { + OneofUint64 = input.ReadUInt64(); + break; + } + case 941: { + OneofFloat = input.ReadFloat(); + break; + } + case 945: { + OneofDouble = input.ReadDouble(); + break; + } + case 952: { + oneofField_ = input.ReadEnum(); + oneofFieldCase_ = OneofFieldOneofCase.OneofEnum; + break; + } case 1610: { bool? value = _single_optionalBoolWrapper_codec.Read(input); if (optionalBoolWrapper_ == null || value != false) { @@ -3600,6 +3908,30 @@ namespace Conformance { FIELDName12 = input.ReadInt32(); break; } + case 3304: { + FieldName13 = input.ReadInt32(); + break; + } + case 3312: { + FieldName14 = input.ReadInt32(); + break; + } + case 3320: { + FieldName15 = input.ReadInt32(); + break; + } + case 3328: { + FieldName16 = input.ReadInt32(); + break; + } + case 3336: { + FieldName17 = input.ReadInt32(); + break; + } + case 3344: { + FieldName18 = input.ReadInt32(); + break; + } } } } diff --git a/docs/third_party.md b/docs/third_party.md index 021cc564..935deab6 100644 --- a/docs/third_party.md +++ b/docs/third_party.md @@ -36,6 +36,7 @@ These are projects we know about implementing Protocol Buffers for other program * Erlang: http://piqi.org/ * Erlang: https://code.google.com/p/protoc-gen-erl/ * Erlang: https://github.com/basho/erlang_protobuffs +* Erlang: https://github.com/tomas-abrahamsson/gpb * Go: https://github.com/golang/protobuf (Google-official implementation) * Go: http://code.google.com/p/goprotobuf/ * Go: https://github.com/akunspy/gopbuf 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/objectivec/DevTools/compile_testing_protos.sh b/objectivec/DevTools/compile_testing_protos.sh index 82953130..9a6b7bf2 100755 --- a/objectivec/DevTools/compile_testing_protos.sh +++ b/objectivec/DevTools/compile_testing_protos.sh @@ -99,26 +99,26 @@ CORE_PROTO_FILES+=( src/google/protobuf/descriptor.proto ) -compile_proto() { +compile_protos() { src/protoc \ --objc_out="${OUTPUT_DIR}/google/protobuf" \ --proto_path=src/google/protobuf/ \ --proto_path=src \ - $* + "$@" } +# Note: there is overlap in package.Message names between some of the test +# files, so they can't be generated all at once. This works because the overlap +# isn't linked into a single binary. for a_proto in "${CORE_PROTO_FILES[@]}" ; do - compile_proto "${a_proto}" + compile_protos "${a_proto}" done -OBJC_PROTO_FILES=( - objectivec/Tests/unittest_cycle.proto - objectivec/Tests/unittest_runtime_proto2.proto - objectivec/Tests/unittest_runtime_proto3.proto - objectivec/Tests/unittest_objc.proto +# Objective C specific testing protos. +compile_protos \ + --proto_path="objectivec/Tests" \ + objectivec/Tests/unittest_cycle.proto \ + objectivec/Tests/unittest_runtime_proto2.proto \ + objectivec/Tests/unittest_runtime_proto3.proto \ + objectivec/Tests/unittest_objc.proto \ objectivec/Tests/unittest_objc_startup.proto -) - -for a_proto in "${OBJC_PROTO_FILES[@]}" ; do - compile_proto --proto_path="objectivec/Tests" "${a_proto}" -done diff --git a/objectivec/GPBArray.h b/objectivec/GPBArray.h index afda57f3..781cfb6f 100644 --- a/objectivec/GPBArray.h +++ b/objectivec/GPBArray.h @@ -32,11 +32,6 @@ #import "GPBRuntimeTypes.h" -// These classes are used for repeated fields of basic data types. They are used because -// they perform better than boxing into NSNumbers in NSArrays. - -// Note: These are not meant to be subclassed. - NS_ASSUME_NONNULL_BEGIN //%PDDM-EXPAND DECLARE_ARRAYS() @@ -44,39 +39,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Int32 +/** + * Class used for repeated fields of int32_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt32Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBInt32Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBInt32Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBInt32Array with value in it. + **/ + (instancetype)arrayWithValue:(int32_t)value; + +/** + * Creates and initializes a GPBInt32Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBInt32Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBInt32Array *)array; + +/** + * Creates and initializes a GPBInt32Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBInt32Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBInt32Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBInt32Array with a copy of the values. + **/ - (instancetype)initWithValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBInt32Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBInt32Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBInt32Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBInt32Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int32_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -84,39 +211,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - UInt32 +/** + * Class used for repeated fields of uint32_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt32Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBUInt32Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBUInt32Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBUInt32Array with value in it. + **/ + (instancetype)arrayWithValue:(uint32_t)value; + +/** + * Creates and initializes a GPBUInt32Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBUInt32Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBUInt32Array *)array; + +/** + * Creates and initializes a GPBUInt32Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBUInt32Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBUInt32Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBUInt32Array with a copy of the values. + **/ - (instancetype)initWithValues:(const uint32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBUInt32Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBUInt32Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBUInt32Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (uint32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(uint32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(uint32_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(uint32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const uint32_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBUInt32Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(uint32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(uint32_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -124,39 +383,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Int64 +/** + * Class used for repeated fields of int64_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBInt64Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBInt64Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBInt64Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBInt64Array with value in it. + **/ + (instancetype)arrayWithValue:(int64_t)value; + +/** + * Creates and initializes a GPBInt64Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBInt64Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBInt64Array *)array; + +/** + * Creates and initializes a GPBInt64Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBInt64Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBInt64Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBInt64Array with a copy of the values. + **/ - (instancetype)initWithValues:(const int64_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBInt64Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBInt64Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBInt64Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int64_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int64_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int64_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int64_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int64_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBInt64Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int64_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int64_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -164,39 +555,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - UInt64 +/** + * Class used for repeated fields of uint64_t values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBUInt64Array : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBUInt64Array. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBUInt64Array with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBUInt64Array with value in it. + **/ + (instancetype)arrayWithValue:(uint64_t)value; + +/** + * Creates and initializes a GPBUInt64Array with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBUInt64Array with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBUInt64Array *)array; + +/** + * Creates and initializes a GPBUInt64Array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBUInt64Array with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBUInt64Array. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBUInt64Array with a copy of the values. + **/ - (instancetype)initWithValues:(const uint64_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBUInt64Array with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBUInt64Array *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBUInt64Array with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (uint64_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(uint64_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(uint64_t value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(uint64_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const uint64_t [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBUInt64Array *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(uint64_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(uint64_t)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -204,39 +727,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Float +/** + * Class used for repeated fields of float values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBFloatArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBFloatArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBFloatArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBFloatArray with value in it. + **/ + (instancetype)arrayWithValue:(float)value; + +/** + * Creates and initializes a GPBFloatArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBFloatArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBFloatArray *)array; + +/** + * Creates and initializes a GPBFloatArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBFloatArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBFloatArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBFloatArray with a copy of the values. + **/ - (instancetype)initWithValues:(const float [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBFloatArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBFloatArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBFloatArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (float)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(float value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(float value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(float)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const float [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBFloatArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(float)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(float)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -244,39 +899,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Double +/** + * Class used for repeated fields of double values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBDoubleArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBDoubleArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBDoubleArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBDoubleArray with value in it. + **/ + (instancetype)arrayWithValue:(double)value; + +/** + * Creates and initializes a GPBDoubleArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBDoubleArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBDoubleArray *)array; + +/** + * Creates and initializes a GPBDoubleArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBDoubleArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBDoubleArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBDoubleArray with a copy of the values. + **/ - (instancetype)initWithValues:(const double [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBDoubleArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBDoubleArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBDoubleArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (double)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(double value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(double value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(double)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const double [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBDoubleArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(double)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(double)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -284,39 +1071,171 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Bool +/** + * Class used for repeated fields of BOOL values. This performs better than + * boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBBoolArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** + * @return A newly instanced and empty GPBBoolArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBBoolArray with the single element given. + * + * @param value The value to be placed in the array. + * + * @return A newly instanced GPBBoolArray with value in it. + **/ + (instancetype)arrayWithValue:(BOOL)value; + +/** + * Creates and initializes a GPBBoolArray with the contents of the given + * array. + * + * @param array Array with the contents to be put into the new array. + * + * @return A newly instanced GPBBoolArray with the contents of array. + **/ + (instancetype)arrayWithValueArray:(GPBBoolArray *)array; + +/** + * Creates and initializes a GPBBoolArray with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBBoolArray with a capacity of count. + **/ + (instancetype)arrayWithCapacity:(NSUInteger)count; +/** + * @return A newly initialized and empty GPBBoolArray. + **/ - (instancetype)init NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. + +/** + * Initializes the array, copying the given values. + * + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBBoolArray with a copy of the values. + **/ - (instancetype)initWithValues:(const BOOL [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBBoolArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBBoolArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBBoolArray with a capacity of count. + **/ - (instancetype)initWithCapacity:(NSUInteger)count; +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (BOOL)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(BOOL value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(BOOL value, NSUInteger idx, BOOL *stop))block; +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(BOOL)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const BOOL [])values count:(NSUInteger)count; + +/** + * Adds the values from the given array to this array. + * + * @param array The array containing the elements to add to this array. + **/ - (void)addValuesFromArray:(GPBBoolArray *)array; +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(BOOL)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(BOOL)value; +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -324,27 +1243,108 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum +/** + * This class is used for repeated fields of int32_t values. This performs + * better than boxing into NSNumbers in NSArrays. + * + * @note This class is not meant to be subclassed. + **/ @interface GPBEnumArray : NSObject <NSCopying> +/** The number of elements contained in the array. */ @property(nonatomic, readonly) NSUInteger count; +/** The validation function to check if the enums are valid. */ @property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; +/** + * @return A newly instanced and empty GPBEnumArray. + **/ + (instancetype)array; + +/** + * Creates and initializes a GPBEnumArray with the enum validation function + * given. + * + * @param func The enum validation function for the array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func; + +/** + * Creates and initializes a GPBEnumArray with the enum validation function + * given and the single raw value given. + * + * @param func The enum validation function for the array. + * @param value The raw value to add to this array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValue:(int32_t)value; + +/** + * Creates and initializes a GPBEnumArray that adds the elements from the + * given array. + * + * @param array Array containing the values to add to the new array. + * + * @return A newly instanced GPBEnumArray. + **/ + (instancetype)arrayWithValueArray:(GPBEnumArray *)array; + +/** + * Creates and initializes a GPBEnumArray with the given enum validation + * function and with the givencapacity. + * + * @param func The enum validation function for the array. + * @param count The capacity needed for the array. + * + * @return A newly instanced GPBEnumArray with a capacity of count. + **/ + (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)count; +/** + * Initializes the array with the given enum validation function. + * + * @param func The enum validation function for the array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func NS_DESIGNATED_INITIALIZER; -// Initializes the array, copying the values. +/** + * Initializes the array, copying the given values. + * + * @param func The enum validation function for the array. + * @param values An array with the values to put inside this array. + * @param count The number of elements to copy into the array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func rawValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Initializes the array, copying the given values. + * + * @param array An array with the values to put inside this array. + * + * @return A newly initialized GPBEnumArray with a copy of the values. + **/ - (instancetype)initWithValueArray:(GPBEnumArray *)array; + +/** + * Initializes the array with the given capacity. + * + * @param func The enum validation function for the array. + * @param count The capacity needed for the array. + * + * @return A newly initialized GPBEnumArray with a capacity of count. + **/ - (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func capacity:(NSUInteger)count; @@ -352,18 +1352,68 @@ NS_ASSUME_NONNULL_BEGIN // valid enumerator as defined by validationFunc. If the actual value is // desired, use "raw" version of the method. +/** + * Gets the value at the given index. + * + * @param index The index of the value to get. + * + * @return The value at the given index. + **/ - (int32_t)valueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; // These methods bypass the validationFunc to provide access to values that were not // known at the time the binary was compiled. +/** + * Gets the raw enum value at the given index. + * + * @param index The index of the raw enum value to get. + * + * @return The raw enum value at the given index. + **/ - (int32_t)rawValueAtIndex:(NSUInteger)index; +/** + * Enumerates the values on this array with the given block. + * + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateRawValuesWithBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; + +/** + * Enumerates the values on this array with the given block. + * + * @param opts Options to control the enumeration. + * @param block The block to enumerate with. + * **value**: The current value being enumerated. + * **idx**: The index of the current value. + * **stop**: A pointer to a boolean that when set stops the enumeration. + **/ - (void)enumerateRawValuesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(int32_t value, NSUInteger idx, BOOL *stop))block; @@ -372,29 +1422,114 @@ NS_ASSUME_NONNULL_BEGIN // to the default value. Use the rawValue methods below to assign non enumerator // values. +/** + * Adds a value to this array. + * + * @param value The value to add to this array. + **/ - (void)addValue:(int32_t)value; + +/** + * Adds values to this array. + * + * @param values The values to add to this array. + * @param count The number of elements to add. + **/ - (void)addValues:(const int32_t [])values count:(NSUInteger)count; + +/** + * Inserts a value into the given position. + * + * @param value The value to add to this array. + * @param index The index into which to insert the value. + **/ - (void)insertValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the value at the given index with the given value. + * + * @param index The index for which to replace the value. + * @param value The value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withValue:(int32_t)value; // These methods bypass the validationFunc to provide setting of values that were not // known at the time the binary was compiled. +/** + * Adds a raw enum value to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param value The raw enum value to add to the array. + **/ - (void)addRawValue:(int32_t)value; + +/** + * Adds raw enum values to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param array Array containing the raw enum values to add to this array. + **/ - (void)addRawValuesFromArray:(GPBEnumArray *)array; + +/** + * Adds raw enum values to this array. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param values Array containing the raw enum values to add to this array. + * @param count The number of raw values to add. + **/ - (void)addRawValues:(const int32_t [])values count:(NSUInteger)count; +/** + * Inserts a raw enum value at the given index. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param value Raw enum value to add. + * @param index The index into which to insert the value. + **/ - (void)insertRawValue:(int32_t)value atIndex:(NSUInteger)index; +/** + * Replaces the raw enum value at the given index with the given value. + * + * @note This method bypass the validationFunc to enable the setting of values that + * were not known at the time the binary was compiled. + * + * @param index The index for which to replace the value. + * @param value The raw enum value to replace with. + **/ - (void)replaceValueAtIndex:(NSUInteger)index withRawValue:(int32_t)value; // No validation applies to these methods. +/** + * Removes the value at the given index. + * + * @param index The index of the value to remove. + **/ - (void)removeValueAtIndex:(NSUInteger)index; + +/** + * Removes all the values from this array. + **/ - (void)removeAll; +/** + * Exchanges the values between the given indexes. + * + * @param idx1 The index of the first element to exchange. + * @param idx2 The index of the second element to exchange. + **/ - (void)exchangeValueAtIndex:(NSUInteger)idx1 withValueAtIndex:(NSUInteger)idx2; @@ -421,20 +1556,82 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE ARRAY_INTERFACE_SIMPLE(NAME, TYPE) //%#pragma mark - NAME //% +//%/** +//% * Class used for repeated fields of ##TYPE## values. This performs better than +//% * boxing into NSNumbers in NSArrays. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface GPB##NAME##Array : NSObject <NSCopying> //% +//%/** The number of elements contained in the array. */ //%@property(nonatomic, readonly) NSUInteger count; //% +//%/** +//% * @return A newly instanced and empty GPB##NAME##Array. +//% **/ //%+ (instancetype)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the single element given. +//% * +//% * @param value The value to be placed in the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with value in it. +//% **/ //%+ (instancetype)arrayWithValue:(TYPE)value; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the contents of the given +//% * array. +//% * +//% * @param array Array with the contents to be put into the new array. +//% * +//% * @return A newly instanced GPB##NAME##Array with the contents of array. +//% **/ //%+ (instancetype)arrayWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the given capacity. +//% * +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with a capacity of count. +//% **/ //%+ (instancetype)arrayWithCapacity:(NSUInteger)count; //% +//%/** +//% * @return A newly initialized and empty GPB##NAME##Array. +//% **/ //%- (instancetype)init NS_DESIGNATED_INITIALIZER; -//%// Initializes the array, copying the values. +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param values An array with the values to put inside this array. +//% * @param count The number of elements to copy into the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValues:(const TYPE [])values //% count:(NSUInteger)count; +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param array An array with the values to put inside this array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Initializes the array with the given capacity. +//% * +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a capacity of count. +//% **/ //%- (instancetype)initWithCapacity:(NSUInteger)count; //% //%ARRAY_IMMUTABLE_INTERFACE(NAME, TYPE, Basic) @@ -451,27 +1648,108 @@ NS_ASSUME_NONNULL_END //%PDDM-DEFINE ARRAY_INTERFACE_ENUM(NAME, TYPE) //%#pragma mark - NAME //% +//%/** +//% * This class is used for repeated fields of ##TYPE## values. This performs +//% * better than boxing into NSNumbers in NSArrays. +//% * +//% * @note This class is not meant to be subclassed. +//% **/ //%@interface GPB##NAME##Array : NSObject <NSCopying> //% +//%/** The number of elements contained in the array. */ //%@property(nonatomic, readonly) NSUInteger count; +//%/** The validation function to check if the enums are valid. */ //%@property(nonatomic, readonly) GPBEnumValidationFunc validationFunc; //% +//%/** +//% * @return A newly instanced and empty GPB##NAME##Array. +//% **/ //%+ (instancetype)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the enum validation function +//% * given. +//% * +//% * @param func The enum validation function for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the enum validation function +//% * given and the single raw value given. +//% * +//% * @param func The enum validation function for the array. +//% * @param value The raw value to add to this array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValue:(TYPE)value; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array that adds the elements from the +//% * given array. +//% * +//% * @param array Array containing the values to add to the new array. +//% * +//% * @return A newly instanced GPB##NAME##Array. +//% **/ //%+ (instancetype)arrayWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Creates and initializes a GPB##NAME##Array with the given enum validation +//% * function and with the givencapacity. +//% * +//% * @param func The enum validation function for the array. +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly instanced GPB##NAME##Array with a capacity of count. +//% **/ //%+ (instancetype)arrayWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)count; //% +//%/** +//% * Initializes the array with the given enum validation function. +//% * +//% * @param func The enum validation function for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% NS_DESIGNATED_INITIALIZER; //% -//%// Initializes the array, copying the values. +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param func The enum validation function for the array. +//% * @param values An array with the values to put inside this array. +//% * @param count The number of elements to copy into the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% rawValues:(const TYPE [])values //% count:(NSUInteger)count; +//% +//%/** +//% * Initializes the array, copying the given values. +//% * +//% * @param array An array with the values to put inside this array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a copy of the values. +//% **/ //%- (instancetype)initWithValueArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Initializes the array with the given capacity. +//% * +//% * @param func The enum validation function for the array. +//% * @param count The capacity needed for the array. +//% * +//% * @return A newly initialized GPB##NAME##Array with a capacity of count. +//% **/ //%- (instancetype)initWithValidationFunction:(nullable GPBEnumValidationFunc)func //% capacity:(NSUInteger)count; //% @@ -484,9 +1762,34 @@ NS_ASSUME_NONNULL_END //%// These methods bypass the validationFunc to provide access to values that were not //%// known at the time the binary was compiled. //% +//%/** +//% * Gets the raw enum value at the given index. +//% * +//% * @param index The index of the raw enum value to get. +//% * +//% * @return The raw enum value at the given index. +//% **/ //%- (TYPE)rawValueAtIndex:(NSUInteger)index; //% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateRawValuesWithBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; +//% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param opts Options to control the enumeration. +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateRawValuesWithOptions:(NSEnumerationOptions)opts //% usingBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; //% @@ -501,23 +1804,88 @@ NS_ASSUME_NONNULL_END //% //%PDDM-DEFINE ARRAY_IMMUTABLE_INTERFACE(NAME, TYPE, HELPER_NAME) +//%/** +//% * Gets the value at the given index. +//% * +//% * @param index The index of the value to get. +//% * +//% * @return The value at the given index. +//% **/ //%- (TYPE)valueAtIndex:(NSUInteger)index; //% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateValuesWithBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; +//% +//%/** +//% * Enumerates the values on this array with the given block. +//% * +//% * @param opts Options to control the enumeration. +//% * @param block The block to enumerate with. +//% * **value**: The current value being enumerated. +//% * **idx**: The index of the current value. +//% * **stop**: A pointer to a boolean that when set stops the enumeration. +//% **/ //%- (void)enumerateValuesWithOptions:(NSEnumerationOptions)opts //% usingBlock:(void (^)(TYPE value, NSUInteger idx, BOOL *stop))block; //%PDDM-DEFINE ARRAY_MUTABLE_INTERFACE(NAME, TYPE, HELPER_NAME) +//%/** +//% * Adds a value to this array. +//% * +//% * @param value The value to add to this array. +//% **/ //%- (void)addValue:(TYPE)value; +//% +//%/** +//% * Adds values to this array. +//% * +//% * @param values The values to add to this array. +//% * @param count The number of elements to add. +//% **/ //%- (void)addValues:(const TYPE [])values count:(NSUInteger)count; +//% //%ARRAY_EXTRA_MUTABLE_METHODS1_##HELPER_NAME(NAME, TYPE) +//%/** +//% * Inserts a value into the given position. +//% * +//% * @param value The value to add to this array. +//% * @param index The index into which to insert the value. +//% **/ //%- (void)insertValue:(TYPE)value atIndex:(NSUInteger)index; //% +//%/** +//% * Replaces the value at the given index with the given value. +//% * +//% * @param index The index for which to replace the value. +//% * @param value The value to replace with. +//% **/ //%- (void)replaceValueAtIndex:(NSUInteger)index withValue:(TYPE)value; //%ARRAY_EXTRA_MUTABLE_METHODS2_##HELPER_NAME(NAME, TYPE) +//%/** +//% * Removes the value at the given index. +//% * +//% * @param index The index of the value to remove. +//% **/ //%- (void)removeValueAtIndex:(NSUInteger)index; +//% +//%/** +//% * Removes all the values from this array. +//% **/ //%- (void)removeAll; //% +//%/** +//% * Exchanges the values between the given indexes. +//% * +//% * @param idx1 The index of the first element to exchange. +//% * @param idx2 The index of the second element to exchange. +//% **/ //%- (void)exchangeValueAtIndex:(NSUInteger)idx1 //% withValueAtIndex:(NSUInteger)idx2; @@ -526,6 +1894,11 @@ NS_ASSUME_NONNULL_END // //%PDDM-DEFINE ARRAY_EXTRA_MUTABLE_METHODS1_Basic(NAME, TYPE) +//%/** +//% * Adds the values from the given array to this array. +//% * +//% * @param array The array containing the elements to add to this array. +//% **/ //%- (void)addValuesFromArray:(GPB##NAME##Array *)array; //% //%PDDM-DEFINE ARRAY_EXTRA_MUTABLE_METHODS2_Basic(NAME, TYPE) @@ -537,12 +1910,57 @@ NS_ASSUME_NONNULL_END //%// These methods bypass the validationFunc to provide setting of values that were not //%// known at the time the binary was compiled. //% +//%/** +//% * Adds a raw enum value to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param value The raw enum value to add to the array. +//% **/ //%- (void)addRawValue:(TYPE)value; +//% +//%/** +//% * Adds raw enum values to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param array Array containing the raw enum values to add to this array. +//% **/ //%- (void)addRawValuesFromArray:(GPB##NAME##Array *)array; +//% +//%/** +//% * Adds raw enum values to this array. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param values Array containing the raw enum values to add to this array. +//% * @param count The number of raw values to add. +//% **/ //%- (void)addRawValues:(const TYPE [])values count:(NSUInteger)count; //% +//%/** +//% * Inserts a raw enum value at the given index. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param value Raw enum value to add. +//% * @param index The index into which to insert the value. +//% **/ //%- (void)insertRawValue:(TYPE)value atIndex:(NSUInteger)index; //% +//%/** +//% * Replaces the raw enum value at the given index with the given value. +//% * +//% * @note This method bypass the validationFunc to enable the setting of values that +//% * were not known at the time the binary was compiled. +//% * +//% * @param index The index for which to replace the value. +//% * @param value The raw enum value to replace with. +//% **/ //%- (void)replaceValueAtIndex:(NSUInteger)index withRawValue:(TYPE)value; //% //%// No validation applies to these methods. diff --git a/objectivec/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/GPBCodedOutputStream.m b/objectivec/GPBCodedOutputStream.m index 63ba8068..251a159c 100644 --- a/objectivec/GPBCodedOutputStream.m +++ b/objectivec/GPBCodedOutputStream.m @@ -144,22 +144,6 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state, GPBWriteRawByte(state, (int32_t)(value >> 56) & 0xFF); } -#if defined(DEBUG) && DEBUG && !defined(NS_BLOCK_ASSERTIONS) -+ (void)load { - // This test exists to verify that CFStrings with embedded NULLs will work - // for us. If this Assert fails, all code below that depends on - // CFStringGetCStringPtr will NOT work properly on strings that contain - // embedded NULLs, and we do get that in some protobufs. - // Note that this will not be compiled in release. - // We didn't feel that just keeping it in a unit test was sufficient because - // the Protobuf unit tests are only run when somebody is actually working - // on protobufs. - CFStringRef zeroTest = CFSTR("Test\0String"); - const char *cString = CFStringGetCStringPtr(zeroTest, kCFStringEncodingUTF8); - NSAssert(cString == NULL, @"Serious Error"); -} -#endif // DEBUG && !defined(NS_BLOCK_ASSERTIONS) - - (void)dealloc { [self flush]; [state_.output close]; @@ -282,19 +266,15 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state, } - (void)writeStringNoTag:(const NSString *)value { - // If you are concerned about embedded NULLs see the test in - // +load above. - const char *quickString = - CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); - size_t length = (quickString != NULL) - ? strlen(quickString) - : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; + size_t length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; GPBWriteRawVarint32(&state_, (int32_t)length); - if (length == 0) { return; } + const char *quickString = + CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); + // Fast path: Most strings are short, if the buffer already has space, // add to it directly. NSUInteger bufferBytesLeft = state_.size - state_.position; @@ -1038,14 +1018,7 @@ size_t GPBComputeBoolSizeNoTag(BOOL value) { } size_t GPBComputeStringSizeNoTag(NSString *value) { - // If you are concerned about embedded NULLs see the test in - // +load above. - const char *quickString = - CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8); - NSUInteger length = - (quickString != NULL) - ? strlen(quickString) - : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; + NSUInteger length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding]; return GPBComputeRawVarint32SizeForInteger(length) + length; } diff --git a/objectivec/GPBDescriptor.h b/objectivec/GPBDescriptor.h index fe4ff390..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..d79632d2 100644 --- a/objectivec/GPBExtensionRegistry.h +++ b/objectivec/GPBExtensionRegistry.h @@ -35,45 +35,50 @@ NS_ASSUME_NONNULL_BEGIN -/// A table of known extensions, searchable by name or field number. When -/// parsing a protocol message that might have extensions, you must provide a -/// @c GPBExtensionRegistry in which you have registered any extensions that you -/// want to be able to parse. Otherwise, those extensions will just be treated -/// like unknown fields. -/// -/// The @c *Root classes provide @c +extensionRegistry for the extensions defined -/// in a given file *and* all files it imports. You can also create a -/// @c GPBExtensionRegistry, and merge those registries to handle parsing -/// extensions defined from non overlapping files. -/// -/// @code -/// GPBExtensionRegistry *registry = -/// [[[MyProtoFileRoot extensionRegistry] copy] autorelease]; -/// [registry addExtension:[OtherMessage neededExtension]; // Not in MyProtoFile -/// NSError *parseError = nil; -/// MyMessage *msg = [MyMessage parseData:data -/// extensionRegistry:registry -/// error:&parseError]; -/// @endcode +/** + * A table of known extensions, searchable by name or field number. When + * parsing a protocol message that might have extensions, you must provide a + * GPBExtensionRegistry in which you have registered any extensions that you + * want to be able to parse. Otherwise, those extensions will just be treated + * like unknown fields. + * + * The *Root classes provide `+extensionRegistry` for the extensions defined + * in a given file *and* all files it imports. You can also create a + * GPBExtensionRegistry, and merge those registries to handle parsing + * extensions defined from non overlapping files. + * + * ``` + * GPBExtensionRegistry *registry = [[MyProtoFileRoot extensionRegistry] copy]; + * [registry addExtension:[OtherMessage neededExtension]]; // Not in MyProtoFile + * NSError *parseError; + * MyMessage *msg = [MyMessage parseData:data extensionRegistry:registry error:&parseError]; + * ``` + **/ @interface GPBExtensionRegistry : NSObject<NSCopying> -/// Add the given @c GPBExtensionDescriptor to this registry. -/// -/// @param extension The extension description to add. +/** + * Adds the given GPBExtensionDescriptor to this registry. + * + * @param extension The extension description to add. + **/ - (void)addExtension:(GPBExtensionDescriptor *)extension; -/// Adds all the extensions from another registry to this registry. -/// -/// @param registry The registry to merge into this registry. +/** + * Adds all the extensions from another registry to this registry. + * + * @param registry The registry to merge into this registry. + **/ - (void)addExtensions:(GPBExtensionRegistry *)registry; -/// Looks for the extension registered for the given field number on a given -/// @c GPBDescriptor. -/// -/// @param descriptor The descriptor to look for a registered extension on. -/// @param fieldNumber The field number of an extension to look for. -/// -/// @return The registered @c GPBExtensionDescripto or nil if none was found. +/** + * Looks for the extension registered for the given field number on a given + * GPBDescriptor. + * + * @param descriptor The descriptor to look for a registered extension on. + * @param fieldNumber The field number of the extension to look for. + * + * @return The registered GPBExtensionDescriptor or nil if none was found. + **/ - (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor fieldNumber:(NSInteger)fieldNumber; diff --git a/objectivec/GPBMessage.h b/objectivec/GPBMessage.h index 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/GPBUtilities.m b/objectivec/GPBUtilities.m index ee84fb45..80b85d07 100644 --- a/objectivec/GPBUtilities.m +++ b/objectivec/GPBUtilities.m @@ -218,9 +218,10 @@ void GPBMaybeClearOneof(GPBMessage *self, GPBOneofDescriptor *oneof, //% TYPE *typePtr = (TYPE *)&storage[field->description_->offset]; //% *typePtr = value; //% // proto2: any value counts as having been set; proto3, it -//% // has to be a non zero value. -//% BOOL hasValue = -//% (syntax == GPBFileSyntaxProto2) || (value != (TYPE)0); +//% // has to be a non zero value or be in a oneof. +//% BOOL hasValue = ((syntax == GPBFileSyntaxProto2) +//% || (value != (TYPE)0) +//% || (field->containingOneof_ != NULL)); //% GPBSetHasIvarField(self, field, hasValue); //% GPBBecomeVisibleToAutocreator(self); //%} @@ -337,8 +338,19 @@ void GPBSetRetainedObjectIvarWithFieldInternal(GPBMessage *self, // zero, they are being cleared. if ((syntax == GPBFileSyntaxProto3) && !fieldIsMessage && ([value length] == 0)) { - setHasValue = NO; - value = nil; + // Except, if the field was in a oneof, then it still gets recorded as + // having been set so the state of the oneof can be serialized back out. + if (!oneof) { + setHasValue = NO; + } + if (setHasValue) { + NSCAssert(value != nil, @"Should never be setting has for nil"); + } else { + // The value passed in was retained, it must be released since we + // aren't saving anything in the field. + [value release]; + value = nil; + } } GPBSetHasIvarField(self, field, setHasValue); } @@ -524,9 +536,10 @@ void GPBSetBoolIvarWithFieldInternal(GPBMessage *self, GPBSetHasIvar(self, (int32_t)(fieldDesc->offset), fieldDesc->number, value); // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (BOOL)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (BOOL)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -573,9 +586,10 @@ void GPBSetInt32IvarWithFieldInternal(GPBMessage *self, int32_t *typePtr = (int32_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (int32_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (int32_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -622,9 +636,10 @@ void GPBSetUInt32IvarWithFieldInternal(GPBMessage *self, uint32_t *typePtr = (uint32_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (uint32_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (uint32_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -671,9 +686,10 @@ void GPBSetInt64IvarWithFieldInternal(GPBMessage *self, int64_t *typePtr = (int64_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (int64_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (int64_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -720,9 +736,10 @@ void GPBSetUInt64IvarWithFieldInternal(GPBMessage *self, uint64_t *typePtr = (uint64_t *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (uint64_t)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (uint64_t)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -769,9 +786,10 @@ void GPBSetFloatIvarWithFieldInternal(GPBMessage *self, float *typePtr = (float *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (float)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (float)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -818,9 +836,10 @@ void GPBSetDoubleIvarWithFieldInternal(GPBMessage *self, double *typePtr = (double *)&storage[field->description_->offset]; *typePtr = value; // proto2: any value counts as having been set; proto3, it - // has to be a non zero value. - BOOL hasValue = - (syntax == GPBFileSyntaxProto2) || (value != (double)0); + // has to be a non zero value or be in a oneof. + BOOL hasValue = ((syntax == GPBFileSyntaxProto2) + || (value != (double)0) + || (field->containingOneof_ != NULL)); GPBSetHasIvarField(self, field, hasValue); GPBBecomeVisibleToAutocreator(self); } @@ -1052,7 +1071,15 @@ static void AppendStringEscaped(NSString *toPrint, NSMutableString *destStr) { case '\'': [destStr appendString:@"\\\'"]; break; case '\\': [destStr appendString:@"\\\\"]; break; default: - [destStr appendFormat:@"%C", aChar]; + // This differs slightly from the C++ code in that the C++ doesn't + // generate UTF8; it looks at the string in UTF8, but escapes every + // byte > 0x7E. + if (aChar < 0x20) { + [destStr appendFormat:@"\\%d%d%d", + (aChar / 64), ((aChar % 64) / 8), (aChar % 8)]; + } else { + [destStr appendFormat:@"%C", aChar]; + } break; } } diff --git a/objectivec/GPBUtilities_PackagePrivate.h b/objectivec/GPBUtilities_PackagePrivate.h index c02493b2..a41ee2ab 100644 --- a/objectivec/GPBUtilities_PackagePrivate.h +++ b/objectivec/GPBUtilities_PackagePrivate.h @@ -96,7 +96,7 @@ GPB_INLINE int64_t GPBLogicalRightShift64(int64_t value, int32_t spaces) { // negative values must be sign-extended to 64 bits to be varint encoded, // thus always taking 10 bytes on the wire.) GPB_INLINE int32_t GPBDecodeZigZag32(uint32_t n) { - return GPBLogicalRightShift32(n, 1) ^ -(n & 1); + return (int32_t)(GPBLogicalRightShift32((int32_t)n, 1) ^ -((int32_t)(n) & 1)); } // Decode a ZigZag-encoded 64-bit value. ZigZag encodes signed integers @@ -104,7 +104,7 @@ GPB_INLINE int32_t GPBDecodeZigZag32(uint32_t n) { // negative values must be sign-extended to 64 bits to be varint encoded, // thus always taking 10 bytes on the wire.) GPB_INLINE int64_t GPBDecodeZigZag64(uint64_t n) { - return GPBLogicalRightShift64(n, 1) ^ -(n & 1); + return (int64_t)(GPBLogicalRightShift64((int64_t)n, 1) ^ -((int64_t)(n) & 1)); } // Encode a ZigZag-encoded 32-bit value. ZigZag encodes signed integers @@ -113,7 +113,7 @@ GPB_INLINE int64_t GPBDecodeZigZag64(uint64_t n) { // thus always taking 10 bytes on the wire.) GPB_INLINE uint32_t GPBEncodeZigZag32(int32_t n) { // Note: the right-shift must be arithmetic - return (n << 1) ^ (n >> 31); + return (uint32_t)((n << 1) ^ (n >> 31)); } // Encode a ZigZag-encoded 64-bit value. ZigZag encodes signed integers @@ -122,7 +122,7 @@ GPB_INLINE uint32_t GPBEncodeZigZag32(int32_t n) { // thus always taking 10 bytes on the wire.) GPB_INLINE uint64_t GPBEncodeZigZag64(int64_t n) { // Note: the right-shift must be arithmetic - return (n << 1) ^ (n >> 63); + return (uint64_t)((n << 1) ^ (n >> 63)); } #pragma clang diagnostic push diff --git a/objectivec/GPBWellKnownTypes.h b/objectivec/GPBWellKnownTypes.h index 311ac58e..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/objectivec/Tests/GPBCodedOuputStreamTests.m b/objectivec/Tests/GPBCodedOuputStreamTests.m index 0723b645..2ad326be 100644 --- a/objectivec/Tests/GPBCodedOuputStreamTests.m +++ b/objectivec/Tests/GPBCodedOuputStreamTests.m @@ -193,6 +193,32 @@ } } +- (void)assertWriteStringNoTag:(NSData*)data + value:(NSString *)value + context:(NSString *)contextMessage { + NSOutputStream* rawOutput = [NSOutputStream outputStreamToMemory]; + GPBCodedOutputStream* output = + [GPBCodedOutputStream streamWithOutputStream:rawOutput]; + [output writeStringNoTag:value]; + [output flush]; + + NSData* actual = + [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey]; + XCTAssertEqualObjects(data, actual, @"%@", contextMessage); + + // Try different block sizes. + for (int blockSize = 1; blockSize <= 16; blockSize *= 2) { + rawOutput = [NSOutputStream outputStreamToMemory]; + output = [GPBCodedOutputStream streamWithOutputStream:rawOutput + bufferSize:blockSize]; + [output writeStringNoTag:value]; + [output flush]; + + actual = [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey]; + XCTAssertEqualObjects(data, actual, @"%@", contextMessage); + } +} + - (void)testWriteVarint1 { [self assertWriteVarint:bytes(0x00) value:0]; } @@ -337,4 +363,64 @@ XCTAssertEqualObjects(rawBytes, goldenData); } +- (void)testCFStringGetCStringPtrAndStringsWithNullChars { + // This test exists to verify that CFStrings with embedded NULLs still expose + // their raw buffer if they are backed by UTF8 storage. If this fails, the + // quick/direct access paths in GPBCodedOutputStream that depend on + // CFStringGetCStringPtr need to be re-evalutated (maybe just removed). + // And yes, we do get NULLs in strings from some servers. + + char zeroTest[] = "\0Test\0String"; + // Note: there is a \0 at the end of this since it is a c-string. + NSString *asNSString = [[NSString alloc] initWithBytes:zeroTest + length:sizeof(zeroTest) + encoding:NSUTF8StringEncoding]; + const char *cString = + CFStringGetCStringPtr((CFStringRef)asNSString, kCFStringEncodingUTF8); + XCTAssertTrue(cString != NULL); + // Again, if the above assert fails, then it means NSString no longer exposes + // the raw utf8 storage of a string created from utf8 input, so the code using + // CFStringGetCStringPtr in GPBCodedOutputStream will still work (it will take + // a different code path); but the optimizations for when + // CFStringGetCStringPtr does work could possibly go away. + + XCTAssertEqual(sizeof(zeroTest), + [asNSString lengthOfBytesUsingEncoding:NSUTF8StringEncoding]); + XCTAssertTrue(0 == memcmp(cString, zeroTest, sizeof(zeroTest))); + [asNSString release]; +} + +- (void)testWriteStringsWithZeroChar { + // Unicode allows `\0` as a character, and NSString is a class cluster, so + // there are a few different classes that could end up beind a given string. + // Historically, we've seen differences based on constant strings in code and + // strings built via the NSString apis. So this round trips them to ensure + // they are acting as expected. + + NSArray<NSString *> *strs = @[ + @"\0at start", + @"in\0middle", + @"at end\0", + ]; + int i = 0; + for (NSString *str in strs) { + NSData *asUTF8 = [str dataUsingEncoding:NSUTF8StringEncoding]; + NSMutableData *expected = [NSMutableData data]; + uint8_t lengthByte = (uint8_t)asUTF8.length; + [expected appendBytes:&lengthByte length:1]; + [expected appendData:asUTF8]; + + NSString *context = [NSString stringWithFormat:@"Loop %d - Literal", i]; + [self assertWriteStringNoTag:expected value:str context:context]; + + // Force a new string to be built which gets a different class from the + // NSString class cluster than the literal did. + NSString *str2 = [NSString stringWithFormat:@"%@", str]; + context = [NSString stringWithFormat:@"Loop %d - Built", i]; + [self assertWriteStringNoTag:expected value:str2 context:context]; + + ++i; + } +} + @end diff --git a/objectivec/Tests/GPBMessageTests+Runtime.m b/objectivec/Tests/GPBMessageTests+Runtime.m index 1520381b..2cf9ccef 100644 --- a/objectivec/Tests/GPBMessageTests+Runtime.m +++ b/objectivec/Tests/GPBMessageTests+Runtime.m @@ -326,6 +326,17 @@ //% [msg release]; //% } //% +//%PDDM-DEFINE PROTO2_TEST_CLEAR_FIELD_WITH_NIL(FIELD, VALUE) +//% { // optional##FIELD +//% Message2 *msg = [[Message2 alloc] init]; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = VALUE; +//% XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = nil; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_Optional##FIELD)); +//% [msg release]; +//% } +//% //%PDDM-DEFINE PROTO2_TEST_HAS_FIELDS() //%PROTO2_TEST_HAS_FIELD(Int32, 1, 0) //%PROTO2_TEST_HAS_FIELD(Int64, 1, 0) @@ -347,6 +358,14 @@ //% // //% //%PROTO2_TEST_HAS_FIELD(Enum, Message2_Enum_Bar, Message2_Enum_Foo) +//% // +//% // Nil can also be used to clear strings, bytes, groups, and messages. +//% // +//% +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(String, @"foo") +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding]) +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Group, [Message2_OptionalGroup message]) +//%PROTO2_TEST_CLEAR_FIELD_WITH_NIL(Message, [Message2 message]) //%PDDM-EXPAND PROTO2_TEST_HAS_FIELDS() // This block of code is generated, do not edit it directly. @@ -658,13 +677,57 @@ [msg release]; } + // + // Nil can also be used to clear strings, bytes, groups, and messages. + // + + { // optionalString + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + msg.optionalString = @"foo"; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + msg.optionalString = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalString)); + [msg release]; + } + + { // optionalBytes + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + msg.optionalBytes = [@"foo" dataUsingEncoding:NSUTF8StringEncoding]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + msg.optionalBytes = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalBytes)); + [msg release]; + } + + { // optionalGroup + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + msg.optionalGroup = [Message2_OptionalGroup message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + msg.optionalGroup = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalGroup)); + [msg release]; + } + + { // optionalMessage + Message2 *msg = [[Message2 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + msg.optionalMessage = [Message2 message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + msg.optionalMessage = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message2_FieldNumber_OptionalMessage)); + [msg release]; + } + //%PDDM-EXPAND-END PROTO2_TEST_HAS_FIELDS() } - (void)testProto3SingleFieldHasBehavior { // - // Setting to any value including the default value (0) should result has* - // being true. + // Setting to any value but the default value (0) should result has* + // being true. When set to the default, shouldn't be true. // //%PDDM-DEFINE PROTO3_TEST_HAS_FIELD(FIELD, NON_ZERO_VALUE, ZERO_VALUE) @@ -678,6 +741,17 @@ //% [msg release]; //% } //% +//%PDDM-DEFINE PROTO3_TEST_CLEAR_FIELD_WITH_NIL(FIELD, VALUE) +//% { // optional##FIELD +//% Message3 *msg = [[Message3 alloc] init]; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = VALUE; +//% XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% msg.optional##FIELD = nil; +//% XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_Optional##FIELD)); +//% [msg release]; +//% } +//% //%PDDM-DEFINE PROTO3_TEST_HAS_FIELDS() //%PROTO3_TEST_HAS_FIELD(Int32, 1, 0) //%PROTO3_TEST_HAS_FIELD(Int64, 1, 0) @@ -695,10 +769,17 @@ //%PROTO3_TEST_HAS_FIELD(String, @"foo", @"") //%PROTO3_TEST_HAS_FIELD(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding], [NSData data]) //% // -//% // Test doesn't apply to optionalGroup/optionalMessage. +//% // Test doesn't apply to optionalMessage (no groups in proto3). //% // //% //%PROTO3_TEST_HAS_FIELD(Enum, Message3_Enum_Bar, Message3_Enum_Foo) +//% // +//% // Nil can also be used to clear strings, bytes, and messages (no groups in proto3). +//% // +//% +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(String, @"foo") +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(Bytes, [@"foo" dataUsingEncoding:NSUTF8StringEncoding]) +//%PROTO3_TEST_CLEAR_FIELD_WITH_NIL(Message, [Message3 message]) //%PDDM-EXPAND PROTO3_TEST_HAS_FIELDS() // This block of code is generated, do not edit it directly. @@ -853,7 +934,7 @@ } // - // Test doesn't apply to optionalGroup/optionalMessage. + // Test doesn't apply to optionalMessage (no groups in proto3). // { // optionalEnum @@ -866,6 +947,40 @@ [msg release]; } + // + // Nil can also be used to clear strings, bytes, and messages (no groups in proto3). + // + + { // optionalString + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + msg.optionalString = @"foo"; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + msg.optionalString = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalString)); + [msg release]; + } + + { // optionalBytes + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + msg.optionalBytes = [@"foo" dataUsingEncoding:NSUTF8StringEncoding]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + msg.optionalBytes = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalBytes)); + [msg release]; + } + + { // optionalMessage + Message3 *msg = [[Message3 alloc] init]; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + msg.optionalMessage = [Message3 message]; + XCTAssertTrue(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + msg.optionalMessage = nil; + XCTAssertFalse(GPBMessageHasFieldNumberSet(msg, Message3_FieldNumber_OptionalMessage)); + [msg release]; + } + //%PDDM-EXPAND-END PROTO3_TEST_HAS_FIELDS() } @@ -1972,6 +2087,262 @@ [msg release]; } +- (void)testProto2OneofSetToDefault { + + // proto3 doesn't normally write out zero (default) fields, but if they are + // in a oneof it does. proto2 doesn't have this special behavior, but we + // still confirm setting to the explicit default does set the case to be + // sure the runtime is working correctly. + + NSString *oneofStringDefault = @"string"; + NSData *oneofBytesDefault = [@"data" dataUsingEncoding:NSUTF8StringEncoding]; + + Message2 *msg = [[Message2 alloc] init]; + + uint32_t values[] = { + Message2_O_OneOfCase_OneofInt32, + Message2_O_OneOfCase_OneofInt64, + Message2_O_OneOfCase_OneofUint32, + Message2_O_OneOfCase_OneofUint64, + Message2_O_OneOfCase_OneofSint32, + Message2_O_OneOfCase_OneofSint64, + Message2_O_OneOfCase_OneofFixed32, + Message2_O_OneOfCase_OneofFixed64, + Message2_O_OneOfCase_OneofSfixed32, + Message2_O_OneOfCase_OneofSfixed64, + Message2_O_OneOfCase_OneofFloat, + Message2_O_OneOfCase_OneofDouble, + Message2_O_OneOfCase_OneofBool, + Message2_O_OneOfCase_OneofString, + Message2_O_OneOfCase_OneofBytes, + // Skip group + // Skip message + Message2_O_OneOfCase_OneofEnum, + }; + + for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) { + switch (values[i]) { + case Message2_O_OneOfCase_OneofInt32: + msg.oneofInt32 = 100; + break; + case Message2_O_OneOfCase_OneofInt64: + msg.oneofInt64 = 101; + break; + case Message2_O_OneOfCase_OneofUint32: + msg.oneofUint32 = 102; + break; + case Message2_O_OneOfCase_OneofUint64: + msg.oneofUint64 = 103; + break; + case Message2_O_OneOfCase_OneofSint32: + msg.oneofSint32 = 104; + break; + case Message2_O_OneOfCase_OneofSint64: + msg.oneofSint64 = 105; + break; + case Message2_O_OneOfCase_OneofFixed32: + msg.oneofFixed32 = 106; + break; + case Message2_O_OneOfCase_OneofFixed64: + msg.oneofFixed64 = 107; + break; + case Message2_O_OneOfCase_OneofSfixed32: + msg.oneofSfixed32 = 108; + break; + case Message2_O_OneOfCase_OneofSfixed64: + msg.oneofSfixed64 = 109; + break; + case Message2_O_OneOfCase_OneofFloat: + msg.oneofFloat = 110.0f; + break; + case Message2_O_OneOfCase_OneofDouble: + msg.oneofDouble = 111.0; + break; + case Message2_O_OneOfCase_OneofBool: + msg.oneofBool = YES; + break; + case Message2_O_OneOfCase_OneofString: + msg.oneofString = oneofStringDefault; + break; + case Message2_O_OneOfCase_OneofBytes: + msg.oneofBytes = oneofBytesDefault; + break; + case Message2_O_OneOfCase_OneofEnum: + msg.oneofEnum = Message3_Enum_Baz; + break; + default: + XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]); + break; + } + + // Should be set to the correct case. + XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i); + + // Confirm everything is the defaults. + XCTAssertEqual(msg.oneofInt32, 100, "Loop: %zd", i); + XCTAssertEqual(msg.oneofInt64, 101, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint32, 102U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint64, 103U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint32, 104, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint64, 105, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed32, 106U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed64, 107U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed32, 108, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed64, 109, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFloat, 110.0f, "Loop: %zd", i); + XCTAssertEqual(msg.oneofDouble, 111.0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofBool, YES, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i); + // Skip group, no default to consider. + // Skip message, no default to consider. + XCTAssertEqual(msg.oneofEnum, Message2_Enum_Baz, "Loop: %zd", i); + } + + // We special case nil on string, data, group, and message, ensure they work + // as expected. i.e. - it clears the case. + msg.oneofString = nil; + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault); + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + msg.oneofBytes = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault); + msg.oneofGroup = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofGroup); + msg.oneofMessage = nil; + XCTAssertEqual(msg.oOneOfCase, Message2_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofMessage); + + [msg release]; +} + +- (void)testProto3OneofSetToZero { + + // Normally setting a proto3 field to the zero value should result in it being + // reset/cleared. But in a oneof, it still gets recored so it can go out + // over the wire and the other side can see what was set in the oneof. + + NSString *oneofStringDefault = @""; + NSData *oneofBytesDefault = [NSData data]; + + Message3 *msg = [[Message3 alloc] init]; + + uint32_t values[] = { + Message3_O_OneOfCase_OneofInt32, + Message3_O_OneOfCase_OneofInt64, + Message3_O_OneOfCase_OneofUint32, + Message3_O_OneOfCase_OneofUint64, + Message3_O_OneOfCase_OneofSint32, + Message3_O_OneOfCase_OneofSint64, + Message3_O_OneOfCase_OneofFixed32, + Message3_O_OneOfCase_OneofFixed64, + Message3_O_OneOfCase_OneofSfixed32, + Message3_O_OneOfCase_OneofSfixed64, + Message3_O_OneOfCase_OneofFloat, + Message3_O_OneOfCase_OneofDouble, + Message3_O_OneOfCase_OneofBool, + Message3_O_OneOfCase_OneofString, + Message3_O_OneOfCase_OneofBytes, + Message3_O_OneOfCase_OneofMessage, + Message3_O_OneOfCase_OneofEnum, + }; + + for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) { + switch (values[i]) { + case Message3_O_OneOfCase_OneofInt32: + msg.oneofInt32 = 0; + break; + case Message3_O_OneOfCase_OneofInt64: + msg.oneofInt64 = 0; + break; + case Message3_O_OneOfCase_OneofUint32: + msg.oneofUint32 = 0; + break; + case Message3_O_OneOfCase_OneofUint64: + msg.oneofUint64 = 0; + break; + case Message3_O_OneOfCase_OneofSint32: + msg.oneofSint32 = 0; + break; + case Message3_O_OneOfCase_OneofSint64: + msg.oneofSint64 = 0; + break; + case Message3_O_OneOfCase_OneofFixed32: + msg.oneofFixed32 = 0; + break; + case Message3_O_OneOfCase_OneofFixed64: + msg.oneofFixed64 = 0; + break; + case Message3_O_OneOfCase_OneofSfixed32: + msg.oneofSfixed32 = 0; + break; + case Message3_O_OneOfCase_OneofSfixed64: + msg.oneofSfixed64 = 0; + break; + case Message3_O_OneOfCase_OneofFloat: + msg.oneofFloat = 0.0f; + break; + case Message3_O_OneOfCase_OneofDouble: + msg.oneofDouble = 0.0; + break; + case Message3_O_OneOfCase_OneofBool: + msg.oneofBool = NO; + break; + case Message3_O_OneOfCase_OneofString: + msg.oneofString = oneofStringDefault; + break; + case Message3_O_OneOfCase_OneofBytes: + msg.oneofBytes = oneofBytesDefault; + break; + case Message3_O_OneOfCase_OneofMessage: + msg.oneofMessage.optionalInt32 = 0; + break; + case Message3_O_OneOfCase_OneofEnum: + msg.oneofEnum = Message3_Enum_Foo; + break; + default: + XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]); + break; + } + + // Should be set to the correct case. + XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i); + + // Confirm everything is still zeros. + XCTAssertEqual(msg.oneofInt32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofInt64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint32, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofUint64, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSint64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed32, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFixed64, 0U, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed32, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofSfixed64, 0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofFloat, 0.0f, "Loop: %zd", i); + XCTAssertEqual(msg.oneofDouble, 0.0, "Loop: %zd", i); + XCTAssertEqual(msg.oneofBool, NO, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i); + XCTAssertNotNil(msg.oneofMessage, "Loop: %zd", i); + XCTAssertEqual(msg.oneofEnum, Message3_Enum_Foo, "Loop: %zd", i); + } + + // We special case nil on string, data, message, ensure they work as expected. + msg.oneofString = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofString, oneofStringDefault); + msg.oneofBytes = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault); + msg.oneofMessage = nil; + XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase); + XCTAssertNotNil(msg.oneofMessage); + + [msg release]; +} + - (void)testCopyingMakesUniqueObjects { const int repeatCount = 5; TestAllTypes *msg1 = [TestAllTypes message]; diff --git a/objectivec/Tests/unittest_objc.proto b/objectivec/Tests/unittest_objc.proto index 914945eb..e5577faf 100644 --- a/objectivec/Tests/unittest_objc.proto +++ b/objectivec/Tests/unittest_objc.proto @@ -34,6 +34,15 @@ import "google/protobuf/unittest.proto"; package protobuf_unittest; +// Used to check that Headerdocs and appledoc work correctly. If these comments +// are not handled correctly, Xcode will fail to build the tests. +message TestGeneratedComments { + // This is a string that could contain stuff like + // mime types as image/* or */plain. Maybe twitter usernames + // like @protobuf, @google or @something. + optional string string_field = 1; +} + // Using the messages in unittest.proto, setup for recursive cases for testing // extensions at various depths. extend TestAllExtensions { diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h index 4253b604..842052fe 100644 --- a/objectivec/google/protobuf/Any.pbobjc.h +++ b/objectivec/google/protobuf/Any.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBAnyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBAnyRoot : GPBRootObject @end @@ -46,101 +48,105 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { GPBAny_FieldNumber_Value = 2, }; -/// `Any` contains an arbitrary serialized protocol buffer message along with a -/// URL that describes the type of the serialized message. -/// -/// Protobuf library provides support to pack/unpack Any values in the form -/// of utility functions or additional generated methods of the Any type. -/// -/// Example 1: Pack and unpack a message in C++. -/// -/// Foo foo = ...; -/// Any any; -/// any.PackFrom(foo); -/// ... -/// if (any.UnpackTo(&foo)) { -/// ... -/// } -/// -/// Example 2: Pack and unpack a message in Java. -/// -/// Foo foo = ...; -/// Any any = Any.pack(foo); -/// ... -/// if (any.is(Foo.class)) { -/// foo = any.unpack(Foo.class); -/// } -/// -/// Example 3: Pack and unpack a message in Python. -/// -/// foo = Foo(...) -/// any = Any() -/// any.Pack(foo) -/// ... -/// if any.Is(Foo.DESCRIPTOR): -/// any.Unpack(foo) -/// ... -/// -/// The pack methods provided by protobuf library will by default use -/// 'type.googleapis.com/full.type.name' as the type URL and the unpack -/// methods only use the fully qualified type name after the last '/' -/// in the type URL, for example "foo.bar.com/x/y.z" will yield type -/// name "y.z". -/// -/// -/// JSON -/// ==== -/// The JSON representation of an `Any` value uses the regular -/// representation of the deserialized, embedded message, with an -/// additional field `\@type` which contains the type URL. Example: -/// -/// package google.profile; -/// message Person { -/// string first_name = 1; -/// string last_name = 2; -/// } -/// -/// { -/// "\@type": "type.googleapis.com/google.profile.Person", -/// "firstName": <string>, -/// "lastName": <string> -/// } -/// -/// If the embedded message type is well-known and has a custom JSON -/// representation, that representation will be embedded adding a field -/// `value` which holds the custom JSON in addition to the `\@type` -/// field. Example (for message [google.protobuf.Duration][]): -/// -/// { -/// "\@type": "type.googleapis.com/google.protobuf.Duration", -/// "value": "1.212s" -/// } +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * JSON + * ==== + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `\@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "\@type": "type.googleapis.com/google.profile.Person", + * "firstName": <string>, + * "lastName": <string> + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `\@type` + * field. Example (for message [google.protobuf.Duration][]): + * + * { + * "\@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + **/ @interface GPBAny : GPBMessage -/// A URL/resource name whose content describes the type of the -/// serialized protocol buffer message. -/// -/// For URLs which use the scheme `http`, `https`, or no scheme, the -/// following restrictions and interpretations apply: -/// -/// * If no scheme is provided, `https` is assumed. -/// * The last segment of the URL's path must represent the fully -/// qualified name of the type (as in `path/google.protobuf.Duration`). -/// The name should be in a canonical form (e.g., leading "." is -/// not accepted). -/// * An HTTP GET on the URL must yield a [google.protobuf.Type][] -/// value in binary format, or produce an error. -/// * Applications are allowed to cache lookup results based on the -/// URL, or have them precompiled into a binary to avoid any -/// lookup. Therefore, binary compatibility needs to be preserved -/// on changes to types. (Use versioned type names to manage -/// breaking changes.) -/// -/// Schemes other than `http`, `https` (or the empty scheme) might be -/// used with implementation specific semantics. +/** + * A URL/resource name whose content describes the type of the + * serialized protocol buffer message. + * + * For URLs which use the scheme `http`, `https`, or no scheme, the + * following restrictions and interpretations apply: + * + * * If no scheme is provided, `https` is assumed. + * * The last segment of the URL's path must represent the fully + * qualified name of the type (as in `path/google.protobuf.Duration`). + * The name should be in a canonical form (e.g., leading "." is + * not accepted). + * * An HTTP GET on the URL must yield a [google.protobuf.Type][] + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// Must be a valid serialized protocol buffer of the above specified type. +/** Must be a valid serialized protocol buffer of the above specified type. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/objectivec/google/protobuf/Api.pbobjc.h b/objectivec/google/protobuf/Api.pbobjc.h index 04341f47..182e866c 100644 --- a/objectivec/google/protobuf/Api.pbobjc.h +++ b/objectivec/google/protobuf/Api.pbobjc.h @@ -34,14 +34,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBApiRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBApiRoot : GPBRootObject @end @@ -57,67 +59,79 @@ typedef GPB_ENUM(GPBApi_FieldNumber) { GPBApi_FieldNumber_Syntax = 7, }; -/// Api is a light-weight descriptor for a protocol buffer service. +/** + * Api is a light-weight descriptor for a protocol buffer service. + **/ @interface GPBApi : GPBMessage -/// The fully qualified name of this api, including package name -/// followed by the api's simple name. +/** + * The fully qualified name of this api, including package name + * followed by the api's simple name. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The methods of this api, in unspecified order. +/** The methods of this api, in unspecified order. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMethod*> *methodsArray; -/// The number of items in @c methodsArray without causing the array to be created. +/** The number of items in @c methodsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger methodsArray_Count; -/// Any metadata attached to the API. +/** Any metadata attached to the API. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// A version string for this api. If specified, must have the form -/// `major-version.minor-version`, as in `1.10`. If the minor version -/// is omitted, it defaults to zero. If the entire version field is -/// empty, the major version is derived from the package name, as -/// outlined below. If the field is not empty, the version in the -/// package name will be verified to be consistent with what is -/// provided here. -/// -/// The versioning schema uses [semantic -/// versioning](http://semver.org) where the major version number -/// indicates a breaking change and the minor version an additive, -/// non-breaking change. Both version numbers are signals to users -/// what to expect from different versions, and should be carefully -/// chosen based on the product plan. -/// -/// The major version is also reflected in the package name of the -/// API, which must end in `v<major-version>`, as in -/// `google.feature.v1`. For major versions 0 and 1, the suffix can -/// be omitted. Zero major versions must only be used for -/// experimental, none-GA apis. +/** + * A version string for this api. If specified, must have the form + * `major-version.minor-version`, as in `1.10`. If the minor version + * is omitted, it defaults to zero. If the entire version field is + * empty, the major version is derived from the package name, as + * outlined below. If the field is not empty, the version in the + * package name will be verified to be consistent with what is + * provided here. + * + * The versioning schema uses [semantic + * versioning](http://semver.org) where the major version number + * indicates a breaking change and the minor version an additive, + * non-breaking change. Both version numbers are signals to users + * what to expect from different versions, and should be carefully + * chosen based on the product plan. + * + * The major version is also reflected in the package name of the + * API, which must end in `v<major-version>`, as in + * `google.feature.v1`. For major versions 0 and 1, the suffix can + * be omitted. Zero major versions must only be used for + * experimental, none-GA apis. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *version; -/// Source context for the protocol buffer service represented by this -/// message. +/** + * Source context for the protocol buffer service represented by this + * message. + **/ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// Included APIs. See [Mixin][]. +/** Included APIs. See [Mixin][]. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMixin*> *mixinsArray; -/// The number of items in @c mixinsArray without causing the array to be created. +/** The number of items in @c mixinsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger mixinsArray_Count; -/// The source syntax of the service. +/** The source syntax of the service. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBApi's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBApi's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBApi_Syntax_RawValue(GPBApi *message); -/// Sets the raw value of an @c GPBApi's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBApi's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBApi_Syntax_RawValue(GPBApi *message, int32_t value); #pragma mark - GPBMethod @@ -132,40 +146,46 @@ typedef GPB_ENUM(GPBMethod_FieldNumber) { GPBMethod_FieldNumber_Syntax = 7, }; -/// Method represents a method of an api. +/** + * Method represents a method of an api. + **/ @interface GPBMethod : GPBMessage -/// The simple name of this method. +/** The simple name of this method. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// A URL of the input message type. +/** A URL of the input message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *requestTypeURL; -/// If true, the request is streamed. +/** If true, the request is streamed. */ @property(nonatomic, readwrite) BOOL requestStreaming; -/// The URL of the output message type. +/** The URL of the output message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *responseTypeURL; -/// If true, the response is streamed. +/** If true, the response is streamed. */ @property(nonatomic, readwrite) BOOL responseStreaming; -/// Any metadata attached to the method. +/** Any metadata attached to the method. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source syntax of this method. +/** The source syntax of this method. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBMethod's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBMethod's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBMethod_Syntax_RawValue(GPBMethod *message); -/// Sets the raw value of an @c GPBMethod's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBMethod's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBMethod_Syntax_RawValue(GPBMethod *message, int32_t value); #pragma mark - GPBMixin @@ -175,90 +195,94 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) { GPBMixin_FieldNumber_Root = 2, }; -/// Declares an API to be included in this API. The including API must -/// redeclare all the methods from the included API, but documentation -/// and options are inherited as follows: -/// -/// - If after comment and whitespace stripping, the documentation -/// string of the redeclared method is empty, it will be inherited -/// from the original method. -/// -/// - Each annotation belonging to the service config (http, -/// visibility) which is not set in the redeclared method will be -/// inherited. -/// -/// - If an http annotation is inherited, the path pattern will be -/// modified as follows. Any version prefix will be replaced by the -/// version of the including API plus the [root][] path if specified. -/// -/// Example of a simple mixin: -/// -/// package google.acl.v1; -/// service AccessControl { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v1/{resource=**}:getAcl"; -/// } -/// } -/// -/// package google.storage.v2; -/// service Storage { -/// rpc GetAcl(GetAclRequest) returns (Acl); -/// -/// // Get a data record. -/// rpc GetData(GetDataRequest) returns (Data) { -/// option (google.api.http).get = "/v2/{resource=**}"; -/// } -/// } -/// -/// Example of a mixin configuration: -/// -/// apis: -/// - name: google.storage.v2.Storage -/// mixins: -/// - name: google.acl.v1.AccessControl -/// -/// The mixin construct implies that all methods in `AccessControl` are -/// also declared with same name and request/response types in -/// `Storage`. A documentation generator or annotation processor will -/// see the effective `Storage.GetAcl` method after inherting -/// documentation and annotations as follows: -/// -/// service Storage { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v2/{resource=**}:getAcl"; -/// } -/// ... -/// } -/// -/// Note how the version in the path pattern changed from `v1` to `v2`. -/// -/// If the `root` field in the mixin is specified, it should be a -/// relative path under which inherited HTTP paths are placed. Example: -/// -/// apis: -/// - name: google.storage.v2.Storage -/// mixins: -/// - name: google.acl.v1.AccessControl -/// root: acls -/// -/// This implies the following inherited HTTP annotation: -/// -/// service Storage { -/// // Get the underlying ACL object. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; -/// } -/// ... -/// } +/** + * Declares an API to be included in this API. The including API must + * redeclare all the methods from the included API, but documentation + * and options are inherited as follows: + * + * - If after comment and whitespace stripping, the documentation + * string of the redeclared method is empty, it will be inherited + * from the original method. + * + * - Each annotation belonging to the service config (http, + * visibility) which is not set in the redeclared method will be + * inherited. + * + * - If an http annotation is inherited, the path pattern will be + * modified as follows. Any version prefix will be replaced by the + * version of the including API plus the [root][] path if specified. + * + * Example of a simple mixin: + * + * package google.acl.v1; + * service AccessControl { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v1/{resource=**}:getAcl"; + * } + * } + * + * package google.storage.v2; + * service Storage { + * rpc GetAcl(GetAclRequest) returns (Acl); + * + * // Get a data record. + * rpc GetData(GetDataRequest) returns (Data) { + * option (google.api.http).get = "/v2/{resource=**}"; + * } + * } + * + * Example of a mixin configuration: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * + * The mixin construct implies that all methods in `AccessControl` are + * also declared with same name and request/response types in + * `Storage`. A documentation generator or annotation processor will + * see the effective `Storage.GetAcl` method after inherting + * documentation and annotations as follows: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/{resource=**}:getAcl"; + * } + * ... + * } + * + * Note how the version in the path pattern changed from `v1` to `v2`. + * + * If the `root` field in the mixin is specified, it should be a + * relative path under which inherited HTTP paths are placed. Example: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * root: acls + * + * This implies the following inherited HTTP annotation: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; + * } + * ... + * } + **/ @interface GPBMixin : GPBMessage -/// The fully qualified name of the API which is included. +/** The fully qualified name of the API which is included. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// If non-empty specifies a path under which inherited HTTP paths -/// are rooted. +/** + * If non-empty specifies a path under which inherited HTTP paths + * are rooted. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *root; @end diff --git a/objectivec/google/protobuf/Duration.pbobjc.h b/objectivec/google/protobuf/Duration.pbobjc.h index 4c3173d3..fa91e223 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.h +++ b/objectivec/google/protobuf/Duration.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBDurationRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBDurationRoot : GPBRootObject @end @@ -46,58 +48,64 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) { GPBDuration_FieldNumber_Nanos = 2, }; -/// A Duration represents a signed, fixed-length span of time represented -/// as a count of seconds and fractions of seconds at nanosecond -/// resolution. It is independent of any calendar and concepts like "day" -/// or "month". It is related to Timestamp in that the difference between -/// two Timestamp values is a Duration and it can be added or subtracted -/// from a Timestamp. Range is approximately +-10,000 years. -/// -/// Example 1: Compute Duration from two Timestamps in pseudo code. -/// -/// Timestamp start = ...; -/// Timestamp end = ...; -/// Duration duration = ...; -/// -/// duration.seconds = end.seconds - start.seconds; -/// duration.nanos = end.nanos - start.nanos; -/// -/// if (duration.seconds < 0 && duration.nanos > 0) { -/// duration.seconds += 1; -/// duration.nanos -= 1000000000; -/// } else if (durations.seconds > 0 && duration.nanos < 0) { -/// duration.seconds -= 1; -/// duration.nanos += 1000000000; -/// } -/// -/// Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. -/// -/// Timestamp start = ...; -/// Duration duration = ...; -/// Timestamp end = ...; -/// -/// end.seconds = start.seconds + duration.seconds; -/// end.nanos = start.nanos + duration.nanos; -/// -/// if (end.nanos < 0) { -/// end.seconds -= 1; -/// end.nanos += 1000000000; -/// } else if (end.nanos >= 1000000000) { -/// end.seconds += 1; -/// end.nanos -= 1000000000; -/// } +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + **/ @interface GPBDuration : GPBMessage -/// Signed seconds of the span of time. Must be from -315,576,000,000 -/// to +315,576,000,000 inclusive. +/** + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Signed fractions of a second at nanosecond resolution of the span -/// of time. Durations less than one second are represented with a 0 -/// `seconds` field and a positive or negative `nanos` field. For durations -/// of one second or more, a non-zero value for the `nanos` field must be -/// of the same sign as the `seconds` field. Must be from -999,999,999 -/// to +999,999,999 inclusive. +/** + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Empty.pbobjc.h b/objectivec/google/protobuf/Empty.pbobjc.h index 2d2a86bc..4d36174d 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.h +++ b/objectivec/google/protobuf/Empty.pbobjc.h @@ -28,28 +28,32 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBEmptyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBEmptyRoot : GPBRootObject @end #pragma mark - GPBEmpty -/// A generic empty message that you can re-use to avoid defining duplicated -/// empty messages in your APIs. A typical example is to use it as the request -/// or the response type of an API method. For instance: -/// -/// service Foo { -/// rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); -/// } -/// -/// The JSON representation for `Empty` is empty JSON object `{}`. +/** + * A generic empty message that you can re-use to avoid defining duplicated + * empty messages in your APIs. A typical example is to use it as the request + * or the response type of an API method. For instance: + * + * service Foo { + * rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); + * } + * + * The JSON representation for `Empty` is empty JSON object `{}`. + **/ @interface GPBEmpty : GPBMessage @end diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.h b/objectivec/google/protobuf/FieldMask.pbobjc.h index 06053f1a..491463f9 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBFieldMaskRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBFieldMaskRoot : GPBRootObject @end @@ -45,212 +47,214 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { GPBFieldMask_FieldNumber_PathsArray = 1, }; -/// `FieldMask` represents a set of symbolic field paths, for example: -/// -/// paths: "f.a" -/// paths: "f.b.d" -/// -/// Here `f` represents a field in some root message, `a` and `b` -/// fields in the message found in `f`, and `d` a field found in the -/// message in `f.b`. -/// -/// Field masks are used to specify a subset of fields that should be -/// returned by a get operation or modified by an update operation. -/// Field masks also have a custom JSON encoding (see below). -/// -/// # Field Masks in Projections -/// -/// When used in the context of a projection, a response message or -/// sub-message is filtered by the API to only contain those fields as -/// specified in the mask. For example, if the mask in the previous -/// example is applied to a response message as follows: -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// x : 2 -/// } -/// y : 13 -/// } -/// z: 8 -/// -/// The result will not contain specific values for fields x,y and z -/// (their value will be set to the default, and omitted in proto text -/// output): -/// -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// } -/// } -/// -/// A repeated field is not allowed except at the last position of a -/// field mask. -/// -/// If a FieldMask object is not present in a get operation, the -/// operation applies to all fields (as if a FieldMask of all fields -/// had been specified). -/// -/// Note that a field mask does not necessarily apply to the -/// top-level response message. In case of a REST get operation, the -/// field mask applies directly to the response, but in case of a REST -/// list operation, the mask instead applies to each individual message -/// in the returned resource list. In case of a REST custom method, -/// other definitions may be used. Where the mask applies will be -/// clearly documented together with its declaration in the API. In -/// any case, the effect on the returned resource/resources is required -/// behavior for APIs. -/// -/// # Field Masks in Update Operations -/// -/// A field mask in update operations specifies which fields of the -/// targeted resource are going to be updated. The API is required -/// to only change the values of the fields as specified in the mask -/// and leave the others untouched. If a resource is passed in to -/// describe the updated values, the API ignores the values of all -/// fields not covered by the mask. -/// -/// If a repeated field is specified for an update operation, the existing -/// repeated values in the target resource will be overwritten by the new values. -/// Note that a repeated field is only allowed in the last position of a field -/// mask. -/// -/// If a sub-message is specified in the last position of the field mask for an -/// update operation, then the existing sub-message in the target resource is -/// overwritten. Given the target message: -/// -/// f { -/// b { -/// d : 1 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// And an update message: -/// -/// f { -/// b { -/// d : 10 -/// } -/// } -/// -/// then if the field mask is: -/// -/// paths: "f.b" -/// -/// then the result will be: -/// -/// f { -/// b { -/// d : 10 -/// } -/// c : 1 -/// } -/// -/// However, if the update mask was: -/// -/// paths: "f.b.d" -/// -/// then the result would be: -/// -/// f { -/// b { -/// d : 10 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// In order to reset a field's value to the default, the field must -/// be in the mask and set to the default value in the provided resource. -/// Hence, in order to reset all fields of a resource, provide a default -/// instance of the resource and set all fields in the mask, or do -/// not provide a mask as described below. -/// -/// If a field mask is not present on update, the operation applies to -/// all fields (as if a field mask of all fields has been specified). -/// Note that in the presence of schema evolution, this may mean that -/// fields the client does not know and has therefore not filled into -/// the request will be reset to their default. If this is unwanted -/// behavior, a specific service may require a client to always specify -/// a field mask, producing an error if not. -/// -/// As with get operations, the location of the resource which -/// describes the updated values in the request message depends on the -/// operation kind. In any case, the effect of the field mask is -/// required to be honored by the API. -/// -/// ## Considerations for HTTP REST -/// -/// The HTTP kind of an update operation which uses a field mask must -/// be set to PATCH instead of PUT in order to satisfy HTTP semantics -/// (PUT must only be used for full updates). -/// -/// # JSON Encoding of Field Masks -/// -/// In JSON, a field mask is encoded as a single string where paths are -/// separated by a comma. Fields name in each path are converted -/// to/from lower-camel naming conventions. -/// -/// As an example, consider the following message declarations: -/// -/// message Profile { -/// User user = 1; -/// Photo photo = 2; -/// } -/// message User { -/// string display_name = 1; -/// string address = 2; -/// } -/// -/// In proto a field mask for `Profile` may look as such: -/// -/// mask { -/// paths: "user.display_name" -/// paths: "photo" -/// } -/// -/// In JSON, the same mask is represented as below: -/// -/// { -/// mask: "user.displayName,photo" -/// } -/// -/// # Field Masks and Oneof Fields -/// -/// Field masks treat fields in oneofs just as regular fields. Consider the -/// following message: -/// -/// message SampleMessage { -/// oneof test_oneof { -/// string name = 4; -/// SubMessage sub_message = 9; -/// } -/// } -/// -/// The field mask can be: -/// -/// mask { -/// paths: "name" -/// } -/// -/// Or: -/// -/// mask { -/// paths: "sub_message" -/// } -/// -/// Note that oneof type names ("test_oneof" in this case) cannot be used in -/// paths. +/** + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * field mask. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, the existing + * repeated values in the target resource will be overwritten by the new values. + * Note that a repeated field is only allowed in the last position of a field + * mask. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then the existing sub-message in the target resource is + * overwritten. Given the target message: + * + * f { + * b { + * d : 1 + * x : 2 + * } + * c : 1 + * } + * + * And an update message: + * + * f { + * b { + * d : 10 + * } + * } + * + * then if the field mask is: + * + * paths: "f.b" + * + * then the result will be: + * + * f { + * b { + * d : 10 + * } + * c : 1 + * } + * + * However, if the update mask was: + * + * paths: "f.b.d" + * + * then the result would be: + * + * f { + * b { + * d : 10 + * x : 2 + * } + * c : 1 + * } + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + **/ @interface GPBFieldMask : GPBMessage -/// The set of field mask paths. +/** The set of field mask paths. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *pathsArray; -/// The number of items in @c pathsArray without causing the array to be created. +/** The number of items in @c pathsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger pathsArray_Count; @end diff --git a/objectivec/google/protobuf/SourceContext.pbobjc.h b/objectivec/google/protobuf/SourceContext.pbobjc.h index 4514fa9f..d9450057 100644 --- a/objectivec/google/protobuf/SourceContext.pbobjc.h +++ b/objectivec/google/protobuf/SourceContext.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBSourceContextRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBSourceContextRoot : GPBRootObject @end @@ -45,12 +47,16 @@ typedef GPB_ENUM(GPBSourceContext_FieldNumber) { GPBSourceContext_FieldNumber_FileName = 1, }; -/// `SourceContext` represents information about the source of a -/// protobuf element, like the file in which it is defined. +/** + * `SourceContext` represents information about the source of a + * protobuf element, like the file in which it is defined. + **/ @interface GPBSourceContext : GPBMessage -/// The path-qualified name of the .proto file that contained the associated -/// protobuf element. For example: `"google/protobuf/source_context.proto"`. +/** + * The path-qualified name of the .proto file that contained the associated + * protobuf element. For example: `"google/protobuf/source_context.proto"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *fileName; @end diff --git a/objectivec/google/protobuf/Struct.pbobjc.h b/objectivec/google/protobuf/Struct.pbobjc.h index 3e2d55fd..a5b31cd0 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.h +++ b/objectivec/google/protobuf/Struct.pbobjc.h @@ -32,35 +32,43 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBNullValue -/// `NullValue` is a singleton enumeration to represent the null value for the -/// `Value` type union. -/// -/// The JSON representation for `NullValue` is JSON `null`. +/** + * `NullValue` is a singleton enumeration to represent the null value for the + * `Value` type union. + * + * The JSON representation for `NullValue` is JSON `null`. + **/ typedef GPB_ENUM(GPBNullValue) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBNullValue_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Null value. + /** Null value. */ GPBNullValue_NullValue = 0, }; GPBEnumDescriptor *GPBNullValue_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBNullValue_IsValidValue(int32_t value); #pragma mark - GPBStructRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBStructRoot : GPBRootObject @end @@ -70,19 +78,21 @@ typedef GPB_ENUM(GPBStruct_FieldNumber) { GPBStruct_FieldNumber_Fields = 1, }; -/// `Struct` represents a structured data value, consisting of fields -/// which map to dynamically typed values. In some languages, `Struct` -/// might be supported by a native representation. For example, in -/// scripting languages like JS a struct is represented as an -/// object. The details of that representation are described together -/// with the proto support for the language. -/// -/// The JSON representation for `Struct` is JSON object. +/** + * `Struct` represents a structured data value, consisting of fields + * which map to dynamically typed values. In some languages, `Struct` + * might be supported by a native representation. For example, in + * scripting languages like JS a struct is represented as an + * object. The details of that representation are described together + * with the proto support for the language. + * + * The JSON representation for `Struct` is JSON object. + **/ @interface GPBStruct : GPBMessage -/// Unordered map of dynamically typed values. +/** Unordered map of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableDictionary<NSString*, GPBValue*> *fields; -/// The number of items in @c fields without causing the array to be created. +/** The number of items in @c fields without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fields_Count; @end @@ -108,46 +118,54 @@ typedef GPB_ENUM(GPBValue_Kind_OneOfCase) { GPBValue_Kind_OneOfCase_ListValue = 6, }; -/// `Value` represents a dynamically typed value which can be either -/// null, a number, a string, a boolean, a recursive struct value, or a -/// list of values. A producer of value is expected to set one of that -/// variants, absence of any variant indicates an error. -/// -/// The JSON representation for `Value` is JSON value. +/** + * `Value` represents a dynamically typed value which can be either + * null, a number, a string, a boolean, a recursive struct value, or a + * list of values. A producer of value is expected to set one of that + * variants, absence of any variant indicates an error. + * + * The JSON representation for `Value` is JSON value. + **/ @interface GPBValue : GPBMessage -/// The kind of value. +/** The kind of value. */ @property(nonatomic, readonly) GPBValue_Kind_OneOfCase kindOneOfCase; -/// Represents a null value. +/** Represents a null value. */ @property(nonatomic, readwrite) GPBNullValue nullValue; -/// Represents a double value. +/** Represents a double value. */ @property(nonatomic, readwrite) double numberValue; -/// Represents a string value. +/** Represents a string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *stringValue; -/// Represents a boolean value. +/** Represents a boolean value. */ @property(nonatomic, readwrite) BOOL boolValue; -/// Represents a structured value. +/** Represents a structured value. */ @property(nonatomic, readwrite, strong, null_resettable) GPBStruct *structValue; -/// Represents a repeated `Value`. +/** Represents a repeated `Value`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBListValue *listValue; @end -/// Fetches the raw value of a @c GPBValue's @c nullValue property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBValue's @c nullValue property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBValue_NullValue_RawValue(GPBValue *message); -/// Sets the raw value of an @c GPBValue's @c nullValue property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBValue's @c nullValue property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value); -/// Clears whatever value was set for the oneof 'kind'. +/** + * Clears whatever value was set for the oneof 'kind'. + **/ void GPBValue_ClearKindOneOfCase(GPBValue *message); #pragma mark - GPBListValue @@ -156,14 +174,16 @@ typedef GPB_ENUM(GPBListValue_FieldNumber) { GPBListValue_FieldNumber_ValuesArray = 1, }; -/// `ListValue` is a wrapper around a repeated field of values. -/// -/// The JSON representation for `ListValue` is JSON array. +/** + * `ListValue` is a wrapper around a repeated field of values. + * + * The JSON representation for `ListValue` is JSON array. + **/ @interface GPBListValue : GPBMessage -/// Repeated field of dynamically typed values. +/** Repeated field of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBValue*> *valuesArray; -/// The number of items in @c valuesArray without causing the array to be created. +/** The number of items in @c valuesArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger valuesArray_Count; @end diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.h b/objectivec/google/protobuf/Timestamp.pbobjc.h index d15de7c7..ebfa670f 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.h +++ b/objectivec/google/protobuf/Timestamp.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBTimestampRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTimestampRoot : GPBRootObject @end @@ -46,70 +48,76 @@ typedef GPB_ENUM(GPBTimestamp_FieldNumber) { GPBTimestamp_FieldNumber_Nanos = 2, }; -/// A Timestamp represents a point in time independent of any time zone -/// or calendar, represented as seconds and fractions of seconds at -/// nanosecond resolution in UTC Epoch time. It is encoded using the -/// Proleptic Gregorian Calendar which extends the Gregorian calendar -/// backwards to year one. It is encoded assuming all minutes are 60 -/// seconds long, i.e. leap seconds are "smeared" so that no leap second -/// table is needed for interpretation. Range is from -/// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. -/// By restricting to that range, we ensure that we can convert to -/// and from RFC 3339 date strings. -/// See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). -/// -/// Example 1: Compute Timestamp from POSIX `time()`. -/// -/// Timestamp timestamp; -/// timestamp.set_seconds(time(NULL)); -/// timestamp.set_nanos(0); -/// -/// Example 2: Compute Timestamp from POSIX `gettimeofday()`. -/// -/// struct timeval tv; -/// gettimeofday(&tv, NULL); -/// -/// Timestamp timestamp; -/// timestamp.set_seconds(tv.tv_sec); -/// timestamp.set_nanos(tv.tv_usec * 1000); -/// -/// Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. -/// -/// FILETIME ft; -/// GetSystemTimeAsFileTime(&ft); -/// UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; -/// -/// // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z -/// // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. -/// Timestamp timestamp; -/// timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); -/// timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); -/// -/// Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. -/// -/// long millis = System.currentTimeMillis(); -/// -/// Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) -/// .setNanos((int) ((millis % 1000) * 1000000)).build(); -/// -/// -/// Example 5: Compute Timestamp from current time in Python. -/// -/// now = time.time() -/// seconds = int(now) -/// nanos = int((now - seconds) * 10**9) -/// timestamp = Timestamp(seconds=seconds, nanos=nanos) +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * now = time.time() + * seconds = int(now) + * nanos = int((now - seconds) * 10**9) + * timestamp = Timestamp(seconds=seconds, nanos=nanos) + **/ @interface GPBTimestamp : GPBMessage -/// Represents seconds of UTC time since Unix epoch -/// 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to -/// 9999-12-31T23:59:59Z inclusive. +/** + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Non-negative fractions of a second at nanosecond resolution. Negative -/// second values with fractions must still have non-negative nanos values -/// that count forward in time. Must be from 0 to 999,999,999 -/// inclusive. +/** + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Type.pbobjc.h b/objectivec/google/protobuf/Type.pbobjc.h index 93ee3cec..05411958 100644 --- a/objectivec/google/protobuf/Type.pbobjc.h +++ b/objectivec/google/protobuf/Type.pbobjc.h @@ -34,134 +34,148 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBSyntax -/// The syntax in which a protocol buffer element is defined. +/** The syntax in which a protocol buffer element is defined. */ typedef GPB_ENUM(GPBSyntax) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBSyntax_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Syntax `proto2`. + /** Syntax `proto2`. */ GPBSyntax_SyntaxProto2 = 0, - /// Syntax `proto3`. + /** Syntax `proto3`. */ GPBSyntax_SyntaxProto3 = 1, }; GPBEnumDescriptor *GPBSyntax_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBSyntax_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Kind -/// Basic field types. +/** Basic field types. */ typedef GPB_ENUM(GPBField_Kind) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Kind_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Field type unknown. + /** Field type unknown. */ GPBField_Kind_TypeUnknown = 0, - /// Field type double. + /** Field type double. */ GPBField_Kind_TypeDouble = 1, - /// Field type float. + /** Field type float. */ GPBField_Kind_TypeFloat = 2, - /// Field type int64. + /** Field type int64. */ GPBField_Kind_TypeInt64 = 3, - /// Field type uint64. + /** Field type uint64. */ GPBField_Kind_TypeUint64 = 4, - /// Field type int32. + /** Field type int32. */ GPBField_Kind_TypeInt32 = 5, - /// Field type fixed64. + /** Field type fixed64. */ GPBField_Kind_TypeFixed64 = 6, - /// Field type fixed32. + /** Field type fixed32. */ GPBField_Kind_TypeFixed32 = 7, - /// Field type bool. + /** Field type bool. */ GPBField_Kind_TypeBool = 8, - /// Field type string. + /** Field type string. */ GPBField_Kind_TypeString = 9, - /// Field type group. Proto2 syntax only, and deprecated. + /** Field type group. Proto2 syntax only, and deprecated. */ GPBField_Kind_TypeGroup = 10, - /// Field type message. + /** Field type message. */ GPBField_Kind_TypeMessage = 11, - /// Field type bytes. + /** Field type bytes. */ GPBField_Kind_TypeBytes = 12, - /// Field type uint32. + /** Field type uint32. */ GPBField_Kind_TypeUint32 = 13, - /// Field type enum. + /** Field type enum. */ GPBField_Kind_TypeEnum = 14, - /// Field type sfixed32. + /** Field type sfixed32. */ GPBField_Kind_TypeSfixed32 = 15, - /// Field type sfixed64. + /** Field type sfixed64. */ GPBField_Kind_TypeSfixed64 = 16, - /// Field type sint32. + /** Field type sint32. */ GPBField_Kind_TypeSint32 = 17, - /// Field type sint64. + /** Field type sint64. */ GPBField_Kind_TypeSint64 = 18, }; GPBEnumDescriptor *GPBField_Kind_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Kind_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Cardinality -/// Whether a field is optional, required, or repeated. +/** Whether a field is optional, required, or repeated. */ typedef GPB_ENUM(GPBField_Cardinality) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Cardinality_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// For fields with unknown cardinality. + /** For fields with unknown cardinality. */ GPBField_Cardinality_CardinalityUnknown = 0, - /// For optional fields. + /** For optional fields. */ GPBField_Cardinality_CardinalityOptional = 1, - /// For required fields. Proto2 syntax only. + /** For required fields. Proto2 syntax only. */ GPBField_Cardinality_CardinalityRequired = 2, - /// For repeated fields. + /** For repeated fields. */ GPBField_Cardinality_CardinalityRepeated = 3, }; GPBEnumDescriptor *GPBField_Cardinality_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Cardinality_IsValidValue(int32_t value); #pragma mark - GPBTypeRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTypeRoot : GPBRootObject @end @@ -176,43 +190,49 @@ typedef GPB_ENUM(GPBType_FieldNumber) { GPBType_FieldNumber_Syntax = 6, }; -/// A protocol buffer message type. +/** + * A protocol buffer message type. + **/ @interface GPBType : GPBMessage -/// The fully qualified message name. +/** The fully qualified message name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The list of fields. +/** The list of fields. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBField*> *fieldsArray; -/// The number of items in @c fieldsArray without causing the array to be created. +/** The number of items in @c fieldsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fieldsArray_Count; -/// The list of types appearing in `oneof` definitions in this type. +/** The list of types appearing in `oneof` definitions in this type. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *oneofsArray; -/// The number of items in @c oneofsArray without causing the array to be created. +/** The number of items in @c oneofsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger oneofsArray_Count; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBType's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBType's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBType_Syntax_RawValue(GPBType *message); -/// Sets the raw value of an @c GPBType's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBType's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBType_Syntax_RawValue(GPBType *message, int32_t value); #pragma mark - GPBField @@ -230,59 +250,73 @@ typedef GPB_ENUM(GPBField_FieldNumber) { GPBField_FieldNumber_DefaultValue = 11, }; -/// A single field of a message type. +/** + * A single field of a message type. + **/ @interface GPBField : GPBMessage -/// The field type. +/** The field type. */ @property(nonatomic, readwrite) GPBField_Kind kind; -/// The field cardinality. +/** The field cardinality. */ @property(nonatomic, readwrite) GPBField_Cardinality cardinality; -/// The field number. +/** The field number. */ @property(nonatomic, readwrite) int32_t number; -/// The field name. +/** The field name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The field type URL, without the scheme, for message or enumeration -/// types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. +/** + * The field type URL, without the scheme, for message or enumeration + * types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// The index of the field type in `Type.oneofs`, for message or enumeration -/// types. The first type has index 1; zero means the type is not in the list. +/** + * The index of the field type in `Type.oneofs`, for message or enumeration + * types. The first type has index 1; zero means the type is not in the list. + **/ @property(nonatomic, readwrite) int32_t oneofIndex; -/// Whether to use alternative packed wire representation. +/** Whether to use alternative packed wire representation. */ @property(nonatomic, readwrite) BOOL packed; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The field JSON name. +/** The field JSON name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *jsonName; -/// The string value of the default value of this field. Proto2 syntax only. +/** The string value of the default value of this field. Proto2 syntax only. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *defaultValue; @end -/// Fetches the raw value of a @c GPBField's @c kind property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c kind property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Kind_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c kind property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c kind property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Kind_RawValue(GPBField *message, int32_t value); -/// Fetches the raw value of a @c GPBField's @c cardinality property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c cardinality property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Cardinality_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c cardinality property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c cardinality property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Cardinality_RawValue(GPBField *message, int32_t value); #pragma mark - GPBEnum @@ -295,38 +329,44 @@ typedef GPB_ENUM(GPBEnum_FieldNumber) { GPBEnum_FieldNumber_Syntax = 5, }; -/// Enum type definition. +/** + * Enum type definition. + **/ @interface GPBEnum : GPBMessage -/// Enum type name. +/** Enum type name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value definitions. +/** Enum value definitions. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBEnumValue*> *enumvalueArray; -/// The number of items in @c enumvalueArray without causing the array to be created. +/** The number of items in @c enumvalueArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger enumvalueArray_Count; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBEnum's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBEnum's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBEnum_Syntax_RawValue(GPBEnum *message); -/// Sets the raw value of an @c GPBEnum's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBEnum's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBEnum_Syntax_RawValue(GPBEnum *message, int32_t value); #pragma mark - GPBEnumValue @@ -337,18 +377,20 @@ typedef GPB_ENUM(GPBEnumValue_FieldNumber) { GPBEnumValue_FieldNumber_OptionsArray = 3, }; -/// Enum value definition. +/** + * Enum value definition. + **/ @interface GPBEnumValue : GPBMessage -/// Enum value name. +/** Enum value name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value number. +/** Enum value number. */ @property(nonatomic, readwrite) int32_t number; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; @end @@ -360,16 +402,18 @@ typedef GPB_ENUM(GPBOption_FieldNumber) { GPBOption_FieldNumber_Value = 2, }; -/// A protocol buffer option, which can be attached to a message, field, -/// enumeration, etc. +/** + * A protocol buffer option, which can be attached to a message, field, + * enumeration, etc. + **/ @interface GPBOption : GPBMessage -/// The option's name. For example, `"java_package"`. +/** The option's name. For example, `"java_package"`. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The option's value. For example, `"com.google.protobuf"`. +/** The option's value. For example, `"com.google.protobuf"`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBAny *value; -/// Test to see if @c value has been set. +/** Test to see if @c value has been set. */ @property(nonatomic, readwrite) BOOL hasValue; @end diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.h b/objectivec/google/protobuf/Wrappers.pbobjc.h index 5593d348..e397c480 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.h +++ b/objectivec/google/protobuf/Wrappers.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBWrappersRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBWrappersRoot : GPBRootObject @end @@ -45,12 +47,14 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) { GPBDoubleValue_FieldNumber_Value = 1, }; -/// Wrapper message for `double`. -/// -/// The JSON representation for `DoubleValue` is JSON number. +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + **/ @interface GPBDoubleValue : GPBMessage -/// The double value. +/** The double value. */ @property(nonatomic, readwrite) double value; @end @@ -61,12 +65,14 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) { GPBFloatValue_FieldNumber_Value = 1, }; -/// Wrapper message for `float`. -/// -/// The JSON representation for `FloatValue` is JSON number. +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + **/ @interface GPBFloatValue : GPBMessage -/// The float value. +/** The float value. */ @property(nonatomic, readwrite) float value; @end @@ -77,12 +83,14 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) { GPBInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int64`. -/// -/// The JSON representation for `Int64Value` is JSON string. +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + **/ @interface GPBInt64Value : GPBMessage -/// The int64 value. +/** The int64 value. */ @property(nonatomic, readwrite) int64_t value; @end @@ -93,12 +101,14 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) { GPBUInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint64`. -/// -/// The JSON representation for `UInt64Value` is JSON string. +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + **/ @interface GPBUInt64Value : GPBMessage -/// The uint64 value. +/** The uint64 value. */ @property(nonatomic, readwrite) uint64_t value; @end @@ -109,12 +119,14 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) { GPBInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int32`. -/// -/// The JSON representation for `Int32Value` is JSON number. +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + **/ @interface GPBInt32Value : GPBMessage -/// The int32 value. +/** The int32 value. */ @property(nonatomic, readwrite) int32_t value; @end @@ -125,12 +137,14 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) { GPBUInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint32`. -/// -/// The JSON representation for `UInt32Value` is JSON number. +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + **/ @interface GPBUInt32Value : GPBMessage -/// The uint32 value. +/** The uint32 value. */ @property(nonatomic, readwrite) uint32_t value; @end @@ -141,12 +155,14 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) { GPBBoolValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bool`. -/// -/// The JSON representation for `BoolValue` is JSON `true` and `false`. +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + **/ @interface GPBBoolValue : GPBMessage -/// The bool value. +/** The bool value. */ @property(nonatomic, readwrite) BOOL value; @end @@ -157,12 +173,14 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) { GPBStringValue_FieldNumber_Value = 1, }; -/// Wrapper message for `string`. -/// -/// The JSON representation for `StringValue` is JSON string. +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + **/ @interface GPBStringValue : GPBMessage -/// The string value. +/** The string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *value; @end @@ -173,12 +191,14 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) { GPBBytesValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bytes`. -/// -/// The JSON representation for `BytesValue` is JSON string. +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + **/ @interface GPBBytesValue : GPBMessage -/// The bytes value. +/** The bytes value. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/ruby/lib/google/protobuf.rb b/ruby/lib/google/protobuf.rb index 62bdd1bf..9b8d8231 100644 --- a/ruby/lib/google/protobuf.rb +++ b/ruby/lib/google/protobuf.rb @@ -45,7 +45,7 @@ if RUBY_PLATFORM == "java" require 'google/protobuf_java' else begin - require "google/#{RUBY_VERSION.sub(/\.\d$/, '')}/protobuf_c" + require "google/#{RUBY_VERSION.sub(/\.\d+$/, '')}/protobuf_c" rescue LoadError require 'google/protobuf_c' end diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc index e76f8e99..34e17823 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc @@ -62,7 +62,7 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { string enum_comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - enum_comments = BuildCommentsString(location); + enum_comments = BuildCommentsString(location, true); } else { enum_comments = ""; } @@ -81,16 +81,18 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { if (HasPreservingUnknownEnumSemantics(descriptor_->file())) { // Include the unknown value. printer->Print( - "/// Value used if any message's field encounters a value that is not defined\n" - "/// by this enum. The message will also have C functions to get/set the rawValue\n" - "/// of the field.\n" + "/**\n" + " * Value used if any message's field encounters a value that is not defined\n" + " * by this enum. The message will also have C functions to get/set the rawValue\n" + " * of the field.\n" + " **/\n" "$name$_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,\n", "name", name_); } for (int i = 0; i < all_values_.size(); i++) { SourceLocation location; if (all_values_[i]->GetSourceLocation(&location)) { - string comments = BuildCommentsString(location).c_str(); + string comments = BuildCommentsString(location, true).c_str(); if (comments.length() > 0) { if (i > 0) { printer->Print("\n"); @@ -111,8 +113,10 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { "\n" "GPBEnumDescriptor *$name$_EnumDescriptor(void);\n" "\n" - "/// Checks to see if the given value is defined by the enum or was not known at\n" - "/// the time this source was generated.\n" + "/**\n" + " * Checks to see if the given value is defined by the enum or was not known at\n" + " * the time this source was generated.\n" + " **/\n" "BOOL $name$_IsValidValue(int32_t value);\n" "\n", "name", name_); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc index b63bc0de..7a774a09 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc @@ -83,12 +83,16 @@ void EnumFieldGenerator::GenerateCFunctionDeclarations( printer->Print( variables_, - "/// Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n" - "/// if the value was not defined by the enum at the time the code was generated.\n" + "/**\n" + " * Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n" + " * if the value was not defined by the enum at the time the code was generated.\n" + " **/\n" "int32_t $owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message);\n" - "/// Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n" - "/// it to be set to a value that was not defined by the enum at the time the code\n" - "/// was generated.\n" + "/**\n" + " * Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n" + " * it to be set to a value that was not defined by the enum at the time the code\n" + " * was generated.\n" + " **/\n" "void Set$owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message, int32_t value);\n" "\n"); } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_extension.cc b/src/google/protobuf/compiler/objectivec/objectivec_extension.cc index 3f7ab9d3..c0e7253a 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_extension.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_extension.cc @@ -63,7 +63,7 @@ void ExtensionGenerator::GenerateMembersHeader(io::Printer* printer) { vars["method_name"] = method_name_; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - vars["comments"] = BuildCommentsString(location); + vars["comments"] = BuildCommentsString(location, true); } else { vars["comments"] = ""; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_field.cc index 812b4a1c..d2a6e882 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_field.cc @@ -64,7 +64,7 @@ void SetCommonFieldVariables(const FieldDescriptor* descriptor, SourceLocation location; if (descriptor->GetSourceLocation(&location)) { - (*variables)["comments"] = BuildCommentsString(location); + (*variables)["comments"] = BuildCommentsString(location, true); } else { (*variables)["comments"] = "\n"; } @@ -335,7 +335,7 @@ void ObjCObjFieldGenerator::GeneratePropertyDeclaration( if (WantsHasProperty()) { printer->Print( variables_, - "/// Test to see if @c $name$ has been set.\n" + "/** Test to see if @c $name$ has been set. */\n" "@property(nonatomic, readwrite) BOOL has$capitalized_name$$deprecated_attribute$;\n"); } if (IsInitName(variables_.find("name")->second)) { @@ -387,7 +387,7 @@ void RepeatedFieldGenerator::GeneratePropertyDeclaration( "$comments$" "$array_comment$" "@property(nonatomic, readwrite, strong, null_resettable) $array_property_type$ *$name$$storage_attribute$$deprecated_attribute$;\n" - "/// The number of items in @c $name$ without causing the array to be created.\n" + "/** The number of items in @c $name$ without causing the array to be created. */\n" "@property(nonatomic, readonly) NSUInteger $name$_Count$deprecated_attribute$;\n"); if (IsInitName(variables_.find("name")->second)) { // If property name starts with init we need to annotate it to get past ARC. diff --git a/src/google/protobuf/compiler/objectivec/objectivec_file.cc b/src/google/protobuf/compiler/objectivec/objectivec_file.cc index b864ef12..1b7b2783 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_file.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_file.cc @@ -51,208 +51,11 @@ namespace protobuf { // runtime being used. const int32 GOOGLE_PROTOBUF_OBJC_GEN_VERSION = 30001; +const char* kHeaderExtension = ".pbobjc.h"; + namespace compiler { namespace objectivec { -namespace { - -class ImportWriter { - public: - ImportWriter(const Options& options) - : options_(options), - need_to_parse_mapping_file_(true) {} - - void AddFile(const FileGenerator* file); - void Print(io::Printer *printer) const; - - private: - class ProtoFrameworkCollector : public LineConsumer { - public: - ProtoFrameworkCollector(map<string, string>* inout_proto_file_to_framework_name) - : map_(inout_proto_file_to_framework_name) {} - - virtual bool ConsumeLine(const StringPiece& line, string* out_error); - - private: - map<string, string>* map_; - }; - - void ParseFrameworkMappings(); - - const Options options_; - map<string, string> proto_file_to_framework_name_; - bool need_to_parse_mapping_file_; - - vector<string> protobuf_framework_imports_; - vector<string> protobuf_non_framework_imports_; - vector<string> other_framework_imports_; - vector<string> other_imports_; -}; - -void ImportWriter::AddFile(const FileGenerator* file) { - const FileDescriptor* file_descriptor = file->Descriptor(); - const string extension(".pbobjc.h"); - - if (IsProtobufLibraryBundledProtoFile(file_descriptor)) { - protobuf_framework_imports_.push_back( - FilePathBasename(file_descriptor) + extension); - protobuf_non_framework_imports_.push_back(file->Path() + extension); - return; - } - - // Lazy parse any mappings. - if (need_to_parse_mapping_file_) { - ParseFrameworkMappings(); - } - - map<string, string>::iterator proto_lookup = - proto_file_to_framework_name_.find(file_descriptor->name()); - if (proto_lookup != proto_file_to_framework_name_.end()) { - other_framework_imports_.push_back( - proto_lookup->second + "/" + - FilePathBasename(file_descriptor) + extension); - return; - } - - if (!options_.generate_for_named_framework.empty()) { - other_framework_imports_.push_back( - options_.generate_for_named_framework + "/" + - FilePathBasename(file_descriptor) + extension); - return; - } - - other_imports_.push_back(file->Path() + extension); -} - -void ImportWriter::Print(io::Printer* printer) const { - assert(protobuf_non_framework_imports_.size() == - protobuf_framework_imports_.size()); - - bool add_blank_line = false; - - if (protobuf_framework_imports_.size() > 0) { - const string framework_name(ProtobufLibraryFrameworkName); - const string cpp_symbol(ProtobufFrameworkImportSymbol(framework_name)); - - printer->Print( - "#if $cpp_symbol$\n", - "cpp_symbol", cpp_symbol); - for (vector<string>::const_iterator iter = protobuf_framework_imports_.begin(); - iter != protobuf_framework_imports_.end(); ++iter) { - printer->Print( - " #import <$framework_name$/$header$>\n", - "framework_name", framework_name, - "header", *iter); - } - printer->Print( - "#else\n"); - for (vector<string>::const_iterator iter = protobuf_non_framework_imports_.begin(); - iter != protobuf_non_framework_imports_.end(); ++iter) { - printer->Print( - " #import \"$header$\"\n", - "header", *iter); - } - printer->Print( - "#endif\n"); - - add_blank_line = true; - } - - if (other_framework_imports_.size() > 0) { - if (add_blank_line) { - printer->Print("\n"); - } - - for (vector<string>::const_iterator iter = other_framework_imports_.begin(); - iter != other_framework_imports_.end(); ++iter) { - printer->Print( - " #import <$header$>\n", - "header", *iter); - } - - add_blank_line = true; - } - - if (other_imports_.size() > 0) { - if (add_blank_line) { - printer->Print("\n"); - } - - for (vector<string>::const_iterator iter = other_imports_.begin(); - iter != other_imports_.end(); ++iter) { - printer->Print( - " #import \"$header$\"\n", - "header", *iter); - } - } -} - -void ImportWriter::ParseFrameworkMappings() { - need_to_parse_mapping_file_ = false; - if (options_.named_framework_to_proto_path_mappings_path.empty()) { - return; // Nothing to do. - } - - ProtoFrameworkCollector collector(&proto_file_to_framework_name_); - string parse_error; - if (!ParseSimpleFile(options_.named_framework_to_proto_path_mappings_path, - &collector, &parse_error)) { - cerr << "error parsing " << options_.named_framework_to_proto_path_mappings_path - << " : " << parse_error << endl; - cerr.flush(); - } -} - -bool ImportWriter::ProtoFrameworkCollector::ConsumeLine( - const StringPiece& line, string* out_error) { - int offset = line.find(':'); - if (offset == StringPiece::npos) { - *out_error = - string("Framework/proto file mapping line without colon sign: '") + - line.ToString() + "'."; - return false; - } - StringPiece framework_name(line, 0, offset); - StringPiece proto_file_list(line, offset + 1, line.length() - offset - 1); - StringPieceTrimWhitespace(&framework_name); - - int start = 0; - while (start < proto_file_list.length()) { - offset = proto_file_list.find(',', start); - if (offset == StringPiece::npos) { - offset = proto_file_list.length(); - } - - StringPiece proto_file(proto_file_list, start, offset - start); - StringPieceTrimWhitespace(&proto_file); - if (proto_file.size() != 0) { - map<string, string>::iterator existing_entry = - map_->find(proto_file.ToString()); - if (existing_entry != map_->end()) { - cerr << "warning: duplicate proto file reference, replacing framework entry for '" - << proto_file.ToString() << "' with '" << framework_name.ToString() - << "' (was '" << existing_entry->second << "')." << endl; - cerr.flush(); - } - - if (proto_file.find(' ') != StringPiece::npos) { - cerr << "note: framework mapping file had a proto file with a space in, hopefully that isn't a missing comma: '" - << proto_file.ToString() << "'" << endl; - cerr.flush(); - } - - (*map_)[proto_file.ToString()] = framework_name.ToString(); - } - - start = offset + 1; - } - - return true; -} - -} // namespace - - FileGenerator::FileGenerator(const FileDescriptor *file, const Options& options) : file_(file), root_class_name_(FileClassName(file)), @@ -299,13 +102,16 @@ void FileGenerator::GenerateHeader(io::Printer *printer) { // #import any headers for "public imports" in the proto file. { - ImportWriter import_writer(options_); + ImportWriter import_writer( + options_.generate_for_named_framework, + options_.named_framework_to_proto_path_mappings_path); const vector<FileGenerator *> &dependency_generators = DependencyGenerators(); + const string header_extension(kHeaderExtension); for (vector<FileGenerator *>::const_iterator iter = dependency_generators.begin(); iter != dependency_generators.end(); ++iter) { if ((*iter)->IsPublicDependency()) { - import_writer.AddFile(*iter); + import_writer.AddFile((*iter)->file_, header_extension); } } import_writer.Print(printer); @@ -357,14 +163,16 @@ void FileGenerator::GenerateHeader(io::Printer *printer) { printer->Print( "#pragma mark - $root_class_name$\n" "\n" - "/// Exposes the extension registry for this file.\n" - "///\n" - "/// The base class provides:\n" - "/// @code\n" - "/// + (GPBExtensionRegistry *)extensionRegistry;\n" - "/// @endcode\n" - "/// which is a @c GPBExtensionRegistry that includes all the extensions defined by\n" - "/// this file and all files that it depends on.\n" + "/**\n" + " * Exposes the extension registry for this file.\n" + " *\n" + " * The base class provides:\n" + " * @code\n" + " * + (GPBExtensionRegistry *)extensionRegistry;\n" + " * @endcode\n" + " * which is a @c GPBExtensionRegistry that includes all the extensions defined by\n" + " * this file and all files that it depends on.\n" + " **/\n" "@interface $root_class_name$ : GPBRootObject\n" "@end\n" "\n", @@ -405,10 +213,13 @@ void FileGenerator::GenerateSource(io::Printer *printer) { PrintFileRuntimePreamble(printer, "GPBProtocolBuffers_RuntimeSupport.h"); { - ImportWriter import_writer(options_); + ImportWriter import_writer( + options_.generate_for_named_framework, + options_.named_framework_to_proto_path_mappings_path); + const string header_extension(kHeaderExtension); // #import the header for this proto file. - import_writer.AddFile(this); + import_writer.AddFile(file_, header_extension); // #import the headers for anything that a plain dependency of this proto // file (that means they were just an include, not a "public" include). @@ -418,7 +229,7 @@ void FileGenerator::GenerateSource(io::Printer *printer) { dependency_generators.begin(); iter != dependency_generators.end(); ++iter) { if (!(*iter)->IsPublicDependency()) { - import_writer.AddFile(*iter); + import_writer.AddFile((*iter)->file_, header_extension); } } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_file.h b/src/google/protobuf/compiler/objectivec/objectivec_file.h index 8e4388d8..60b19f19 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_file.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_file.h @@ -62,8 +62,6 @@ class FileGenerator { void GenerateHeader(io::Printer* printer); const string& RootClassName() const { return root_class_name_; } - const string Path() const { return FilePath(file_); } - const FileDescriptor* Descriptor() const { return file_; } bool IsPublicDependency() const { return is_public_dep_; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_generator.cc b/src/google/protobuf/compiler/objectivec/objectivec_generator.cc index a0b6d6cb..36407467 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_generator.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_generator.cc @@ -45,10 +45,22 @@ ObjectiveCGenerator::ObjectiveCGenerator() {} ObjectiveCGenerator::~ObjectiveCGenerator() {} +bool ObjectiveCGenerator::HasGenerateAll() const { + return true; +} + bool ObjectiveCGenerator::Generate(const FileDescriptor* file, const string& parameter, - OutputDirectory* output_directory, + GeneratorContext* context, string* error) const { + *error = "Unimplemented Generate() method. Call GenerateAll() instead."; + return false; +} + +bool ObjectiveCGenerator::GenerateAll(const vector<const FileDescriptor*>& files, + const string& parameter, + GeneratorContext* context, + string* error) const { // ----------------------------------------------------------------- // Parse generator options. These options are passed to the compiler using the // --objc_opt flag. The options are passed as a comma separated list of @@ -117,29 +129,32 @@ bool ObjectiveCGenerator::Generate(const FileDescriptor* file, // ----------------------------------------------------------------- - // Validate the objc prefix/package pairing. - if (!ValidateObjCClassPrefix(file, generation_options, error)) { + // Validate the objc prefix/package pairings. + if (!ValidateObjCClassPrefixes(files, generation_options, error)) { // *error will have been filled in. return false; } - FileGenerator file_generator(file, generation_options); - string filepath = FilePath(file); + for (int i = 0; i < files.size(); i++) { + const FileDescriptor* file = files[i]; + FileGenerator file_generator(file, generation_options); + string filepath = FilePath(file); - // Generate header. - { - scoped_ptr<io::ZeroCopyOutputStream> output( - output_directory->Open(filepath + ".pbobjc.h")); - io::Printer printer(output.get(), '$'); - file_generator.GenerateHeader(&printer); - } + // Generate header. + { + scoped_ptr<io::ZeroCopyOutputStream> output( + context->Open(filepath + ".pbobjc.h")); + io::Printer printer(output.get(), '$'); + file_generator.GenerateHeader(&printer); + } - // Generate m file. - { - scoped_ptr<io::ZeroCopyOutputStream> output( - output_directory->Open(filepath + ".pbobjc.m")); - io::Printer printer(output.get(), '$'); - file_generator.GenerateSource(&printer); + // Generate m file. + { + scoped_ptr<io::ZeroCopyOutputStream> output( + context->Open(filepath + ".pbobjc.m")); + io::Printer printer(output.get(), '$'); + file_generator.GenerateSource(&printer); + } } return true; diff --git a/src/google/protobuf/compiler/objectivec/objectivec_generator.h b/src/google/protobuf/compiler/objectivec/objectivec_generator.h index 09266b04..9d801d51 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_generator.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_generator.h @@ -47,8 +47,15 @@ class LIBPROTOC_EXPORT ObjectiveCGenerator : public CodeGenerator { ~ObjectiveCGenerator(); // implements CodeGenerator ---------------------------------------- - bool Generate(const FileDescriptor* file, const string& parameter, - OutputDirectory* output_directory, string* error) const; + bool HasGenerateAll() const; + bool Generate(const FileDescriptor* file, + const string& parameter, + GeneratorContext* context, + string* error) const; + bool GenerateAll(const vector<const FileDescriptor*>& files, + const string& parameter, + GeneratorContext* context, + string* error) const; private: GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ObjectiveCGenerator); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc index 22c7a883..847be983 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc @@ -44,9 +44,10 @@ #include <google/protobuf/stubs/hash.h> #include <google/protobuf/compiler/objectivec/objectivec_helpers.h> +#include <google/protobuf/descriptor.pb.h> #include <google/protobuf/io/coded_stream.h> +#include <google/protobuf/io/printer.h> #include <google/protobuf/io/zero_copy_stream_impl.h> -#include <google/protobuf/descriptor.pb.h> #include <google/protobuf/stubs/common.h> #include <google/protobuf/stubs/strutil.h> @@ -830,7 +831,8 @@ string BuildFlagsString(const vector<string>& strings) { return string; } -string BuildCommentsString(const SourceLocation& location) { +string BuildCommentsString(const SourceLocation& location, + bool prefer_single_line) { const string& comments = location.leading_comments.empty() ? location.trailing_comments : location.leading_comments; @@ -839,15 +841,45 @@ string BuildCommentsString(const SourceLocation& location) { while (!lines.empty() && lines.back().empty()) { lines.pop_back(); } - string prefix("///"); - string suffix("\n"); + // If there are no comments, just return an empty string. + if (lines.size() == 0) { + return ""; + } + + string prefix; + string suffix; string final_comments; - for (int i = 0; i < lines.size(); i++) { - // HeaderDoc uses '\' and '@' for markers; escape them. - const string line = StringReplace(lines[i], "\\", "\\\\", true); - final_comments += - prefix + StringReplace(line, "@", "\\@", true) + suffix; + string epilogue; + + bool add_leading_space = false; + + if (prefer_single_line && lines.size() == 1) { + prefix = "/** "; + suffix = " */\n"; + } else { + prefix = "* "; + suffix = "\n"; + final_comments += "/**\n"; + epilogue = " **/\n"; + add_leading_space = true; } + + for (int i = 0; i < lines.size(); i++) { + string line = StripPrefixString(lines[i], " "); + // HeaderDoc and appledoc use '\' and '@' for markers; escape them. + line = StringReplace(line, "\\", "\\\\", true); + line = StringReplace(line, "@", "\\@", true); + // Decouple / from * to not have inline comments inside comments. + line = StringReplace(line, "/*", "/\\*", true); + line = StringReplace(line, "*/", "*\\/", true); + line = prefix + line; + StripWhitespace(&line); + // If not a one line, need to add the first space before *, as + // StripWhitespace would have removed it. + line = (add_leading_space ? " " : "") + line; + final_comments += line + suffix; + } + final_comments += epilogue; return final_comments; } @@ -948,28 +980,20 @@ bool LoadExpectedPackagePrefixes(const Options &generation_options, generation_options.expected_prefixes_path, &collector, out_error); } -} // namespace - -bool ValidateObjCClassPrefix(const FileDescriptor* file, - const Options& generation_options, - string* out_error) { +bool ValidateObjCClassPrefix( + const FileDescriptor* file, + const string& expected_prefixes_path, + const map<string, string>& expected_package_prefixes, + string* out_error) { const string prefix = file->options().objc_class_prefix(); const string package = file->package(); // NOTE: src/google/protobuf/compiler/plugin.cc makes use of cerr for some // error cases, so it seems to be ok to use as a back door for warnings. - // Load any expected package prefixes to validate against those. - map<string, string> expected_package_prefixes; - if (!LoadExpectedPackagePrefixes(generation_options, - &expected_package_prefixes, - out_error)) { - return false; - } - // Check: Error - See if there was an expected prefix for the package and // report if it doesn't match (wrong or missing). - map<string, string>::iterator package_match = + map<string, string>::const_iterator package_match = expected_package_prefixes.find(package); if (package_match != expected_package_prefixes.end()) { // There was an entry, and... @@ -990,27 +1014,11 @@ bool ValidateObjCClassPrefix(const FileDescriptor* file, } // If there was no prefix option, we're done at this point. - if (prefix.length() == 0) { + if (prefix.empty()) { // No prefix, nothing left to check. return true; } - // Check: Error - Make sure the prefix wasn't expected for a different - // package (overlap is allowed, but it has to be listed as an expected - // overlap). - for (map<string, string>::iterator i = expected_package_prefixes.begin(); - i != expected_package_prefixes.end(); ++i) { - if (i->second == prefix) { - *out_error = - "error: Found 'option objc_class_prefix = \"" + prefix + - "\";' in '" + file->name() + - "'; that prefix is already used for 'package " + i->first + - ";'. It can only be reused by listing it in the expected file (" + - generation_options.expected_prefixes_path + ")."; - return false; // Only report first usage of the prefix. - } - } - // Check: Warning - Make sure the prefix is is a reasonable value according // to Apple's rules (the checks above implicitly whitelist anything that // doesn't meet these rules). @@ -1032,6 +1040,56 @@ bool ValidateObjCClassPrefix(const FileDescriptor* file, cerr.flush(); } + // Look for any other package that uses the same prefix. + string other_package_for_prefix; + for (map<string, string>::const_iterator i = expected_package_prefixes.begin(); + i != expected_package_prefixes.end(); ++i) { + if (i->second == prefix) { + other_package_for_prefix = i->first; + break; + } + } + + // Check: Warning - If the file does not have a package, check whether + // the prefix declared is being used by another package or not. + if (package.empty()) { + // The file does not have a package and ... + if (other_package_for_prefix.empty()) { + // ... no other package has declared that prefix. + cerr << endl + << "protoc:0: warning: File '" << file->name() << "' has no " + << "package. Consider adding a new package to the proto and adding '" + << "new.package = " << prefix << "' to the expected prefixes file (" + << expected_prefixes_path << ")." << endl; + cerr.flush(); + } else { + // ... another package has declared the same prefix. + cerr << endl + << "protoc:0: warning: File '" << file->name() << "' has no package " + << "and package '" << other_package_for_prefix << "' already uses '" + << prefix << "' as its prefix. Consider either adding a new package " + << "to the proto, or reusing one of the packages already using this " + << "prefix in the expected prefixes file (" + << expected_prefixes_path << ")." << endl; + cerr.flush(); + } + return true; + } + + // Check: Error - Make sure the prefix wasn't expected for a different + // package (overlap is allowed, but it has to be listed as an expected + // overlap). + if (!other_package_for_prefix.empty()) { + *out_error = + "error: Found 'option objc_class_prefix = \"" + prefix + + "\";' in '" + file->name() + + "'; that prefix is already used for 'package " + + other_package_for_prefix + ";'. It can only be reused by listing " + + "it in the expected file (" + + expected_prefixes_path + ")."; + return false; // Only report first usage of the prefix. + } + // Check: Warning - If the given package/prefix pair wasn't expected, issue a // warning issue a warning suggesting it gets added to the file. if (!expected_package_prefixes.empty()) { @@ -1039,13 +1097,39 @@ bool ValidateObjCClassPrefix(const FileDescriptor* file, << "protoc:0: warning: Found unexpected 'option objc_class_prefix = \"" << prefix << "\";' in '" << file->name() << "';" << " consider adding it to the expected prefixes file (" - << generation_options.expected_prefixes_path << ")." << endl; + << expected_prefixes_path << ")." << endl; cerr.flush(); } return true; } +} // namespace + +bool ValidateObjCClassPrefixes(const vector<const FileDescriptor*>& files, + const Options& generation_options, + string* out_error) { + // Load the expected package prefixes, if available, to validate against. + map<string, string> expected_package_prefixes; + if (!LoadExpectedPackagePrefixes(generation_options, + &expected_package_prefixes, + out_error)) { + return false; + } + + for (int i = 0; i < files.size(); i++) { + bool is_valid = + ValidateObjCClassPrefix(files[i], + generation_options.expected_prefixes_path, + expected_package_prefixes, + out_error); + if (!is_valid) { + return false; + } + } + return true; +} + TextFormatDecodeData::TextFormatDecodeData() { } TextFormatDecodeData::~TextFormatDecodeData() { } @@ -1368,6 +1452,178 @@ bool ParseSimpleFile( return parser.Finish(); } +ImportWriter::ImportWriter( + const string& generate_for_named_framework, + const string& named_framework_to_proto_path_mappings_path) + : generate_for_named_framework_(generate_for_named_framework), + named_framework_to_proto_path_mappings_path_( + named_framework_to_proto_path_mappings_path), + need_to_parse_mapping_file_(true) { +} + +ImportWriter::~ImportWriter() {} + +void ImportWriter::AddFile(const FileDescriptor* file, + const string& header_extension) { + const string file_path(FilePath(file)); + + if (IsProtobufLibraryBundledProtoFile(file)) { + protobuf_framework_imports_.push_back( + FilePathBasename(file) + header_extension); + protobuf_non_framework_imports_.push_back(file_path + header_extension); + return; + } + + // Lazy parse any mappings. + if (need_to_parse_mapping_file_) { + ParseFrameworkMappings(); + } + + map<string, string>::iterator proto_lookup = + proto_file_to_framework_name_.find(file->name()); + if (proto_lookup != proto_file_to_framework_name_.end()) { + other_framework_imports_.push_back( + proto_lookup->second + "/" + + FilePathBasename(file) + header_extension); + return; + } + + if (!generate_for_named_framework_.empty()) { + other_framework_imports_.push_back( + generate_for_named_framework_ + "/" + + FilePathBasename(file) + header_extension); + return; + } + + other_imports_.push_back(file_path + header_extension); +} + +void ImportWriter::Print(io::Printer* printer) const { + assert(protobuf_non_framework_imports_.size() == + protobuf_framework_imports_.size()); + + bool add_blank_line = false; + + if (protobuf_framework_imports_.size() > 0) { + const string framework_name(ProtobufLibraryFrameworkName); + const string cpp_symbol(ProtobufFrameworkImportSymbol(framework_name)); + + printer->Print( + "#if $cpp_symbol$\n", + "cpp_symbol", cpp_symbol); + for (vector<string>::const_iterator iter = protobuf_framework_imports_.begin(); + iter != protobuf_framework_imports_.end(); ++iter) { + printer->Print( + " #import <$framework_name$/$header$>\n", + "framework_name", framework_name, + "header", *iter); + } + printer->Print( + "#else\n"); + for (vector<string>::const_iterator iter = protobuf_non_framework_imports_.begin(); + iter != protobuf_non_framework_imports_.end(); ++iter) { + printer->Print( + " #import \"$header$\"\n", + "header", *iter); + } + printer->Print( + "#endif\n"); + + add_blank_line = true; + } + + if (other_framework_imports_.size() > 0) { + if (add_blank_line) { + printer->Print("\n"); + } + + for (vector<string>::const_iterator iter = other_framework_imports_.begin(); + iter != other_framework_imports_.end(); ++iter) { + printer->Print( + " #import <$header$>\n", + "header", *iter); + } + + add_blank_line = true; + } + + if (other_imports_.size() > 0) { + if (add_blank_line) { + printer->Print("\n"); + } + + for (vector<string>::const_iterator iter = other_imports_.begin(); + iter != other_imports_.end(); ++iter) { + printer->Print( + " #import \"$header$\"\n", + "header", *iter); + } + } +} + +void ImportWriter::ParseFrameworkMappings() { + need_to_parse_mapping_file_ = false; + if (named_framework_to_proto_path_mappings_path_.empty()) { + return; // Nothing to do. + } + + ProtoFrameworkCollector collector(&proto_file_to_framework_name_); + string parse_error; + if (!ParseSimpleFile(named_framework_to_proto_path_mappings_path_, + &collector, &parse_error)) { + cerr << "error parsing " << named_framework_to_proto_path_mappings_path_ + << " : " << parse_error << endl; + cerr.flush(); + } +} + +bool ImportWriter::ProtoFrameworkCollector::ConsumeLine( + const StringPiece& line, string* out_error) { + int offset = line.find(':'); + if (offset == StringPiece::npos) { + *out_error = + string("Framework/proto file mapping line without colon sign: '") + + line.ToString() + "'."; + return false; + } + StringPiece framework_name(line, 0, offset); + StringPiece proto_file_list(line, offset + 1, line.length() - offset - 1); + StringPieceTrimWhitespace(&framework_name); + + int start = 0; + while (start < proto_file_list.length()) { + offset = proto_file_list.find(',', start); + if (offset == StringPiece::npos) { + offset = proto_file_list.length(); + } + + StringPiece proto_file(proto_file_list, start, offset - start); + StringPieceTrimWhitespace(&proto_file); + if (proto_file.size() != 0) { + map<string, string>::iterator existing_entry = + map_->find(proto_file.ToString()); + if (existing_entry != map_->end()) { + cerr << "warning: duplicate proto file reference, replacing framework entry for '" + << proto_file.ToString() << "' with '" << framework_name.ToString() + << "' (was '" << existing_entry->second << "')." << endl; + cerr.flush(); + } + + if (proto_file.find(' ') != StringPiece::npos) { + cerr << "note: framework mapping file had a proto file with a space in, hopefully that isn't a missing comma: '" + << proto_file.ToString() << "'" << endl; + cerr.flush(); + } + + (*map_)[proto_file.ToString()] = framework_name.ToString(); + } + + start = offset + 1; + } + + return true; +} + } // namespace objectivec } // namespace compiler diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h index be20beee..b05983df 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h @@ -170,8 +170,10 @@ bool HasNonZeroDefaultValue(const FieldDescriptor* field); string BuildFlagsString(const vector<string>& strings); -// Builds a HeaderDoc style comment out of the comments in the .proto file. -string BuildCommentsString(const SourceLocation& location); +// Builds HeaderDoc/appledoc style comments out of the comments in the .proto +// file. +string BuildCommentsString(const SourceLocation& location, + bool prefer_single_line); // The name the commonly used by the library when built as a framework. // This lines up to the name used in the CocoaPod. @@ -183,12 +185,12 @@ string ProtobufFrameworkImportSymbol(const string& framework_name); // Checks if the file is one of the proto's bundled with the library. bool IsProtobufLibraryBundledProtoFile(const FileDescriptor* file); -// Checks the prefix for a given file and outputs any warnings needed, if -// there are flat out errors, then out_error is filled in and the result is -// false. -bool ValidateObjCClassPrefix(const FileDescriptor* file, - const Options& generation_options, - string* out_error); +// Checks the prefix for the given files and outputs any warnings as needed. If +// there are flat out errors, then out_error is filled in with the first error +// and the result is false. +bool ValidateObjCClassPrefixes(const vector<const FileDescriptor*>& files, + const Options& generation_options, + string* out_error); // Generate decode data needed for ObjC's GPBDecodeTextFormatName() to transform // the input into the expected output. @@ -223,6 +225,43 @@ class LIBPROTOC_EXPORT LineConsumer { bool ParseSimpleFile( const string& path, LineConsumer* line_consumer, string* out_error); + +// Helper class for parsing framework import mappings and generating +// import statements. +class LIBPROTOC_EXPORT ImportWriter { + public: + ImportWriter(const string& generate_for_named_framework, + const string& named_framework_to_proto_path_mappings_path); + ~ImportWriter(); + + void AddFile(const FileDescriptor* file, const string& header_extension); + void Print(io::Printer *printer) const; + + private: + class ProtoFrameworkCollector : public LineConsumer { + public: + ProtoFrameworkCollector(map<string, string>* inout_proto_file_to_framework_name) + : map_(inout_proto_file_to_framework_name) {} + + virtual bool ConsumeLine(const StringPiece& line, string* out_error); + + private: + map<string, string>* map_; + }; + + void ParseFrameworkMappings(); + + const string generate_for_named_framework_; + const string named_framework_to_proto_path_mappings_path_; + map<string, string> proto_file_to_framework_name_; + bool need_to_parse_mapping_file_; + + vector<string> protobuf_framework_imports_; + vector<string> protobuf_non_framework_imports_; + vector<string> other_framework_imports_; + vector<string> other_imports_; +}; + } // namespace objectivec } // namespace compiler } // namespace protobuf diff --git a/src/google/protobuf/compiler/objectivec/objectivec_message.cc b/src/google/protobuf/compiler/objectivec/objectivec_message.cc index e1a78619..822da893 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_message.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_message.cc @@ -331,7 +331,7 @@ void MessageGenerator::GenerateMessageHeader(io::Printer* printer) { string message_comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - message_comments = BuildCommentsString(location); + message_comments = BuildCommentsString(location, false); } else { message_comments = ""; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc index 3dda903b..5531ae24 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc @@ -53,7 +53,7 @@ OneofGenerator::OneofGenerator(const OneofDescriptor* descriptor) string comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - comments = BuildCommentsString(location); + comments = BuildCommentsString(location, true); } else { comments = ""; } @@ -104,7 +104,9 @@ void OneofGenerator::GeneratePublicCasePropertyDeclaration( void OneofGenerator::GenerateClearFunctionDeclaration(io::Printer* printer) { printer->Print( variables_, - "/// Clears whatever value was set for the oneof '$name$'.\n" + "/**\n" + " * Clears whatever value was set for the oneof '$name$'.\n" + " **/\n" "void $owning_message_class$_Clear$capitalized_name$OneOfCase($owning_message_class$ *message);\n"); } 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/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; } |