Fix small typo (#19993)
[google-protobuf.git] / objectivec / GPBCodedOutputStream.h
blob92e0d8ff3627513bd150cfa8e48408dfa71a921d
1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 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
8 #import <Foundation/Foundation.h>
10 #import "GPBRuntimeTypes.h"
11 #import "GPBWireFormat.h"
13 #import "GPBArray.h"
15 NS_ASSUME_NONNULL_BEGIN
17 /**
18 * @c GPBCodedOutputStream exception names.
19 **/
20 extern NSString *const GPBCodedOutputStreamException_OutOfSpace;
21 extern NSString *const GPBCodedOutputStreamException_WriteFailed;
23 /**
24 * Writes out protocol message fields.
26 * The common uses of protocol buffers shouldn't need to use this class.
27 * GPBMessage's provide a -data method that will serialize the message for you.
29 * @note Any -write* api can raise the GPBCodedOutputStreamException_*
30 * exceptions.
32 * @note Subclassing of GPBCodedOutputStream is NOT supported.
33 **/
34 __attribute__((objc_subclassing_restricted))
35 @interface GPBCodedOutputStream : NSObject
37 /**
38 * Creates a stream to fill in the given data. Data must be sized to fit or
39 * an error will be raised when out of space.
41 * @param data The data where the stream will be written to.
43 * @return A newly instanced GPBCodedOutputStream.
44 **/
45 + (instancetype)streamWithData:(NSMutableData *)data;
47 /**
48 * Creates a stream to write into the given NSOutputStream.
50 * @param output The output stream where the stream will be written to.
52 * @return A newly instanced GPBCodedOutputStream.
53 **/
54 + (instancetype)streamWithOutputStream:(NSOutputStream *)output;
56 /**
57 * Initializes a stream to fill in the given data. Data must be sized to fit
58 * or an error will be raised when out of space.
60 * @param data The data where the stream will be written to.
62 * @return A newly initialized GPBCodedOutputStream.
63 **/
64 - (instancetype)initWithData:(NSMutableData *)data;
66 /**
67 * Initializes a stream to write into the given @c NSOutputStream.
69 * @param output The output stream where the stream will be written to.
71 * @return A newly initialized GPBCodedOutputStream.
72 **/
73 - (instancetype)initWithOutputStream:(NSOutputStream *)output;
75 /**
76 * Flush any buffered data out.
77 **/
78 - (void)flush;
80 /**
81 * @return The number of bytes written out. Includes bytes not yet flused.
82 **/
83 - (size_t)bytesWritten;
85 /**
86 * Write the raw byte out.
88 * @param value The value to write out.
89 **/
90 - (void)writeRawByte:(uint8_t)value;
92 /**
93 * Write the tag for the given field number and wire format.
95 * @param fieldNumber The field number.
96 * @param format The wire format the data for the field will be in.
97 **/
98 - (void)writeTag:(uint32_t)fieldNumber format:(GPBWireFormat)format;
101 * Write a 32bit value out in little endian format.
103 * @param value The value to write out.
105 - (void)writeRawLittleEndian32:(int32_t)value;
107 * Write a 64bit value out in little endian format.
109 * @param value The value to write out.
111 - (void)writeRawLittleEndian64:(int64_t)value;
114 * Write a 32bit value out in varint format.
116 * @param value The value to write out.
118 - (void)writeRawVarint32:(int32_t)value;
120 * Write a 64bit value out in varint format.
122 * @param value The value to write out.
124 - (void)writeRawVarint64:(int64_t)value;
127 * Write a size_t out as a 32bit varint value.
129 * @note This will truncate 64 bit values to 32.
131 * @param value The value to write out.
133 - (void)writeRawVarintSizeTAs32:(size_t)value;
136 * Writes the contents of an NSData out.
138 * @param data The data to write out.
140 - (void)writeRawData:(NSData *)data;
142 * Writes out the given data.
144 * @param data The data blob to write out.
145 * @param offset The offset into the blob to start writing out.
146 * @param length The number of bytes from the blob to write out.
148 - (void)writeRawPtr:(const void *)data offset:(size_t)offset length:(size_t)length;
150 // Disable clang-format for the macros.
151 // clang-format off
153 //%PDDM-EXPAND _WRITE_DECLS()
154 // This block of code is generated, do not edit it directly.
157 * Write a double for the given field number.
159 * @param fieldNumber The field number assigned to the value.
160 * @param value The value to write out.
162 - (void)writeDouble:(int32_t)fieldNumber value:(double)value;
164 * Write a packed array of double for the given field number.
166 * @param fieldNumber The field number assigned to the values.
167 * @param values The values to write out.
168 * @param tag The tag assigned to the values.
170 - (void)writeDoubleArray:(int32_t)fieldNumber
171 values:(GPBDoubleArray *)values
172 tag:(uint32_t)tag;
174 * Write a double without any tag.
176 * @param value The value to write out.
178 - (void)writeDoubleNoTag:(double)value;
181 * Write a float for the given field number.
183 * @param fieldNumber The field number assigned to the value.
184 * @param value The value to write out.
186 - (void)writeFloat:(int32_t)fieldNumber value:(float)value;
188 * Write a packed array of float for the given field number.
190 * @param fieldNumber The field number assigned to the values.
191 * @param values The values to write out.
192 * @param tag The tag assigned to the values.
194 - (void)writeFloatArray:(int32_t)fieldNumber
195 values:(GPBFloatArray *)values
196 tag:(uint32_t)tag;
198 * Write a float without any tag.
200 * @param value The value to write out.
202 - (void)writeFloatNoTag:(float)value;
205 * Write a uint64_t for the given field number.
207 * @param fieldNumber The field number assigned to the value.
208 * @param value The value to write out.
210 - (void)writeUInt64:(int32_t)fieldNumber value:(uint64_t)value;
212 * Write a packed array of uint64_t for the given field number.
214 * @param fieldNumber The field number assigned to the values.
215 * @param values The values to write out.
216 * @param tag The tag assigned to the values.
218 - (void)writeUInt64Array:(int32_t)fieldNumber
219 values:(GPBUInt64Array *)values
220 tag:(uint32_t)tag;
222 * Write a uint64_t without any tag.
224 * @param value The value to write out.
226 - (void)writeUInt64NoTag:(uint64_t)value;
229 * Write a int64_t for the given field number.
231 * @param fieldNumber The field number assigned to the value.
232 * @param value The value to write out.
234 - (void)writeInt64:(int32_t)fieldNumber value:(int64_t)value;
236 * Write a packed array of int64_t for the given field number.
238 * @param fieldNumber The field number assigned to the values.
239 * @param values The values to write out.
240 * @param tag The tag assigned to the values.
242 - (void)writeInt64Array:(int32_t)fieldNumber
243 values:(GPBInt64Array *)values
244 tag:(uint32_t)tag;
246 * Write a int64_t without any tag.
248 * @param value The value to write out.
250 - (void)writeInt64NoTag:(int64_t)value;
253 * Write a int32_t for the given field number.
255 * @param fieldNumber The field number assigned to the value.
256 * @param value The value to write out.
258 - (void)writeInt32:(int32_t)fieldNumber value:(int32_t)value;
260 * Write a packed array of int32_t for the given field number.
262 * @param fieldNumber The field number assigned to the values.
263 * @param values The values to write out.
264 * @param tag The tag assigned to the values.
266 - (void)writeInt32Array:(int32_t)fieldNumber
267 values:(GPBInt32Array *)values
268 tag:(uint32_t)tag;
270 * Write a int32_t without any tag.
272 * @param value The value to write out.
274 - (void)writeInt32NoTag:(int32_t)value;
277 * Write a uint32_t for the given field number.
279 * @param fieldNumber The field number assigned to the value.
280 * @param value The value to write out.
282 - (void)writeUInt32:(int32_t)fieldNumber value:(uint32_t)value;
284 * Write a packed array of uint32_t for the given field number.
286 * @param fieldNumber The field number assigned to the values.
287 * @param values The values to write out.
288 * @param tag The tag assigned to the values.
290 - (void)writeUInt32Array:(int32_t)fieldNumber
291 values:(GPBUInt32Array *)values
292 tag:(uint32_t)tag;
294 * Write a uint32_t without any tag.
296 * @param value The value to write out.
298 - (void)writeUInt32NoTag:(uint32_t)value;
301 * Write a uint64_t for the given field number.
303 * @param fieldNumber The field number assigned to the value.
304 * @param value The value to write out.
306 - (void)writeFixed64:(int32_t)fieldNumber value:(uint64_t)value;
308 * Write a packed array of uint64_t for the given field number.
310 * @param fieldNumber The field number assigned to the values.
311 * @param values The values to write out.
312 * @param tag The tag assigned to the values.
314 - (void)writeFixed64Array:(int32_t)fieldNumber
315 values:(GPBUInt64Array *)values
316 tag:(uint32_t)tag;
318 * Write a uint64_t without any tag.
320 * @param value The value to write out.
322 - (void)writeFixed64NoTag:(uint64_t)value;
325 * Write a uint32_t for the given field number.
327 * @param fieldNumber The field number assigned to the value.
328 * @param value The value to write out.
330 - (void)writeFixed32:(int32_t)fieldNumber value:(uint32_t)value;
332 * Write a packed array of uint32_t for the given field number.
334 * @param fieldNumber The field number assigned to the values.
335 * @param values The values to write out.
336 * @param tag The tag assigned to the values.
338 - (void)writeFixed32Array:(int32_t)fieldNumber
339 values:(GPBUInt32Array *)values
340 tag:(uint32_t)tag;
342 * Write a uint32_t without any tag.
344 * @param value The value to write out.
346 - (void)writeFixed32NoTag:(uint32_t)value;
349 * Write a int32_t for the given field number.
351 * @param fieldNumber The field number assigned to the value.
352 * @param value The value to write out.
354 - (void)writeSInt32:(int32_t)fieldNumber value:(int32_t)value;
356 * Write a packed array of int32_t for the given field number.
358 * @param fieldNumber The field number assigned to the values.
359 * @param values The values to write out.
360 * @param tag The tag assigned to the values.
362 - (void)writeSInt32Array:(int32_t)fieldNumber
363 values:(GPBInt32Array *)values
364 tag:(uint32_t)tag;
366 * Write a int32_t without any tag.
368 * @param value The value to write out.
370 - (void)writeSInt32NoTag:(int32_t)value;
373 * Write a int64_t for the given field number.
375 * @param fieldNumber The field number assigned to the value.
376 * @param value The value to write out.
378 - (void)writeSInt64:(int32_t)fieldNumber value:(int64_t)value;
380 * Write a packed array of int64_t for the given field number.
382 * @param fieldNumber The field number assigned to the values.
383 * @param values The values to write out.
384 * @param tag The tag assigned to the values.
386 - (void)writeSInt64Array:(int32_t)fieldNumber
387 values:(GPBInt64Array *)values
388 tag:(uint32_t)tag;
390 * Write a int64_t without any tag.
392 * @param value The value to write out.
394 - (void)writeSInt64NoTag:(int64_t)value;
397 * Write a int64_t for the given field number.
399 * @param fieldNumber The field number assigned to the value.
400 * @param value The value to write out.
402 - (void)writeSFixed64:(int32_t)fieldNumber value:(int64_t)value;
404 * Write a packed array of int64_t for the given field number.
406 * @param fieldNumber The field number assigned to the values.
407 * @param values The values to write out.
408 * @param tag The tag assigned to the values.
410 - (void)writeSFixed64Array:(int32_t)fieldNumber
411 values:(GPBInt64Array *)values
412 tag:(uint32_t)tag;
414 * Write a int64_t without any tag.
416 * @param value The value to write out.
418 - (void)writeSFixed64NoTag:(int64_t)value;
421 * Write a int32_t for the given field number.
423 * @param fieldNumber The field number assigned to the value.
424 * @param value The value to write out.
426 - (void)writeSFixed32:(int32_t)fieldNumber value:(int32_t)value;
428 * Write a packed array of int32_t for the given field number.
430 * @param fieldNumber The field number assigned to the values.
431 * @param values The values to write out.
432 * @param tag The tag assigned to the values.
434 - (void)writeSFixed32Array:(int32_t)fieldNumber
435 values:(GPBInt32Array *)values
436 tag:(uint32_t)tag;
438 * Write a int32_t without any tag.
440 * @param value The value to write out.
442 - (void)writeSFixed32NoTag:(int32_t)value;
445 * Write a BOOL for the given field number.
447 * @param fieldNumber The field number assigned to the value.
448 * @param value The value to write out.
450 - (void)writeBool:(int32_t)fieldNumber value:(BOOL)value;
452 * Write a packed array of BOOL for the given field number.
454 * @param fieldNumber The field number assigned to the values.
455 * @param values The values to write out.
456 * @param tag The tag assigned to the values.
458 - (void)writeBoolArray:(int32_t)fieldNumber
459 values:(GPBBoolArray *)values
460 tag:(uint32_t)tag;
462 * Write a BOOL without any tag.
464 * @param value The value to write out.
466 - (void)writeBoolNoTag:(BOOL)value;
469 * Write a int32_t for the given field number.
471 * @param fieldNumber The field number assigned to the value.
472 * @param value The value to write out.
474 - (void)writeEnum:(int32_t)fieldNumber value:(int32_t)value;
476 * Write a packed array of int32_t for the given field number.
478 * @param fieldNumber The field number assigned to the values.
479 * @param values The values to write out.
480 * @param tag The tag assigned to the values.
482 - (void)writeEnumArray:(int32_t)fieldNumber
483 values:(GPBEnumArray *)values
484 tag:(uint32_t)tag;
486 * Write a int32_t without any tag.
488 * @param value The value to write out.
490 - (void)writeEnumNoTag:(int32_t)value;
493 * Write a NSString for the given field number.
495 * @param fieldNumber The field number assigned to the value.
496 * @param value The value to write out.
498 - (void)writeString:(int32_t)fieldNumber value:(NSString *)value;
500 * Write an array of NSString for the given field number.
502 * @param fieldNumber The field number assigned to the values.
503 * @param values The values to write out.
505 - (void)writeStringArray:(int32_t)fieldNumber
506 values:(NSArray<NSString*> *)values;
508 * Write a NSString without any tag.
510 * @param value The value to write out.
512 - (void)writeStringNoTag:(NSString *)value;
515 * Write a GPBMessage for the given field number.
517 * @param fieldNumber The field number assigned to the value.
518 * @param value The value to write out.
520 - (void)writeMessage:(int32_t)fieldNumber value:(GPBMessage *)value;
522 * Write an array of GPBMessage for the given field number.
524 * @param fieldNumber The field number assigned to the values.
525 * @param values The values to write out.
527 - (void)writeMessageArray:(int32_t)fieldNumber
528 values:(NSArray<GPBMessage*> *)values;
530 * Write a GPBMessage without any tag.
532 * @param value The value to write out.
534 - (void)writeMessageNoTag:(GPBMessage *)value;
537 * Write a NSData for the given field number.
539 * @param fieldNumber The field number assigned to the value.
540 * @param value The value to write out.
542 - (void)writeBytes:(int32_t)fieldNumber value:(NSData *)value;
544 * Write an array of NSData for the given field number.
546 * @param fieldNumber The field number assigned to the values.
547 * @param values The values to write out.
549 - (void)writeBytesArray:(int32_t)fieldNumber
550 values:(NSArray<NSData*> *)values;
552 * Write a NSData without any tag.
554 * @param value The value to write out.
556 - (void)writeBytesNoTag:(NSData *)value;
559 * Write a GPBMessage for the given field number.
561 * @param fieldNumber The field number assigned to the value.
562 * @param value The value to write out.
564 - (void)writeGroup:(int32_t)fieldNumber
565 value:(GPBMessage *)value;
567 * Write an array of GPBMessage for the given field number.
569 * @param fieldNumber The field number assigned to the values.
570 * @param values The values to write out.
572 - (void)writeGroupArray:(int32_t)fieldNumber
573 values:(NSArray<GPBMessage*> *)values;
575 * Write a GPBMessage without any tag (but does write the endGroup tag).
577 * @param fieldNumber The field number assigned to the value.
578 * @param value The value to write out.
580 - (void)writeGroupNoTag:(int32_t)fieldNumber
581 value:(GPBMessage *)value;
583 //%PDDM-EXPAND-END _WRITE_DECLS()
585 // clang-format on
588 Write a MessageSet extension field to the stream. For historical reasons,
589 the wire format differs from normal fields.
591 @param fieldNumber The extension field number to write out.
592 @param value The message from where to get the extension.
594 - (void)writeMessageSetExtension:(int32_t)fieldNumber value:(GPBMessage *)value;
597 Write an unparsed MessageSet extension field to the stream. For historical
598 reasons, the wire format differs from normal fields.
600 @param fieldNumber The extension field number to write out.
601 @param value The raw message from where to get the extension.
603 - (void)writeRawMessageSetExtension:(int32_t)fieldNumber value:(NSData *)value;
605 @end
607 NS_ASSUME_NONNULL_END
609 // Disable clang-format for the macros.
610 // clang-format off
612 // Write methods for types that can be in packed arrays.
613 //%PDDM-DEFINE _WRITE_PACKABLE_DECLS(NAME, ARRAY_TYPE, TYPE)
614 //%/**
615 //% * Write a TYPE for the given field number.
616 //% *
617 //% * @param fieldNumber The field number assigned to the value.
618 //% * @param value The value to write out.
619 //% **/
620 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE)value;
621 //%/**
622 //% * Write a packed array of TYPE for the given field number.
623 //% *
624 //% * @param fieldNumber The field number assigned to the values.
625 //% * @param values The values to write out.
626 //% * @param tag The tag assigned to the values.
627 //% **/
628 //%- (void)write##NAME##Array:(int32_t)fieldNumber
629 //% NAME$S values:(GPB##ARRAY_TYPE##Array *)values
630 //% NAME$S tag:(uint32_t)tag;
631 //%/**
632 //% * Write a TYPE without any tag.
633 //% *
634 //% * @param value The value to write out.
635 //% **/
636 //%- (void)write##NAME##NoTag:(TYPE)value;
638 // Write methods for types that aren't in packed arrays.
639 //%PDDM-DEFINE _WRITE_UNPACKABLE_DECLS(NAME, TYPE)
640 //%/**
641 //% * Write a TYPE for the given field number.
642 //% *
643 //% * @param fieldNumber The field number assigned to the value.
644 //% * @param value The value to write out.
645 //% **/
646 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE *)value;
647 //%/**
648 //% * Write an array of TYPE for the given field number.
649 //% *
650 //% * @param fieldNumber The field number assigned to the values.
651 //% * @param values The values to write out.
652 //% **/
653 //%- (void)write##NAME##Array:(int32_t)fieldNumber
654 //% NAME$S values:(NSArray<##TYPE##*> *)values;
655 //%/**
656 //% * Write a TYPE without any tag.
657 //% *
658 //% * @param value The value to write out.
659 //% **/
660 //%- (void)write##NAME##NoTag:(TYPE *)value;
662 // Special write methods for Groups.
663 //%PDDM-DEFINE _WRITE_GROUP_DECLS(NAME, TYPE)
664 //%/**
665 //% * Write a TYPE for the given field number.
666 //% *
667 //% * @param fieldNumber The field number assigned to the value.
668 //% * @param value The value to write out.
669 //% **/
670 //%- (void)write##NAME:(int32_t)fieldNumber
671 //% NAME$S value:(TYPE *)value;
672 //%/**
673 //% * Write an array of TYPE for the given field number.
674 //% *
675 //% * @param fieldNumber The field number assigned to the values.
676 //% * @param values The values to write out.
677 //% **/
678 //%- (void)write##NAME##Array:(int32_t)fieldNumber
679 //% NAME$S values:(NSArray<##TYPE##*> *)values;
680 //%/**
681 //% * Write a TYPE without any tag (but does write the endGroup tag).
682 //% *
683 //% * @param fieldNumber The field number assigned to the value.
684 //% * @param value The value to write out.
685 //% **/
686 //%- (void)write##NAME##NoTag:(int32_t)fieldNumber
687 //% NAME$S value:(TYPE *)value;
690 // One macro to hide it all up above.
691 //%PDDM-DEFINE _WRITE_DECLS()
692 //%_WRITE_PACKABLE_DECLS(Double, Double, double)
693 //%_WRITE_PACKABLE_DECLS(Float, Float, float)
694 //%_WRITE_PACKABLE_DECLS(UInt64, UInt64, uint64_t)
695 //%_WRITE_PACKABLE_DECLS(Int64, Int64, int64_t)
696 //%_WRITE_PACKABLE_DECLS(Int32, Int32, int32_t)
697 //%_WRITE_PACKABLE_DECLS(UInt32, UInt32, uint32_t)
698 //%_WRITE_PACKABLE_DECLS(Fixed64, UInt64, uint64_t)
699 //%_WRITE_PACKABLE_DECLS(Fixed32, UInt32, uint32_t)
700 //%_WRITE_PACKABLE_DECLS(SInt32, Int32, int32_t)
701 //%_WRITE_PACKABLE_DECLS(SInt64, Int64, int64_t)
702 //%_WRITE_PACKABLE_DECLS(SFixed64, Int64, int64_t)
703 //%_WRITE_PACKABLE_DECLS(SFixed32, Int32, int32_t)
704 //%_WRITE_PACKABLE_DECLS(Bool, Bool, BOOL)
705 //%_WRITE_PACKABLE_DECLS(Enum, Enum, int32_t)
706 //%_WRITE_UNPACKABLE_DECLS(String, NSString)
707 //%_WRITE_UNPACKABLE_DECLS(Message, GPBMessage)
708 //%_WRITE_UNPACKABLE_DECLS(Bytes, NSData)
709 //%_WRITE_GROUP_DECLS(Group, GPBMessage)
711 // clang-format on