Revision control

Line Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
// Copyright 2015-2016 Mozilla Foundation. See the COPYRIGHT
// file at the top-level directory of this distribution.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

// Adapted from third_party/rust/encoding_c/include/encoding_rs_cpp.h, so the
// "top-level directory" in the above notice refers to
// third_party/rust/encoding_c/.

#ifndef mozilla_Encoding_h
#define mozilla_Encoding_h

#include "mozilla/CheckedInt.h"
#include "mozilla/NotNull.h"
#include "mozilla/Span.h"
#include "mozilla/Tuple.h"
#include "nsString.h"

namespace mozilla {
class Encoding;
class Decoder;
class Encoder;
};  // namespace mozilla

#define ENCODING_RS_ENCODING mozilla::Encoding
#define ENCODING_RS_NOT_NULL_CONST_ENCODING_PTR \
  mozilla::NotNull<const mozilla::Encoding*>
#define ENCODING_RS_ENCODER mozilla::Encoder
#define ENCODING_RS_DECODER mozilla::Decoder

#include "encoding_rs.h"

extern "C" {

nsresult mozilla_encoding_decode_to_nsstring(mozilla::Encoding const** encoding,
                                             uint8_t const* src, size_t src_len,
                                             nsAString* dst);

nsresult mozilla_encoding_decode_to_nsstring_with_bom_removal(
    mozilla::Encoding const* encoding, uint8_t const* src, size_t src_len,
    nsAString* dst);

nsresult mozilla_encoding_decode_to_nsstring_without_bom_handling(
    mozilla::Encoding const* encoding, uint8_t const* src, size_t src_len,
    nsAString* dst);

nsresult
mozilla_encoding_decode_to_nsstring_without_bom_handling_and_without_replacement(
    mozilla::Encoding const* encoding, uint8_t const* src, size_t src_len,
    nsAString* dst);

nsresult mozilla_encoding_encode_from_utf16(mozilla::Encoding const** encoding,
                                            char16_t const* src, size_t src_len,
                                            nsACString* dst);

nsresult mozilla_encoding_decode_to_nscstring(
    mozilla::Encoding const** encoding, nsACString const* src, nsACString* dst);

nsresult mozilla_encoding_decode_to_nscstring_with_bom_removal(
    mozilla::Encoding const* encoding, nsACString const* src, nsACString* dst);

nsresult mozilla_encoding_decode_to_nscstring_without_bom_handling(
    mozilla::Encoding const* encoding, nsACString const* src, nsACString* dst);

nsresult mozilla_encoding_decode_from_slice_to_nscstring_without_bom_handling(
    mozilla::Encoding const* encoding, uint8_t const* src, size_t src_len,
    nsACString* dst, size_t already_validated);

nsresult
mozilla_encoding_decode_to_nscstring_without_bom_handling_and_without_replacement(
    mozilla::Encoding const* encoding, nsACString const* src, nsACString* dst);

nsresult mozilla_encoding_encode_from_nscstring(
    mozilla::Encoding const** encoding, nsACString const* src, nsACString* dst);

}  // extern "C"

namespace mozilla {

/**
 * Return value from `Decoder`/`Encoder` to indicate that input
 * was exhausted.
 */
const uint32_t kInputEmpty = INPUT_EMPTY;

/**
 * Return value from `Decoder`/`Encoder` to indicate that output
 * space was insufficient.
 */
const uint32_t kOutputFull = OUTPUT_FULL;

/**
 * An encoding as defined in the Encoding Standard
 * (https://encoding.spec.whatwg.org/).
 *
 * See https://docs.rs/encoding_rs/ for the Rust API docs.
 *
 * An _encoding_ defines a mapping from a byte sequence to a Unicode code point
 * sequence and, in most cases, vice versa. Each encoding has a name, an output
 * encoding, and one or more labels.
 *
 * _Labels_ are ASCII-case-insensitive strings that are used to identify an
 * encoding in formats and protocols. The _name_ of the encoding is the
 * preferred label in the case appropriate for returning from the
 * `characterSet` property of the `Document` DOM interface, except for
 * the replacement encoding whose name is not one of its labels.
 *
 * The _output encoding_ is the encoding used for form submission and URL
 * parsing on Web pages in the encoding. This is UTF-8 for the replacement,
 * UTF-16LE and UTF-16BE encodings and the encoding itself for other
 * encodings.
 *
 * # Streaming vs. Non-Streaming
 *
 * When you have the entire input in a single buffer, you can use the
 * methods `Decode()`, `DecodeWithBOMRemoval()`,
 * `DecodeWithoutBOMHandling()`,
 * `DecodeWithoutBOMHandlingAndWithoutReplacement()` and
 * `Encode()`. Unlike the rest of the API (apart from the `NewDecoder()` and
 * NewEncoder()` methods), these methods perform heap allocations. You should
 * the `Decoder` and `Encoder` objects when your input is split into multiple
 * buffers or when you want to control the allocation of the output buffers.
 *
 * # Instances
 *
 * All instances of `Encoding` are statically allocated and have the process's
 * lifetime. There is precisely one unique `Encoding` instance for each
 * encoding defined in the Encoding Standard.
 *
 * To obtain a reference to a particular encoding whose identity you know at
 * compile time, use a `static` that refers to encoding. There is a `static`
 * for each encoding. The `static`s are named in all caps with hyphens
 * replaced with underscores and with `_ENCODING` appended to the
 * name. For example, if you know at compile time that you will want to
 * decode using the UTF-8 encoding, use the `UTF_8_ENCODING` `static`.
 *
 * If you don't know what encoding you need at compile time and need to
 * dynamically get an encoding by label, use `Encoding::for_label()`.
 *
 * Pointers to `Encoding` can be compared with `==` to check for the sameness
 * of two encodings.
 *
 * A pointer to a `mozilla::Encoding` in C++ is the same thing as a pointer
 * to an `encoding_rs::Encoding` in Rust. When writing FFI code, use
 * `const mozilla::Encoding*` in the C signature and
 * `*const encoding_rs::Encoding` is the corresponding Rust signature.
 */
class Encoding final {
 public:
  /**
   * Implements the _get an encoding_ algorithm
   * (https://encoding.spec.whatwg.org/#concept-encoding-get).
   *
   * If, after ASCII-lowercasing and removing leading and trailing
   * whitespace, the argument matches a label defined in the Encoding
   * Standard, `const Encoding*` representing the corresponding
   * encoding is returned. If there is no match, `nullptr` is returned.
   *
   * This is the right method to use if the action upon the method returning
   * `nullptr` is to use a fallback encoding (e.g. `WINDOWS_1252_ENCODING`)
   * instead. When the action upon the method returning `nullptr` is not to
   * proceed with a fallback but to refuse processing,
   * `ForLabelNoReplacement()` is more appropriate.
   */
  static inline const Encoding* ForLabel(Span<const char> aLabel) {
    return encoding_for_label(
        reinterpret_cast<const uint8_t*>(aLabel.Elements()), aLabel.Length());
  }

