objectivec/GPBUnknownFields.h

   1 // Protocol Buffers - Google's data interchange format
   2 // Copyright 2024 Google Inc.  All rights reserved.
   3 //
   4 // Use of this source code is governed by a BSD-style
   5 // license that can be found in the LICENSE file or at
   6 // https://developers.google.com/open-source/licenses/bsd
   7
   8 #import <Foundation/Foundation.h>
   9
  10 #import "GPBMessage.h"
  11 #import "GPBUnknownField.h"
  12
  13 @class GPBMessage;
  14 @class GPBUnknownField;
  15
  16 NS_ASSUME_NONNULL_BEGIN
  17
  18 /**
  19  * A collection of unknown field numbers and their values.
  20  *
  21  * Note: `NSFastEnumeration` is supported to iterate over the `GPBUnknownFields`
  22  * in order.
  23  *
  24  * Reminder: Any field number can occur multiple times. For example, if a .proto
  25  * file were updated to a have a new (unpacked) repeated field, then each value
  26  * would appear independently. Likewise, it is possible that a number appears
  27  * multiple times with different data types, i.e. - unpacked vs. package repeated
  28  * fields from concatenating binary blobs of data.
  29  */
  30 __attribute__((objc_subclassing_restricted))
  31 @interface GPBUnknownFields : NSObject<NSCopying, NSFastEnumeration>
  32
  33 /**
  34  * Initializes a new instance with the data from the unknown fields from the given
  35  * message.
  36  *
  37  * Note: The instance is not linked to the message, any change will not be
  38  * reflected on the message the changes have to be pushed back to the message
  39  * with `-[GPBMessage mergeUnknownFields:extensionRegistry:error:]`.
  40  **/
  41 - (instancetype)initFromMessage:(nonnull GPBMessage *)message;
  42
  43 /**
  44  * Initializes a new empty instance.
  45  **/
  46 - (instancetype)init;
  47
  48 /**
  49  * The number of fields in this set. A single field number can appear in
  50  * multiple `GPBUnknownField` values as it might be a repeated field (it is
  51  * also possible that they have different `type` values (for example package vs
  52  * unpacked repeated fields).
  53  *
  54  * Note: `NSFastEnumeration` is supported to iterate over the fields in order.
  55  **/
  56 @property(nonatomic, readonly, assign) NSUInteger count;
  57
  58 /** If the set is empty or not. */
  59 @property(nonatomic, readonly, assign) BOOL empty;
  60
  61 /**
  62  * Removes all the fields current in the set.
  63  **/
  64 - (void)clear;
  65
  66 /**
  67  * Fetches the subset of all the unknown fields that are for the given field
  68  * number.
  69  *
  70  * @returns An `NSArray` of `GPBUnknownField`s or `nil` if there were none.
  71  */
  72 - (nullable NSArray<GPBUnknownField *> *)fields:(int32_t)fieldNumber;
  73
  74 /**
  75  * Add a new varint unknown field.
  76  *
  77  * @param fieldNumber The field number to use.
  78  * @param value The value to add.
  79  **/
  80 - (void)addFieldNumber:(int32_t)fieldNumber varint:(uint64_t)value;
  81
  82 /**
  83  * Add a new fixed32 unknown field.
  84  *
  85  * @param fieldNumber The field number to use.
  86  * @param value The value to add.
  87  **/
  88 - (void)addFieldNumber:(int32_t)fieldNumber fixed32:(uint32_t)value;
  89
  90 /**
  91  * Add a new fixed64 unknown field.
  92  *
  93  * @param fieldNumber The field number to use.
  94  * @param value The value to add.
  95  **/
  96 - (void)addFieldNumber:(int32_t)fieldNumber fixed64:(uint64_t)value;
  97
  98 /**
  99  * Add a new length delimited (length prefixed) unknown field.
 100  *
 101  * @param fieldNumber The field number to use.
 102  * @param value The value to add.
 103  **/
 104 - (void)addFieldNumber:(int32_t)fieldNumber lengthDelimited:(nonnull NSData *)value;
 105
 106 /**
 107  * Add a group (tag delimited) unknown field.
 108  *
 109  * @param fieldNumber The field number to use.
 110  *
 111  * @return A new `GPBUnknownFields` to set the field of the group too.
 112  **/
 113 - (nonnull GPBUnknownFields *)addGroupWithFieldNumber:(int32_t)fieldNumber;
 114
 115 /**
 116  * Add the copy of the given unknown field.
 117  *
 118  * This can be useful from processing one `GPBUnknownFields` to create another.
 119  *
 120  * NOTE: If the field being copied is an Group, this instance added is new and thus
 121  * the `.group` of that result is also new, so if you intent is to modify the group
 122  * it *must* be fetched out of the result.
 123  *
 124  * @param field The field to add.
 125  *
 126  * @return The autoreleased field that was added.
 127  **/
 128 - (GPBUnknownField *)addCopyOfField:(nonnull GPBUnknownField *)field;
 129
 130 /**
 131  * Removes the given field from the set.
 132  *
 133  * It is a programming error to attempt to remove a field that is not in this collection.
 134  *
 135  * Reminder: it is not save to mutate the collection while also using fast enumeration on it.
 136  *
 137  * @param field The field to remove.
 138  **/
 139 - (void)removeField:(nonnull GPBUnknownField *)field;
 140
 141 /**
 142  * Removes all of the fields from the collection that have the given field number.
 143  *
 144  * If there are no fields with the given field number, this is a no-op.
 145  *
 146  * @param fieldNumber The field number to remove.
 147  **/
 148 - (void)clearFieldNumber:(int32_t)fieldNumber;
 149
 150 @end
 151
 152 @interface GPBUnknownFields (AccessHelpers)
 153
 154 /**
 155  * Fetches the first varint for the given field number.
 156  *
 157  * @param fieldNumber The field number to look for.
 158  * @param outValue A pointer to receive the value if found
 159  *
 160  * @returns YES/NO on if there was a matching unknown field.
 161  **/
 162 - (BOOL)getFirst:(int32_t)fieldNumber varint:(nonnull uint64_t *)outValue;
 163
 164 /**
 165  * Fetches the first fixed32 for the given field number.
 166  *
 167  * @param fieldNumber The field number to look for.
 168  * @param outValue A pointer to receive the value if found
 169  *
 170  * @returns YES/NO on if there was a matching unknown field.
 171  **/
 172 - (BOOL)getFirst:(int32_t)fieldNumber fixed32:(nonnull uint32_t *)outValue;
 173
 174 /**
 175  * Fetches the first fixed64 for the given field number.
 176  *
 177  * @param fieldNumber The field number to look for.
 178  * @param outValue A pointer to receive the value if found
 179  *
 180  * @returns YES/NO on if there was a matching unknown field.
 181  **/
 182 - (BOOL)getFirst:(int32_t)fieldNumber fixed64:(nonnull uint64_t *)outValue;
 183
 184 /**
 185  * Fetches the first length delimited (length prefixed) for the given field number.
 186  *
 187  * @param fieldNumber The field number to look for.
 188  *
 189  * @returns The first length delimited value for the given field number.
 190  **/
 191 - (nullable NSData *)firstLengthDelimited:(int32_t)fieldNumber;
 192
 193 /**
 194  * Fetches the first group (tag delimited) field for the given field number.
 195  *
 196  * @param fieldNumber The field number to look for.
 197  *
 198  * @returns The first group for the given field number.
 199  **/
 200 - (nullable GPBUnknownFields *)firstGroup:(int32_t)fieldNumber;
 201
 202 @end
 203
 204 NS_ASSUME_NONNULL_END