Merge pull request #1920 from gegles/master
Fix missing import of jspb.Map (#1885)
diff --git a/.gitignore b/.gitignore
index 5cb8cba..052dd14 100644
--- a/.gitignore
+++ b/.gitignore
@@ -64,6 +64,8 @@
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.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
diff --git a/BUILD b/BUILD
index 0941d8c..941ca69 100644
--- a/BUILD
+++ b/BUILD
@@ -2,6 +2,8 @@
licenses(["notice"])
+exports_files(["LICENSE"])
+
################################################################################
# Protobuf Runtime Library
################################################################################
diff --git a/Protobuf.podspec b/Protobuf.podspec
index 642fc3e..72e6dd0 100644
--- a/Protobuf.podspec
+++ b/Protobuf.podspec
@@ -36,5 +36,6 @@
s.ios.deployment_target = '7.1'
s.osx.deployment_target = '10.9'
+ s.watchos.deployment_target = '2.0'
s.requires_arc = false
end
diff --git a/README.md b/README.md
index ba9c589..67be3e9 100644
--- a/README.md
+++ b/README.md
@@ -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 ce797c6..2ea3cb7 100644
--- a/appveyor.yml
+++ b/appveyor.yml
@@ -19,9 +19,15 @@
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
diff --git a/autogen.sh b/autogen.sh
index 5b4c29f..9f26642 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -31,10 +31,15 @@
# 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 94ef219..73e3198 100644
--- a/cmake/install.cmake
+++ b/cmake/install.cmake
@@ -110,7 +110,7 @@
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 b76407e..28ac3c8 100644
--- a/conformance/Makefile.am
+++ b/conformance/Makefile.am
@@ -20,7 +20,7 @@
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 fc96074..95a8fd1 100644
--- a/conformance/conformance.proto
+++ b/conformance/conformance.proto
@@ -210,6 +210,11 @@
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 @@
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 @@
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 598ef73..fb963f6 100644
--- a/conformance/conformance_test.cc
+++ b/conformance/conformance_test.cc
@@ -272,11 +272,16 @@
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 @@
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 @@
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 @@
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 @@
"fieldname1": 1,
"field_name2": 2,
"_field_name3": 3,
+ "field__name4_": 4,
"field0name5": 5,
"field_0_name6": 6,
"fieldName7": 7,
@@ -693,12 +732,19 @@
"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 @@
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 @@
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 @@
// 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 @@
"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 @@
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 @@
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 @@
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 @@
"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 c9c5213..5668931 100644
--- a/conformance/conformance_test.h
+++ b/conformance/conformance_test.h
@@ -133,6 +133,9 @@
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 839e521..5e17176 100644
--- a/conformance/failure_list_cpp.txt
+++ b/conformance/failure_list_cpp.txt
@@ -22,16 +22,22 @@
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 1716bcb..d8bfe1b 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 850712b..b2122c8 100644
--- a/conformance/failure_list_java.txt
+++ b/conformance/failure_list_java.txt
@@ -20,8 +20,13 @@
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.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 5dac350..dd538c1 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 550a043..d38b782 100644
--- a/conformance/failure_list_python.txt
+++ b/conformance/failure_list_python.txt
@@ -19,9 +19,6 @@
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.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 1eb916a..84d9fcc 100644
--- a/conformance/failure_list_python_cpp.txt
+++ b/conformance/failure_list_python_cpp.txt
@@ -28,9 +28,6 @@
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.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 7c12da0..2a533aa 100644
--- a/conformance/failure_list_ruby.txt
+++ b/conformance/failure_list_ruby.txt
@@ -58,7 +58,12 @@
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.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.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 5fcbff7..431ac4f 100644
--- a/csharp/src/Google.Protobuf.Conformance/Conformance.cs
+++ b/csharp/src/Google.Protobuf.Conformance/Conformance.cs
@@ -34,7 +34,7 @@
"IAEoCUgAEhkKD3NlcmlhbGl6ZV9lcnJvchgGIAEoCUgAEhcKDXJ1bnRpbWVf",
"ZXJyb3IYAiABKAlIABIaChBwcm90b2J1Zl9wYXlsb2FkGAMgASgMSAASFgoM",
"anNvbl9wYXlsb2FkGAQgASgJSAASEQoHc2tpcHBlZBgFIAEoCUgAQggKBnJl",
- "c3VsdCLVMgoMVGVzdEFsbFR5cGVzEhYKDm9wdGlvbmFsX2ludDMyGAEgASgF",
+ "c3VsdCKCNQoMVGVzdEFsbFR5cGVzEhYKDm9wdGlvbmFsX2ludDMyGAEgASgF",
"EhYKDm9wdGlvbmFsX2ludDY0GAIgASgDEhcKD29wdGlvbmFsX3VpbnQzMhgD",
"IAEoDRIXCg9vcHRpb25hbF91aW50NjQYBCABKAQSFwoPb3B0aW9uYWxfc2lu",
"dDMyGAUgASgREhcKD29wdGlvbmFsX3NpbnQ2NBgGIAEoEhIYChBvcHRpb25h",
@@ -102,93 +102,100 @@
"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 @@
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 @@
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 @@
}
}
+ /// <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 @@
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 @@
}
}
+ /// <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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 021cc56..935deab 100644
--- a/docs/third_party.md
+++ b/docs/third_party.md
@@ -36,6 +36,7 @@
* 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 f615a0a..1cef413 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 8295313..9a6b7bf 100755
--- a/objectivec/DevTools/compile_testing_protos.sh
+++ b/objectivec/DevTools/compile_testing_protos.sh
@@ -99,26 +99,26 @@
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 afda57f..781cfb6 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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
// 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 @@
// 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 @@
//%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 @@
//%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 @@
//%// 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 @@
//%
//%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 @@
//
//%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 @@
//%// 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 4db08e8..2e5bdc7 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 df9d97b..de27b18 100644
--- a/objectivec/GPBCodedInputStream.h
+++ b/objectivec/GPBCodedInputStream.h
@@ -37,125 +37,194 @@
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 8272880..d6fff3d 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 @@
//%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 @@
// 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 63ba806..251a159 100644
--- a/objectivec/GPBCodedOutputStream.m
+++ b/objectivec/GPBCodedOutputStream.m
@@ -144,22 +144,6 @@
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 @@
}
- (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 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 fe4ff39..36fb4ea 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 f795996..4b2b9ff 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 @@
#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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
//%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 @@
//%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 @@
//%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 @@
//%
//%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 @@
//%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 @@
// 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 08a6472..d79632d 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 7e0f58a..0cb74f9 100644
--- a/objectivec/GPBMessage.h
+++ b/objectivec/GPBMessage.h
@@ -44,285 +44,404 @@
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>
+
+// 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.
-// 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.
+/**
+ * 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;
+/**
+ * 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 is only for
-/// repeated field extensions. If the field is a repeated POD type the @c value
-/// is a @c NSNumber.
+/**
+ * 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 c05b5c6..d2e2aeb 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 0a38b11..4d55206 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 @@
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 0f301e4..a135cc2 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 cf61299..1b5f24f 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 b720932..52e7d2e 100644
--- a/objectivec/GPBUtilities.h
+++ b/objectivec/GPBUtilities.h
@@ -38,34 +38,58 @@
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 @@
//
-// 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 @@
//%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 @@
//%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 ee84fb4..80b85d0 100644
--- a/objectivec/GPBUtilities.m
+++ b/objectivec/GPBUtilities.m
@@ -218,9 +218,10 @@
//% 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 @@
// 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 c02493b..a41ee2a 100644
--- a/objectivec/GPBUtilities_PackagePrivate.h
+++ b/objectivec/GPBUtilities_PackagePrivate.h
@@ -96,7 +96,7 @@
// 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 @@
// 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 @@
// 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 @@
// 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 311ac58..96d51d9 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 0723b64..2ad326b 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 1520381..2cf9cce 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 914945e..e5577fa 100644
--- a/objectivec/Tests/unittest_objc.proto
+++ b/objectivec/Tests/unittest_objc.proto
@@ -34,6 +34,15 @@
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 4253b60..842052f 100644
--- a/objectivec/google/protobuf/Any.pbobjc.h
+++ b/objectivec/google/protobuf/Any.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 04341f4..182e866 100644
--- a/objectivec/google/protobuf/Api.pbobjc.h
+++ b/objectivec/google/protobuf/Api.pbobjc.h
@@ -34,14 +34,16 @@
#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 @@
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 @@
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 @@
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 4c3173d..fa91e22 100644
--- a/objectivec/google/protobuf/Duration.pbobjc.h
+++ b/objectivec/google/protobuf/Duration.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 2d2a86b..4d36174 100644
--- a/objectivec/google/protobuf/Empty.pbobjc.h
+++ b/objectivec/google/protobuf/Empty.pbobjc.h
@@ -28,28 +28,32 @@
#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 06053f1..491463f 100644
--- a/objectivec/google/protobuf/FieldMask.pbobjc.h
+++ b/objectivec/google/protobuf/FieldMask.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 4514fa9..d945005 100644
--- a/objectivec/google/protobuf/SourceContext.pbobjc.h
+++ b/objectivec/google/protobuf/SourceContext.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 3e2d55f..a5b31cd 100644
--- a/objectivec/google/protobuf/Struct.pbobjc.h
+++ b/objectivec/google/protobuf/Struct.pbobjc.h
@@ -32,35 +32,43 @@
#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 @@
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 @@
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 @@
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 d15de7c..ebfa670 100644
--- a/objectivec/google/protobuf/Timestamp.pbobjc.h
+++ b/objectivec/google/protobuf/Timestamp.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 93ee3ce..0541195 100644
--- a/objectivec/google/protobuf/Type.pbobjc.h
+++ b/objectivec/google/protobuf/Type.pbobjc.h
@@ -34,134 +34,148 @@
#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 @@
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 @@
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 @@
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 @@
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 @@
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 5593d34..e397c48 100644
--- a/objectivec/google/protobuf/Wrappers.pbobjc.h
+++ b/objectivec/google/protobuf/Wrappers.pbobjc.h
@@ -28,14 +28,16 @@
#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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 62bdd1b..9b8d823 100644
--- a/ruby/lib/google/protobuf.rb
+++ b/ruby/lib/google/protobuf.rb
@@ -45,7 +45,7 @@
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 e76f8e9..34e1782 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc
@@ -62,7 +62,7 @@
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 @@
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 @@
"\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 b63bc0d..7a774a0 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 @@
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 3f7ab9d..c0e7253 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_extension.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_extension.cc
@@ -63,7 +63,7 @@
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 812b4a1..d2a6e88 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_field.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_field.cc
@@ -64,7 +64,7 @@
SourceLocation location;
if (descriptor->GetSourceLocation(&location)) {
- (*variables)["comments"] = BuildCommentsString(location);
+ (*variables)["comments"] = BuildCommentsString(location, true);
} else {
(*variables)["comments"] = "\n";
}
@@ -335,7 +335,7 @@
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 @@
"$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 b864ef1..1b7b278 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_file.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_file.cc
@@ -51,208 +51,11 @@
// 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 @@
// #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 @@
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 @@
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 @@
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 8e4388d..60b19f1 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_file.h
+++ b/src/google/protobuf/compiler/objectivec/objectivec_file.h
@@ -62,8 +62,6 @@
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 a0b6d6c..3640746 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() {}
+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 @@
// -----------------------------------------------------------------
- // 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 09266b0..9d801d5 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_generator.h
+++ b/src/google/protobuf/compiler/objectivec/objectivec_generator.h
@@ -47,8 +47,15 @@
~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 22c7a88..847be98 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/io/coded_stream.h>
-#include <google/protobuf/io/zero_copy_stream_impl.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/stubs/common.h>
#include <google/protobuf/stubs/strutil.h>
@@ -830,7 +831,8 @@
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 @@
while (!lines.empty() && lines.back().empty()) {
lines.pop_back();
}
- string prefix("///");
- string suffix("\n");
- 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;
+ // If there are no comments, just return an empty string.
+ if (lines.size() == 0) {
+ return "";
}
+
+ string prefix;
+ string suffix;
+ string final_comments;
+ 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 @@
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 @@
}
// 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 @@
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 @@
<< "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 @@
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 be20bee..b05983d 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h
+++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h
@@ -170,8 +170,10 @@
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 @@
// 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 @@
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 e1a7861..822da89 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_message.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_message.cc
@@ -331,7 +331,7 @@
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 3dda903..5531ae2 100644
--- a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc
+++ b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc
@@ -53,7 +53,7 @@
string comments;
SourceLocation location;
if (descriptor_->GetSourceLocation(&location)) {
- comments = BuildCommentsString(location);
+ comments = BuildCommentsString(location, true);
} else {
comments = "";
}
@@ -104,7 +104,9 @@
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 a0116a6..7314ee4 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 @@
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 3d07b12..bc76c84 100644
--- a/src/google/protobuf/testing/file.cc
+++ b/src/google/protobuf/testing/file.cc
@@ -91,6 +91,7 @@
if (fwrite(contents.data(), 1, contents.size(), file) != contents.size()) {
GOOGLE_LOG(ERROR) << "fwrite(" << name << "): " << strerror(errno);
+ fclose(file);
return false;
}