  /**
   * `nsAString` argument version. See above for docs.
   */
  static inline const Encoding* ForLabel(const nsAString& aLabel) {
    return Encoding::ForLabel(NS_ConvertUTF16toUTF8(aLabel));
  }

  /**
   * This method behaves the same as `ForLabel()`, except when `ForLabel()`
   * would return `REPLACEMENT_ENCODING`, this method returns `nullptr` instead.
   *
   * This method is useful in scenarios where a fatal error is required
   * upon invalid label, because in those cases the caller typically wishes
   * to treat the labels that map to the replacement encoding as fatal
   * errors, too.
   *
   * It is not OK to use this method when the action upon the method returning
   * `nullptr` is to use a fallback encoding (e.g. `WINDOWS_1252_ENCODING`). In
   * such a case, the `ForLabel()` method should be used instead in order to
   * avoid unsafe fallback for labels that `ForLabel()` maps to
   * `REPLACEMENT_ENCODING`.
   */
  static inline const Encoding* ForLabelNoReplacement(Span<const char> aLabel) {
    return encoding_for_label_no_replacement(
        reinterpret_cast<const uint8_t*>(aLabel.Elements()), aLabel.Length());
  }

  /**
   * `nsAString` argument version. See above for docs.
   */
  static inline const Encoding* ForLabelNoReplacement(const nsAString& aLabel) {
    return Encoding::ForLabelNoReplacement(NS_ConvertUTF16toUTF8(aLabel));
  }

  /**
   * Performs non-incremental BOM sniffing.
   *
   * The argument must either be a buffer representing the entire input
   * stream (non-streaming case) or a buffer representing at least the first
   * three bytes of the input stream (streaming case).
   *
   * Returns `MakeTuple(UTF_8_ENCODING, 3)`, `MakeTuple(UTF_16LE_ENCODING, 2)`
   * or `MakeTuple(UTF_16BE_ENCODING, 3)` if the argument starts with the
   * UTF-8, UTF-16LE or UTF-16BE BOM or `MakeTuple(nullptr, 0)` otherwise.
   */
  static inline Tuple<const Encoding*, size_t> ForBOM(
      Span<const uint8_t> aBuffer) {
    size_t len = aBuffer.Length();
    const Encoding* encoding = encoding_for_bom(aBuffer.Elements(), &len);
    return MakeTuple(encoding, len);
  }

  /**
   * Writes the name of this encoding into `aName`.
   *
   * This name is appropriate to return as-is from the DOM
   * `document.characterSet` property.
   */
  inline void Name(nsACString& aName) const {
    aName.SetLength(ENCODING_NAME_MAX_LENGTH);
    size_t length =
        encoding_name(this, reinterpret_cast<uint8_t*>(aName.BeginWriting()));
    aName.SetLength(length);  // truncation is the 64-bit case is OK
  }

  /**
   * Checks whether the _output encoding_ of this encoding can encode every
   * Unicode code point. (Only true if the output encoding is UTF-8.)
   */
  inline bool CanEncodeEverything() const {
    return encoding_can_encode_everything(this);
  }

  /**
   * Checks whether the bytes 0x00...0x7F map exclusively to the characters
   * U+0000...U+007F and vice versa.
   */
  inline bool IsAsciiCompatible() const {
    return encoding_is_ascii_compatible(this);
  }

  /**
   * Returns the _output encoding_ of this encoding. This is UTF-8 for
   * UTF-16BE, UTF-16LE and replacement and the encoding itself otherwise.
   */
  inline NotNull<const mozilla::Encoding*> OutputEncoding() const {
    return WrapNotNull(encoding_output_encoding(this));
  }

  /**
   * Decode complete input to `nsACString` _with BOM sniffing_ and with
   * malformed sequences replaced with the REPLACEMENT CHARACTER when the
   * entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * This method implements the (non-streaming version of) the
   * _decode_ (https://encoding.spec.whatwg.org/#decode) spec concept.
   *
   * The second item in the returned tuple is the encoding that was actually
   * used (which may differ from this encoding thanks to BOM sniffing).
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise as the first item of the
   * tuple.
   *
   * The backing buffer of the string isn't copied if the input buffer
   * is heap-allocated and decoding from UTF-8 and the input is valid
   * BOMless UTF-8, decoding from an ASCII-compatible encoding and
   * the input is valid ASCII or decoding from ISO-2022-JP and the
   * input stays in the ASCII state of ISO-2022-JP. It is OK to pass
   * the same string as both arguments.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use `NewDecoder()`
   * when decoding segmented input.
   */
  inline Tuple<nsresult, NotNull<const mozilla::Encoding*>> Decode(
      const nsACString& aBytes, nsACString& aOut) const {
    const Encoding* encoding = this;
    const nsACString* bytes = &aBytes;
    nsACString* out = &aOut;
    nsresult rv;
    if (bytes == out) {
      nsAutoCString temp(aBytes);
      rv = mozilla_encoding_decode_to_nscstring(&encoding, &temp, out);
    } else {
      rv = mozilla_encoding_decode_to_nscstring(&encoding, bytes, out);
    }
    return MakeTuple(rv, WrapNotNull(encoding));
  }

  /**
   * Decode complete input to `nsAString` _with BOM sniffing_ and with
   * malformed sequences replaced with the REPLACEMENT CHARACTER when the
   * entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * This method implements the (non-streaming version of) the
   * _decode_ (https://encoding.spec.whatwg.org/#decode) spec concept.
   *
   * The second item in the returned tuple is the encoding that was actually
   * used (which may differ from this encoding thanks to BOM sniffing).
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise as the first item of the
   * tuple.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use `NewDecoder()`
   * when decoding segmented input.
   */
  inline Tuple<nsresult, NotNull<const mozilla::Encoding*>> Decode(
      Span<const uint8_t> aBytes, nsAString& aOut) const {
    const Encoding* encoding = this;
    nsresult rv = mozilla_encoding_decode_to_nsstring(
        &encoding, aBytes.Elements(), aBytes.Length(), &aOut);
    return MakeTuple(rv, WrapNotNull(encoding));
  }

  /**
   * Decode complete input to `nsACString` _with BOM removal_ and with
   * malformed sequences replaced with the REPLACEMENT CHARACTER when the
   * entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode_
   * (https://encoding.spec.whatwg.org/#utf-8-decode) spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise.
   *
   * The backing buffer of the string isn't copied if the input buffer
   * is heap-allocated and decoding from UTF-8 and the input is valid
   * BOMless UTF-8, decoding from an ASCII-compatible encoding and
   * the input is valid ASCII or decoding from ISO-2022-JP and the
   * input stays in the ASCII state of ISO-2022-JP. It is OK to pass
   * the same string as both arguments.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithBOMRemoval()` when decoding segmented input.
   */
  inline nsresult DecodeWithBOMRemoval(const nsACString& aBytes,
                                       nsACString& aOut) const {
    const nsACString* bytes = &aBytes;
    nsACString* out = &aOut;
    if (bytes == out) {
      nsAutoCString temp(aBytes);
      return mozilla_encoding_decode_to_nscstring_with_bom_removal(this, &temp,
                                                                   out);
    }
    return mozilla_encoding_decode_to_nscstring_with_bom_removal(this, bytes,
                                                                 out);
  }

  /**
   * Decode complete input to `nsAString` _with BOM removal_ and with
   * malformed sequences replaced with the REPLACEMENT CHARACTER when the
   * entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode_
   * (https://encoding.spec.whatwg.org/#utf-8-decode) spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithBOMRemoval()` when decoding segmented input.
   */
  inline nsresult DecodeWithBOMRemoval(Span<const uint8_t> aBytes,
                                       nsAString& aOut) const {
    return mozilla_encoding_decode_to_nsstring_with_bom_removal(
        this, aBytes.Elements(), aBytes.Length(), &aOut);
  }

  /**
   * Decode complete input to `nsACString` _without BOM handling_ and
   * with malformed sequences replaced with the REPLACEMENT CHARACTER when
   * the entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode without BOM_
   * (https://encoding.spec.whatwg.org/#utf-8-decode-without-bom) spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise.
   *
   * The backing buffer of the string isn't copied if the input buffer
   * is heap-allocated and decoding from UTF-8 and the input is valid
   * UTF-8, decoding from an ASCII-compatible encoding and the input
   * is valid ASCII or decoding from ISO-2022-JP and the input stays
   * in the ASCII state of ISO-2022-JP. It is OK to pass the same string
   * as both arguments.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithoutBOMHandling()` when decoding segmented input.
   */
  inline nsresult DecodeWithoutBOMHandling(const nsACString& aBytes,
                                           nsACString& aOut) const {
    const nsACString* bytes = &aBytes;
    nsACString* out = &aOut;
    if (bytes == out) {
      nsAutoCString temp(aBytes);
      return mozilla_encoding_decode_to_nscstring_without_bom_handling(
          this, &temp, out);
    }
    return mozilla_encoding_decode_to_nscstring_without_bom_handling(
        this, bytes, out);
  }

  /**
   * Decode complete input to `nsAString` _without BOM handling_ and
   * with malformed sequences replaced with the REPLACEMENT CHARACTER when
   * the entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode without BOM_
   * (https://encoding.spec.whatwg.org/#utf-8-decode-without-bom) spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithoutBOMHandling()` when decoding segmented input.
   */
  inline nsresult DecodeWithoutBOMHandling(Span<const uint8_t> aBytes,
                                           nsAString& aOut) const {
    return mozilla_encoding_decode_to_nsstring_without_bom_handling(
        this, aBytes.Elements(), aBytes.Length(), &aOut);
  }

  /**
   * Decode complete input to `nsACString` _without BOM handling_ and
   * _with malformed sequences treated as fatal_ when the entire input is
   * available as a single buffer (i.e. the end of the buffer marks the end
   * of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode without BOM or fail_
   * (https://encoding.spec.whatwg.org/#utf-8-decode-without-bom-or-fail)
   * spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_ERROR_UDEC_ILLEGALINPUT`
   * if a malformed sequence was encountered and `NS_OK` otherwise.
   *
   * The backing buffer of the string isn't copied if the input buffer
   * is heap-allocated and decoding from UTF-8 and the input is valid
   * UTF-8, decoding from an ASCII-compatible encoding and the input
   * is valid ASCII or decoding from ISO-2022-JP and the input stays
   * in the ASCII state of ISO-2022-JP. It is OK to pass the same string
   * as both arguments.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithoutBOMHandling()` when decoding segmented input.
   */
  inline nsresult DecodeWithoutBOMHandlingAndWithoutReplacement(
      const nsACString& aBytes, nsACString& aOut) const {
    const nsACString* bytes = &aBytes;
    nsACString* out = &aOut;
    if (bytes == out) {
      nsAutoCString temp(aBytes);
      return mozilla_encoding_decode_to_nscstring_without_bom_handling_and_without_replacement(
          this, &temp, out);
    }
    return mozilla_encoding_decode_to_nscstring_without_bom_handling_and_without_replacement(
        this, bytes, out);
  }

  /**
   * Decode complete input to `nsACString` _without BOM handling_ and
   * with malformed sequences replaced with the REPLACEMENT CHARACTER when
   * the entire input is available as a single buffer (i.e. the end of the
   * buffer marks the end of the stream) _asserting that a number of bytes
   * from the start are already known to be valid UTF-8_.
   *
   * The use case for this method is avoiding copying when dealing with
   * input that has a UTF-8 BOM. _When in doubt, do not use this method._
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode without BOM_
   * (https://encoding.spec.whatwg.org/#utf-8-decode-without-bom) spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_OK_HAD_REPLACEMENTS`
   * if there were malformed sequences (that were replaced with the
   * REPLACEMENT CHARACTER) and `NS_OK` otherwise.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithoutBOMHandling()` when decoding segmented input.
   *
   * # Safety
   *
   * The first `aAlreadyValidated` bytes of `aBytes` _must_ be valid UTF-8.
   * `aBytes` _must not_ alias the buffer (if any) of `aOut`.
   */
  inline nsresult DecodeWithoutBOMHandling(Span<const uint8_t> aBytes,
                                           nsACString& aOut,
                                           size_t aAlreadyValidated) const {
    return mozilla_encoding_decode_from_slice_to_nscstring_without_bom_handling(
        this, aBytes.Elements(), aBytes.Length(), &aOut, aAlreadyValidated);
  }

  /**
   * Decode complete input to `nsAString` _without BOM handling_ and
   * _with malformed sequences treated as fatal_ when the entire input is
   * available as a single buffer (i.e. the end of the buffer marks the end
   * of the stream).
   *
   * When invoked on `UTF_8`, this method implements the (non-streaming
   * version of) the _UTF-8 decode without BOM or fail_
   * (https://encoding.spec.whatwg.org/#utf-8-decode-without-bom-or-fail)
   * spec concept.
   *
   * Returns `NS_ERROR_OUT_OF_MEMORY` upon OOM, `NS_ERROR_UDEC_ILLEGALINPUT`
   * if a malformed sequence was encountered and `NS_OK` otherwise.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use
   * `NewDecoderWithoutBOMHandling()` when decoding segmented input.
   */
  inline nsresult DecodeWithoutBOMHandlingAndWithoutReplacement(
      Span<const uint8_t> aBytes, nsAString& aOut) const {
    return mozilla_encoding_decode_to_nsstring_without_bom_handling_and_without_replacement(
        this, aBytes.Elements(), aBytes.Length(), &aOut);
  }

  /**
   * Encode complete input to `nsACString` with unmappable characters
   * replaced with decimal numeric character references when the entire input
   * is available as a single buffer (i.e. the end of the buffer marks the
   * end of the stream).
   *
   * This method implements the (non-streaming version of) the
   * _encode_ (https://encoding.spec.whatwg.org/#encode) spec concept.
   *
   * The second item in the returned tuple is the encoding that was actually
   * used (which may differ from this encoding thanks to some encodings
   * having UTF-8 as their output encoding).
   *
   * The first item of the returned tuple is `NS_ERROR_UDEC_ILLEGALINPUT` if
   * the input is not valid UTF-8, `NS_ERROR_OUT_OF_MEMORY` upon OOM,
   * `NS_OK_HAD_REPLACEMENTS` if there were unmappable code points (that were
   * replaced with numeric character references) and `NS_OK` otherwise.
   *
   * The backing buffer of the string isn't copied if the input buffer
   * is heap-allocated and encoding to UTF-8 and the input is valid
   * UTF-8, encoding to an ASCII-compatible encoding and the input
   * is valid ASCII or encoding from ISO-2022-JP and the input stays
   * in the ASCII state of ISO-2022-JP. It is OK to pass the same string
   * as both arguments.
   *
   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use `NewEncoder()`
   * when encoding segmented output.
   */
  inline Tuple<nsresult, NotNull<const mozilla::Encoding*>> Encode(
      const nsACString& aString, nsACString& aOut) const {
    const Encoding* encoding = this;
    const nsACString* string = &aString;
    nsACString* out = &aOut;
    nsresult rv;
    if (string == out) {
      nsAutoCString temp(aString);
      rv = mozilla_encoding_encode_from_nscstring(&encoding, &temp, out);
    } else {
      rv = mozilla_encoding_encode_from_nscstring(&encoding, string, out);
    }
    return MakeTuple(rv, WrapNotNull(encoding));
  }

  /**
   * Encode complete input to `nsACString` with unmappable characters
   * replaced with decimal numeric character references when the entire input
   * is available as a single buffer (i.e. the end of the buffer marks the
   * end of the stream).
   *
   * This method implements the (non-streaming version of) the
   * _encode_ (https://encoding.spec.whatwg.org/#encode) spec concept.
   *
   * The second item in the returned tuple is the encoding that was actually
   * used (which may differ from this encoding thanks to some encodings
   * having UTF-8 as their output encoding).
   *
   * The first item of the returned tuple is `NS_ERROR_OUT_OF_MEMORY` upon
   * OOM, `NS_OK_HAD_REPLACEMENTS` if there were unmappable code points (that
   * were replaced with numeric character references) and `NS_OK` otherwise.

   * _Note:_ It is wrong to use this when the input buffer represents only
   * a segment of the input instead of the whole input. Use `NewEncoder()`
   * when encoding segmented output.
   */
  inline Tuple<nsresult, NotNull<const mozilla::Encoding*>> Encode(
      Span<const char16_t> aString, nsACString& aOut) const {
    const Encoding* encoding = this;
    nsresult rv = mozilla_encoding_encode_from_utf16(
        &encoding, aString.Elements(), aString.Length(), &aOut);
    return MakeTuple(rv, WrapNotNull(encoding));
  }

  /**
   * Instantiates a new decoder for this encoding with BOM sniffing enabled.
   *
   * BOM sniffing may cause the returned decoder to morph into a decoder
   * for UTF-8, UTF-16LE or UTF-16BE instead of this encoding.
   */
  inline UniquePtr<Decoder> NewDecoder() const {
    UniquePtr<Decoder> decoder(encoding_new_decoder(this));
    return decoder;
  }

  /**
   * Instantiates a new decoder for this encoding with BOM sniffing enabled
   * into memory occupied by a previously-instantiated decoder.
   *
   * BOM sniffing may cause the returned decoder to morph into a decoder
   * for UTF-8, UTF-16LE or UTF-16BE instead of this encoding.
   */
  inline void NewDecoderInto(Decoder& aDecoder) const {
    encoding_new_decoder_into(this, &aDecoder);
  }

  /**
   * Instantiates a new decoder for this encoding with BOM removal.
   *
   * If the input starts with bytes that are the BOM for this encoding,
   * those bytes are removed. However, the decoder never morphs into a
   * decoder for another encoding: A BOM for another encoding is treated as
   * (potentially malformed) input to the decoding algorithm for this
   * encoding.
   */
  inline UniquePtr<Decoder> NewDecoderWithBOMRemoval() const {
    UniquePtr<Decoder> decoder(encoding_new_decoder_with_bom_removal(this));
    return decoder;
  }

  /**
   * Instantiates a new decoder for this encoding with BOM removal
   * into memory occupied by a previously-instantiated decoder.
   *
   * If the input starts with bytes that are the BOM for this encoding,
   * those bytes are removed. However, the decoder never morphs into a
   * decoder for another encoding: A BOM for another encoding is treated as
   * (potentially malformed) input to the decoding algorithm for this
   * encoding.
   */
  inline void NewDecoderWithBOMRemovalInto(Decoder& aDecoder) const {
    encoding_new_decoder_with_bom_removal_into(this, &aDecoder);
  }

  /**
   * Instantiates a new decoder for this encoding with BOM handling disabled.
   *
   * If the input starts with bytes that look like a BOM, those bytes are
   * not treated as a BOM. (Hence, the decoder never morphs into a decoder
   * for another encoding.)
   *
   * _Note:_ If the caller has performed BOM sniffing on its own but has not
   * removed the BOM, the caller should use `NewDecoderWithBOMRemoval()`
   * instead of this method to cause the BOM to be removed.
   */
  inline UniquePtr<Decoder> NewDecoderWithoutBOMHandling() const {
    UniquePtr<Decoder> decoder(encoding_new_decoder_without_bom_handling(this));
    return decoder;
  }

  /**
   * Instantiates a new decoder for this encoding with BOM handling disabled
   * into memory occupied by a previously-instantiated decoder.
   *
   * If the input starts with bytes that look like a BOM, those bytes are
   * not treated as a BOM. (Hence, the decoder never morphs into a decoder
   * for another encoding.)
   *
   * _Note:_ If the caller has performed BOM sniffing on its own but has not
   * removed the BOM, the caller should use `NewDecoderWithBOMRemovalInto()`
   * instead of this method to cause the BOM to be removed.
   */
  inline void NewDecoderWithoutBOMHandlingInto(Decoder& aDecoder) const {
    encoding_new_decoder_without_bom_handling_into(this, &aDecoder);
  }

  /**
   * Instantiates a new encoder for the output encoding of this encoding.
   */
  inline UniquePtr<Encoder> NewEncoder() const {
    UniquePtr<Encoder> encoder(encoding_new_encoder(this));
    return encoder;
  }

  /**
   * Instantiates a new encoder for the output encoding of this encoding
   * into memory occupied by a previously-instantiated encoder.
   */
  inline void NewEncoderInto(Encoder& aEncoder) const {
    encoding_new_encoder_into(this, &aEncoder);
  }

  /**
   * Validates UTF-8.
   *
   * Returns the index of the first byte that makes the input malformed as
   * UTF-8 or the length of the input if the input is entirely valid.
   */
  static inline size_t UTF8ValidUpTo(Span<const uint8_t> aBuffer) {
    return encoding_utf8_valid_up_to(aBuffer.Elements(), aBuffer.Length());
  }

  /**
   * Validates ASCII.
   *
   * Returns the index of the first byte that makes the input malformed as
   * ASCII or the length of the input if the input is entirely valid.
   */
  static inline size_t ASCIIValidUpTo(Span<const uint8_t> aBuffer) {
    return encoding_ascii_valid_up_to(aBuffer.Elements(), aBuffer.Length());
  }

  /**
   * Validates ISO-2022-JP ASCII-state data.
   *
   * Returns the index of the first byte that makes the input not
   * representable in the ASCII state of ISO-2022-JP or the length of the
   * input if the input is entirely representable in the ASCII state of
   * ISO-2022-JP.
   */
  static inline size_t ISO2022JPASCIIValidUpTo(Span<const uint8_t> aBuffer) {
    return encoding_iso_2022_jp_ascii_valid_up_to(aBuffer.Elements(),
                                                  aBuffer.Length());
  }

 private:
  Encoding() = delete;
  Encoding(const Encoding&) = delete;
  Encoding& operator=(const Encoding&) = delete;
  ~Encoding() = delete;
};

/**
 * A converter that decodes a byte stream into Unicode according to a
 * character encoding in a streaming (incremental) manner.
 *
 * The various `Decode*` methods take an input buffer (`aSrc`) and an output
 * buffer `aDst` both of which are caller-allocated. There are variants for
 * both UTF-8 and UTF-16 output buffers.
 *
 * A `Decode*` method decodes bytes from `aSrc` into Unicode characters stored
 * into `aDst` until one of the following three things happens:
 *
 * 1. A malformed byte sequence is encountered (`*WithoutReplacement`
 *    variants only).
 *
 * 2. The output buffer has been filled so near capacity that the decoder
 *    cannot be sure that processing an additional byte of input wouldn't
 *    cause so much output that the output buffer would overflow.
 *
 * 3. All the input bytes have been processed.
 *
 * The `Decode*` method then returns tuple of a status indicating which one
 * of the three reasons to return happened, how many input bytes were read,
 * how many output code units (`uint8_t` when decoding into UTF-8 and `char16_t`
 * when decoding to UTF-16) were written, and in the case of the
 * variants performing replacement, a boolean indicating whether an error was
 * replaced with the REPLACEMENT CHARACTER during the call.
 *
 * The number of bytes "written" is what's logically written. Garbage may be
 * written in the output buffer beyond the point logically written to.
 *
 * In the case of the `*WithoutReplacement` variants, the status is a
 * `uint32_t` whose possible values are packed info about a malformed byte
 * sequence, `kOutputFull` and `kInputEmpty` corresponding to the three cases
 * listed above).
 *
 * Packed info about malformed sequences has the following format:
 * The lowest 8 bits, which can have the decimal value 0, 1, 2 or 3,
 * indicate the number of bytes that were consumed after the malformed
 * sequence and whose next-lowest 8 bits, when shifted right by 8 indicate
 * the length of the malformed byte sequence (possible decimal values 1, 2,
 * 3 or 4). The maximum possible sum of the two is 6.
 *
 * In the case of methods whose name does not end with
 * `*WithoutReplacement`, malformed sequences are automatically replaced
 * with the REPLACEMENT CHARACTER and errors do not cause the methods to
 * return early.
 *
 * When decoding to UTF-8, the output buffer must have at least 4 bytes of
 * space. When decoding to UTF-16, the output buffer must have at least two
 * UTF-16 code units (`char16_t`) of space.
 *
 * When decoding to UTF-8 without replacement, the methods are guaranteed
 * not to return indicating that more output space is needed if the length
 * of the output buffer is at least the length returned by
 * `MaxUTF8BufferLengthWithoutReplacement()`. When decoding to UTF-8
 * with replacement, the length of the output buffer that guarantees the
 * methods not to return indicating that more output space is needed is given
 * by `MaxUTF8BufferLength()`. When decoding to UTF-16 with
 * or without replacement, the length of the output buffer that guarantees
 * the methods not to return indicating that more output space is needed is
 * given by `MaxUTF16BufferLength()`.
 *
 * The output written into `aDst` is guaranteed to be valid UTF-8 or UTF-16,
 * and the output after each `Decode*` call is guaranteed to consist of
 * complete characters. (I.e. the code unit sequence for the last character is
 * guaranteed not to be split across output buffers.)
 *
 * The boolean argument `aLast` indicates that the end of the stream is reached
 * when all the bytes in `aSrc` have been consumed.
 *
 * A `Decoder` object can be used to incrementally decode a byte stream.
 *
 * During the processing of a single stream, the caller must call `Decode*`
 * zero or more times with `aLast` set to `false` and then call `Decode*` at
 * least once with `aLast` set to `true`. If `Decode*` returns `kInputEmpty`,
 * the processing of the stream has ended. Otherwise, the caller must call
 * `Decode*` again with `aLast` set to `true` (or treat a malformed result,
 * i.e. neither `kInputEmpty` nor `kOutputFull`, as a fatal error).
 *
 * Once the stream has ended, the `Decoder` object must not be used anymore.
 * That is, you need to create another one to process another stream.
 *
 * When the decoder returns `kOutputFull` or the decoder returns a malformed
 * result and the caller does not wish to treat it as a fatal error, the input
 * buffer `aSrc` may not have been completely consumed. In that case, the caller
 * must pass the unconsumed contents of `aSrc` to `Decode*` again upon the next
 * call.
 *
 * # Infinite loops
 *
 * When converting with a fixed-size output buffer whose size is too small to
 * accommodate one character of output, an infinite loop ensues. When
 * converting with a fixed-size output buffer, it generally makes sense to
 * make the buffer fairly large (e.g. couple of kilobytes).
 */
class Decoder final {
 public:
  ~Decoder() {}
  static void operator delete(void* aDecoder) {
    decoder_free(reinterpret_cast<Decoder*>(aDecoder));
  }

  /**
   * The `Encoding` this `Decoder` is for.
   *
   * BOM sniffing can change the return value of this method during the life
   * of the decoder.
   */
  inline NotNull<const mozilla::Encoding*> Encoding() const {
    return WrapNotNull(decoder_encoding(this));
  }

  /**
   * Query the worst-case UTF-8 output size _with replacement_.
   *
   * Returns the size of the output buffer in UTF-8 code units (`uint8_t`)
   * that will not overflow given the current state of the decoder and
   * `aByteLength` number of additional input bytes when decoding with
   * errors handled by outputting a REPLACEMENT CHARACTER for each malformed
   * sequence.
   */
  inline CheckedInt<size_t> MaxUTF8BufferLength(size_t aByteLength) const {
    CheckedInt<size_t> max(decoder_max_utf8_buffer_length(this, aByteLength));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Query the worst-case UTF-8 output size _without replacement_.
   *
   * Returns the size of the output buffer in UTF-8 code units (`uint8_t`)
   * that will not overflow given the current state of the decoder and
   * `aByteLength` number of additional input bytes when decoding without
   * replacement error handling.
   *
   * Note that this value may be too small for the `WithReplacement` case.
   * Use `MaxUTF8BufferLength()` for that case.
   */
  inline CheckedInt<size_t> MaxUTF8BufferLengthWithoutReplacement(
      size_t aByteLength) const {
    CheckedInt<size_t> max(
        decoder_max_utf8_buffer_length_without_replacement(this, aByteLength));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Incrementally decode a byte stream into UTF-8 with malformed sequences
   * replaced with the REPLACEMENT CHARACTER.
   *
   * See the documentation of the class for documentation for `Decode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t, bool> DecodeToUTF8(
      Span<const uint8_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    bool hadReplacements;
    uint32_t result =
        decoder_decode_to_utf8(this, aSrc.Elements(), &srcRead, aDst.Elements(),
                               &dstWritten, aLast, &hadReplacements);
    return MakeTuple(result, srcRead, dstWritten, hadReplacements);
  }

  /**
   * Incrementally decode a byte stream into UTF-8 _without replacement_.
   *
   * See the documentation of the class for documentation for `Decode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t> DecodeToUTF8WithoutReplacement(
      Span<const uint8_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    uint32_t result = decoder_decode_to_utf8_without_replacement(
        this, aSrc.Elements(), &srcRead, aDst.Elements(), &dstWritten, aLast);
    return MakeTuple(result, srcRead, dstWritten);
  }

  /**
   * Query the worst-case UTF-16 output size (with or without replacement).
   *
   * Returns the size of the output buffer in UTF-16 code units (`char16_t`)
   * that will not overflow given the current state of the decoder and
   * `aByteLength` number of additional input bytes.
   *
   * Since the REPLACEMENT CHARACTER fits into one UTF-16 code unit, the
   * return value of this method applies also in the
   * `_without_replacement` case.
   */
  inline CheckedInt<size_t> MaxUTF16BufferLength(size_t aU16Length) const {
    CheckedInt<size_t> max(decoder_max_utf16_buffer_length(this, aU16Length));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Incrementally decode a byte stream into UTF-16 with malformed sequences
   * replaced with the REPLACEMENT CHARACTER.
   *
   * See the documentation of the class for documentation for `Decode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t, bool> DecodeToUTF16(
      Span<const uint8_t> aSrc, Span<char16_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    bool hadReplacements;
    uint32_t result = decoder_decode_to_utf16(this, aSrc.Elements(), &srcRead,
                                              aDst.Elements(), &dstWritten,
                                              aLast, &hadReplacements);
    return MakeTuple(result, srcRead, dstWritten, hadReplacements);
  }

  /**
   * Incrementally decode a byte stream into UTF-16 _without replacement_.
   *
   * See the documentation of the class for documentation for `Decode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t> DecodeToUTF16WithoutReplacement(
      Span<const uint8_t> aSrc, Span<char16_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    uint32_t result = decoder_decode_to_utf16_without_replacement(
        this, aSrc.Elements(), &srcRead, aDst.Elements(), &dstWritten, aLast);
    return MakeTuple(result, srcRead, dstWritten);
  }

 private:
  Decoder() = delete;
  Decoder(const Decoder&) = delete;
  Decoder& operator=(const Decoder&) = delete;
};

/**
 * A converter that encodes a Unicode stream into bytes according to a
 * character encoding in a streaming (incremental) manner.
 *
 * The various `Encode*` methods take an input buffer (`aSrc`) and an output
 * buffer `aDst` both of which are caller-allocated. There are variants for
 * both UTF-8 and UTF-16 input buffers.
 *
 * An `Encode*` method encode characters from `aSrc` into bytes characters
 * stored into `aDst` until one of the following three things happens:
 *
 * 1. An unmappable character is encountered (`*WithoutReplacement` variants
 *    only).
 *
 * 2. The output buffer has been filled so near capacity that the decoder
 *    cannot be sure that processing an additional character of input wouldn't
 *    cause so much output that the output buffer would overflow.
 *
 * 3. All the input characters have been processed.
 *
 * The `Encode*` method then returns tuple of a status indicating which one
 * of the three reasons to return happened, how many input code units (`uint8_t`
 * when encoding from UTF-8 and `char16_t` when encoding from UTF-16) were read,
 * how many output bytes were written, and in the case of the variants that
 * perform replacement, a boolean indicating whether an unmappable
 * character was replaced with a numeric character reference during the call.
 *
 * The number of bytes "written" is what's logically written. Garbage may be
 * written in the output buffer beyond the point logically written to.
 *
 * In the case of the methods whose name ends with
 * `*WithoutReplacement`, the status is a `uint32_t` whose possible values
 * are an unmappable code point, `kOutputFull` and `kInputEmpty` corresponding
 * to the three cases listed above).
 *
 * In the case of methods whose name does not end with
 * `*WithoutReplacement`, unmappable characters are automatically replaced
 * with the corresponding numeric character references and unmappable
 * characters do not cause the methods to return early.
 *
 * When encoding from UTF-8 without replacement, the methods are guaranteed
 * not to return indicating that more output space is needed if the length
 * of the output buffer is at least the length returned by
 * `MaxBufferLengthFromUTF8WithoutReplacement()`. When encoding from
 * UTF-8 with replacement, the length of the output buffer that guarantees the
 * methods not to return indicating that more output space is needed in the
 * absence of unmappable characters is given by
 * `MaxBufferLengthFromUTF8IfNoUnmappables()`. When encoding from
 * UTF-16 without replacement, the methods are guaranteed not to return
 * indicating that more output space is needed if the length of the output
 * buffer is at least the length returned by
 * `MaxBufferLengthFromUTF16WithoutReplacement()`. When encoding
 * from UTF-16 with replacement, the the length of the output buffer that
 * guarantees the methods not to return indicating that more output space is
 * needed in the absence of unmappable characters is given by
 * `MaxBufferLengthFromUTF16IfNoUnmappables()`.
 * When encoding with replacement, applications are not expected to size the
 * buffer for the worst case ahead of time but to resize the buffer if there
 * are unmappable characters. This is why max length queries are only available
 * for the case where there are no unmappable characters.
 *
 * When encoding from UTF-8, each `aSrc` buffer _must_ be valid UTF-8. When
 * encoding from UTF-16, unpaired surrogates in the input are treated as U+FFFD
 * REPLACEMENT CHARACTERS. Therefore, in order for astral characters not to
 * turn into a pair of REPLACEMENT CHARACTERS, the caller must ensure that
 * surrogate pairs are not split across input buffer boundaries.
 *
 * After an `Encode*` call returns, the output produced so far, taken as a
 * whole from the start of the stream, is guaranteed to consist of a valid
 * byte sequence in the target encoding. (I.e. the code unit sequence for a
 * character is guaranteed not to be split across output buffers. However, due
 * to the stateful nature of ISO-2022-JP, the stream needs to be considered
 * from the start for it to be valid. For other encodings, the validity holds
 * on a per-output buffer basis.)
 *
 * The boolean argument `aLast` indicates that the end of the stream is reached
 * when all the characters in `aSrc` have been consumed. This argument is needed
 * for ISO-2022-JP and is ignored for other encodings.
 *
 * An `Encoder` object can be used to incrementally encode a byte stream.
 *
 * During the processing of a single stream, the caller must call `Encode*`
 * zero or more times with `aLast` set to `false` and then call `Encode*` at
 * least once with `aLast` set to `true`. If `Encode*` returns `kInputEmpty`,
 * the processing of the stream has ended. Otherwise, the caller must call
 * `Encode*` again with `aLast` set to `true` (or treat an unmappable result,
 * i.e. neither `kInputEmpty` nor `kOutputFull`, as a fatal error).
 *
 * Once the stream has ended, the `Encoder` object must not be used anymore.
 * That is, you need to create another one to process another stream.
 *
 * When the encoder returns `kOutputFull` or the encoder returns an unmappable
 * result and the caller does not wish to treat it as a fatal error, the input
 * buffer `aSrc` may not have been completely consumed. In that case, the caller
 * must pass the unconsumed contents of `aSrc` to `Encode*` again upon the next
 * call.
 *
 * # Infinite loops
 *
 * When converting with a fixed-size output buffer whose size is too small to
 * accommodate one character of output, an infinite loop ensues. When
 * converting with a fixed-size output buffer, it generally makes sense to
 * make the buffer fairly large (e.g. couple of kilobytes).
 */
class Encoder final {
 public:
  ~Encoder() {}

  static void operator delete(void* aEncoder) {
    encoder_free(reinterpret_cast<Encoder*>(aEncoder));
  }

  /**
   * The `Encoding` this `Encoder` is for.
   */
  inline NotNull<const mozilla::Encoding*> Encoding() const {
    return WrapNotNull(encoder_encoding(this));
  }

  /**
   * Returns `true` if this is an ISO-2022-JP encoder that's not in the
   * ASCII state and `false` otherwise.
   */
  inline bool HasPendingState() const {
    return encoder_has_pending_state(this);
  }

  /**
   * Query the worst-case output size when encoding from UTF-8 with
   * replacement.
   *
   * Returns the size of the output buffer in bytes that will not overflow
   * given the current state of the encoder and `aByteLength` number of
   * additional input code units if there are no unmappable characters in
   * the input.
   */
  inline CheckedInt<size_t> MaxBufferLengthFromUTF8IfNoUnmappables(
      size_t aByteLength) const {
    CheckedInt<size_t> max(
        encoder_max_buffer_length_from_utf8_if_no_unmappables(this,
                                                              aByteLength));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Query the worst-case output size when encoding from UTF-8 without
   * replacement.
   *
   * Returns the size of the output buffer in bytes that will not overflow
   * given the current state of the encoder and `aByteLength` number of
   * additional input code units.
   */
  inline CheckedInt<size_t> MaxBufferLengthFromUTF8WithoutReplacement(
      size_t aByteLength) const {
    CheckedInt<size_t> max(
        encoder_max_buffer_length_from_utf8_without_replacement(this,
                                                                aByteLength));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Incrementally encode into byte stream from UTF-8 with unmappable
   * characters replaced with HTML (decimal) numeric character references.
   *
   * See the documentation of the class for documentation for `Encode*`
   * methods collectively.
   *
   * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING:
   * The input ***MUST*** be valid UTF-8 or bad things happen! Unless
   * absolutely sure, use `Encoding::UTF8ValidUpTo()` to check.
   */
  inline Tuple<uint32_t, size_t, size_t, bool> EncodeFromUTF8(
      Span<const uint8_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    bool hadReplacements;
    uint32_t result = encoder_encode_from_utf8(this, aSrc.Elements(), &srcRead,
                                               aDst.Elements(), &dstWritten,
                                               aLast, &hadReplacements);
    return MakeTuple(result, srcRead, dstWritten, hadReplacements);
  }

  /**
   * Incrementally encode into byte stream from UTF-8 _without replacement_.
   *
   * See the documentation of the class for documentation for `Encode*`
   * methods collectively.
   *
   * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING:
   * The input ***MUST*** be valid UTF-8 or bad things happen! Unless
   * absolutely sure, use `Encoding::UTF8ValidUpTo()` to check.
   */
  inline Tuple<uint32_t, size_t, size_t> EncodeFromUTF8WithoutReplacement(
      Span<const uint8_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    uint32_t result = encoder_encode_from_utf8_without_replacement(
        this, aSrc.Elements(), &srcRead, aDst.Elements(), &dstWritten, aLast);
    return MakeTuple(result, srcRead, dstWritten);
  }

  /**
   * Query the worst-case output size when encoding from UTF-16 with
   * replacement.
   *
   * Returns the size of the output buffer in bytes that will not overflow
   * given the current state of the encoder and `aU16Length` number of
   * additional input code units if there are no unmappable characters in
   * the input.
   */
  inline CheckedInt<size_t> MaxBufferLengthFromUTF16IfNoUnmappables(
      size_t aU16Length) const {
    CheckedInt<size_t> max(
        encoder_max_buffer_length_from_utf16_if_no_unmappables(this,
                                                               aU16Length));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Query the worst-case output size when encoding from UTF-16 without
   * replacement.
   *
   * Returns the size of the output buffer in bytes that will not overflow
   * given the current state of the encoder and `aU16Length` number of
   * additional input code units.
   */
  inline CheckedInt<size_t> MaxBufferLengthFromUTF16WithoutReplacement(
      size_t aU16Length) const {
    CheckedInt<size_t> max(
        encoder_max_buffer_length_from_utf16_without_replacement(this,
                                                                 aU16Length));
    if (max.value() == MaxValue<size_t>::value) {
      // Mark invalid by overflowing
      max++;
      MOZ_ASSERT(!max.isValid());
    }
    return max;
  }

  /**
   * Incrementally encode into byte stream from UTF-16 with unmappable
   * characters replaced with HTML (decimal) numeric character references.
   *
   * See the documentation of the class for documentation for `Encode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t, bool> EncodeFromUTF16(
      Span<const char16_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    bool hadReplacements;
    uint32_t result = encoder_encode_from_utf16(this, aSrc.Elements(), &srcRead,
                                                aDst.Elements(), &dstWritten,
                                                aLast, &hadReplacements);
    return MakeTuple(result, srcRead, dstWritten, hadReplacements);
  }

  /**
   * Incrementally encode into byte stream from UTF-16 _without replacement_.
   *
   * See the documentation of the class for documentation for `Encode*`
   * methods collectively.
   */
  inline Tuple<uint32_t, size_t, size_t> EncodeFromUTF16WithoutReplacement(
      Span<const char16_t> aSrc, Span<uint8_t> aDst, bool aLast) {
    size_t srcRead = aSrc.Length();
    size_t dstWritten = aDst.Length();
    uint32_t result = encoder_encode_from_utf16_without_replacement(
        this, aSrc.Elements(), &srcRead, aDst.Elements(), &dstWritten, aLast);
    return MakeTuple(result, srcRead, dstWritten);
  }

 private:
  Encoder() = delete;
  Encoder(const Encoder&) = delete;
  Encoder& operator=(const Encoder&) = delete;
};

};  // namespace mozilla

#endif  // mozilla_Encoding_h