-
Notifications
You must be signed in to change notification settings - Fork 0
/
RJCP.SerialPortStream.xml
18858 lines (18857 loc) · 900 KB
/
RJCP.SerialPortStream.xml
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
<?xml version="1.0"?>
<doc>
<assembly>
<name>RJCP.SerialPortStream</name>
</assembly>
<members>
<member name="T:RJCP.Datastructures.ReusableList`1">
<summary>
Array of elements which can be reused.
</summary>
<typeparam name="T">The element type that is to be kept.</typeparam>
<remarks>
Behave like a list, that when we convert to an array we don't allocate new
objects on the heap like List{T}.
</remarks>
</member>
<member name="T:RJCP.Datastructures.CircularBuffer`1">
<summary>
A simple data structure to manage an array as a circular buffer.
</summary>
<remarks>
This class provides simple methods for abstracting a circular buffer. A circular buffer allows for faster access
of data by avoiding potential copy operations for data that is at the beginning.
<para>
Stream data structures can benefit from this data structure by allocating a single block on the heap of an
arbitrary size. If the stream is long-lived the benefits are larger. In the .NET framework (4.0 and earlier),
all allocations of data structures that are 80kb and larger are automatically allocated on the heap. The heap is
not garbage collected like smaller objects. Instead, new elements are added to the heap in an incremental
fashion. It is theoretically possible to exhaust all memory in an application by allocating and deallocating
regularly on a heap if such a new heap element requires space and there is not a single block large enough. By
using the <see cref="T:RJCP.Datastructures.CircularBuffer`1"/> with the type <c>T</c> as <c>byte</c>, you can preallocate a buffer
for a stream of any reasonable size (as a simple example 5MB). That block is allocated once and remains for the
lifetime of the stream. No time will be allocated for compacting or garbage collection.
</para>
</remarks>
<typeparam name="T">Type to use for the array.</typeparam>
</member>
<member name="F:RJCP.Datastructures.CircularBuffer`1.m_Array">
<summary>
Circular buffer itself. Exposed by property "Array".
</summary>
</member>
<member name="F:RJCP.Datastructures.CircularBuffer`1.m_Start">
<summary>
Start index into the buffer. Exposed by property "Start".
</summary>
</member>
<member name="F:RJCP.Datastructures.CircularBuffer`1.m_Count">
<summary>
Length of data in circular buffer. Exposed by property "Length".
</summary>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.#ctor(System.Int32)">
<summary>
Allocate an Array of type T[] of particular capacity.
</summary>
<param name="capacity">Size of array to allocate.</param>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="capacity"/> must be positive.</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.#ctor(`0[])">
<summary>
Circular buffer based on an already allocated array.
</summary>
<param name="array">Array (zero indexed) to allocate.</param>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentException"><paramref name="array"/> must have at least one element;</exception>
<remarks>
The array is used as the storage for the circular buffer. No copy of the array is made. The initial index in
the circular buffer is index 0 in the array. The array is assumed to be completely used (i.e. it is
initialized with zero bytes Free).
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.#ctor(`0[],System.Int32)">
<summary>
Circular buffer based on an already allocated array.
</summary>
<param name="array">Array (zero indexed) to allocate.</param>
<param name="count">Length of data in array, beginning from offset 0.</param>
<exception cref="T:System.ArgumentOutOfRangeException">
Initial <paramref name="count"/> must be within range of <paramref name="array"/>
</exception>
<exception cref="T:System.ArgumentException"><paramref name="array"/> must have at least one element;</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<remarks>
The array is used as the storage for the circular buffer. No copy of the array is made, only a reference.
The initial index in the array is 0. The value <paramref name="count"/> sets the initial length of the
array. So an initial <paramref name="count"/> of zero would imply an empty circular buffer.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.#ctor(`0[],System.Int32,System.Int32)">
<summary>
Circular buffer based on an already allocated array.
</summary>
<param name="array">Array (zero indexed) to allocate.</param>
<param name="offset">Offset of first byte in the array.</param>
<param name="count">
Length of data in <paramref name="array"/>, wrapping to the start of the <paramref name="array"/>.
</param>
<exception cref="T:System.ArgumentException"><paramref name="array"/> must have at least one element;</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="count"/> must be within range of <paramref name="array"/>;
<para>- or -</para>
<paramref name="offset"/> exceeds the <paramref name="array"/> boundaries.
</exception>
<remarks>
The array is used as the storage for the circular buffer. No copy of the array is made, only a reference.
The <paramref name="offset"/> is defined to be the first entry in the circular buffer. This may be any value
from zero to the last index ( <c>Array.Length - 1</c>). The value <paramref name="count"/> is the amount of
data in the array, and it may cause wrapping (so that by setting offset near the end, a value of count may
be set so that data can be considered at the end and beginning of the array given).
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Start">
<summary>
Get start index into array where data begins.
</summary>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.End">
<summary>
Get end index into array where data ends.
</summary>
<remarks>
This property is useful to know from what element in the underlying array that data can be written to.
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Length">
<summary>
Get total length of data in array.
</summary>
<remarks>
Returns the amount of allocated data in the circular buffer. The following rule applies:
<see cref="P:RJCP.Datastructures.CircularBuffer`1.Length"/> + <see cref="P:RJCP.Datastructures.CircularBuffer`1.Free"/> = <see cref="P:RJCP.Datastructures.CircularBuffer`1.Capacity"/>.
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Free">
<summary>
Get total free data in array.
</summary>
<remarks>
Returns the total amount of free elements in the circular buffer. The following rule applies:
<see cref="P:RJCP.Datastructures.CircularBuffer`1.Length"/> + <see cref="P:RJCP.Datastructures.CircularBuffer`1.Free"/> = <see cref="P:RJCP.Datastructures.CircularBuffer`1.Capacity"/>.
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Capacity">
<summary>
Get the total capacity of the array.
</summary>
<remarks>
Get the total number of elements allocated for the underlying array of the circular buffer. The following
rule applies: <see cref="P:RJCP.Datastructures.CircularBuffer`1.Length"/> + <see cref="P:RJCP.Datastructures.CircularBuffer`1.Free"/> = <see cref="P:RJCP.Datastructures.CircularBuffer`1.Capacity"/>.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.ToArrayIndex(System.Int32)">
<summary>
Convert an index from the start of the data to read to an array index.
</summary>
<param name="index">
Index in circular buffer, where an index of 0 is equivalent to the <see cref="P:RJCP.Datastructures.CircularBuffer`1.Start"/> property.
</param>
<returns>Index in array that can be used in array based operations.</returns>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.WriteLength">
<summary>
Get length of continuous available space from the current position to the end of the array or until the
buffer is full.
</summary>
<remarks>
This function is useful if you need to pass the array to another function that will then fill the contents
of the buffer. You would pass <see cref="P:RJCP.Datastructures.CircularBuffer`1.End"/> as the offset for where writing the data should start, and
<b>WriteLength</b> as the length of buffer space available until the end of the array buffer. After the read
operation that writes in to your buffer, the array is completely full, or until the end of the array.
<para>
Such a property is necessary in case that the free space wraps around the buffer. Where below <c>X</c> is
your stream you wish to read from, <c>b</c> is the circular buffer instantiated as the type
<c>CircularBuffer{T}</c>.
<code language="csharp">
<![CDATA[
c = X.Read(b.Array, b.End, b.WriteLength);
b.Produce(c);]]>
</code>
If the property <b>WriteLength</b> is not zero, then there is space in the buffer to read data.
</para>
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.ReadLength">
<summary>
Get the length of the continuous amount of data that can be read in a single copy operation from the start
of the buffer data.
</summary>
<remarks>
This function is useful if you need to pass the array to another function that will use the contents of the
array. You would pass <see cref="P:RJCP.Datastructures.CircularBuffer`1.Start"/> as the offset for reading data and <see cref="P:RJCP.Datastructures.CircularBuffer`1.ReadLength"/> as the
count. Then based on the amount of data operated on, you would free space with
<c><see cref="M:RJCP.Datastructures.CircularBuffer`1.Consume(System.Int32)"/>(ReadLength).</c>
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.GetReadBlock(System.Int32)">
<summary>
Given an offset, calculate the length of data that can be read until the end of the block.
</summary>
<param name="offset">The offset into the circular buffer to test for the read length.</param>
<returns>Length of the block that can be read from <paramref name="offset"/>.</returns>
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="offset"/> may not be negative.</exception>
<remarks>
Similar to the property <c>ReadLength</c>, this function takes an argument <c>offset</c> which is used to
determine the length of data that can be read from that offset, until either the end of the block, or the
end of the buffer.
<para>
This function is useful if you want to read a block of data, not starting from the offset 0 (and you don't
want to consume the data before hand to reach an offset of zero).
</para>
<para>
The example below, will calculate a checksum from the third byte in the block for the length of data. If the
block to read from offset 3 can be done in one operation, it will do so. Else it must be done in two
operations, first from offset 3 to the end, then from offset 0 for the remaining data.
</para>
</remarks>
<example>
<code language="csharp">
<![CDATA[
short crc;
if (buffer.GetReadBlock(3) >= length - 3) {
crc = crc16.Compute(buffer.Array, buffer.ToArrayIndex(3), length - 3);
} else {
crc = crc16.Compute(buffer.Array, buffer.ToArrayIndex(3), buffer.ReadLength - 3);
crc = crc16.Compute(crc, buffer.Array, 0, length - buffer.ReadLength);
}]]>
</code>
</example>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Consume(System.Int32)">
<summary>
Consume array elements (freeing space from the beginning) updating pointers in the circular buffer.
</summary>
<param name="length">Amount of data to consume.</param>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="length"/> is negative, or cannot consume more data than exists.
</exception>
<remarks>
This method advances the internal pointers for <i>Start</i> based on the <i>length</i> that should be
consumed. The pointer <i>End</i> does not change. It is important that this method does not <i>Reset()</i>
the buffer in case that all data is consumed. A common scenario with Streams is to write into the buffer
using asynchronous I/O. If a <i>Reset()</i> occurs during an asynchronous I/O <i>ReadFile()</i>, the
<i>End</i> pointer is also changed, so that when a <i>Produce()</i> occurs on completion of the
<i>ReadFile()</i> operation, the pointers are updated, but not using the pointers before the <i>Reset()</i>.
No crash would occur (so long as the underlying array is pinned), but data corruption would occur if this
method were not used in this particular scenario.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Produce(System.Int32)">
<summary>
Produce bytes (allocating space at the end) updating pointers in the circular buffer.
</summary>
<param name="length">
The number of bytes to indicate that have been added from the index <see cref="P:RJCP.Datastructures.CircularBuffer`1.End"/> to the end of the
array and possibly again from the start of the array if overlapped.
</param>
<exception cref="T:System.ArgumentOutOfRangeException">
Cannot produce negative <paramref name="length"/>, or producing <paramref name="length"/> exceeds
<see cref="P:RJCP.Datastructures.CircularBuffer`1.Free"/>.
</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Revert(System.Int32)">
<summary>
Revert elements produced to the end of the circular buffer.
</summary>
<param name="length">
The number of bytes to remove from the end of the array, moving the <see cref="P:RJCP.Datastructures.CircularBuffer`1.End"/> property to the left,
leaving the <see cref="P:RJCP.Datastructures.CircularBuffer`1.Start"/> property untouched.
</param>
<exception cref="T:System.ArgumentOutOfRangeException">
The <paramref name="length"/> must be positive and not exceed the number of elements in the circular buffer.
</exception>
<remarks>
This method can be used to remove data that has been added to the end of the circular buffer. When using
this data structure for streams, you would not use this property to ensure consistency of your stream (your
<c>Read</c> operation would consume from your circular buffer and <c>Write</c> would produce data to your
circular buffer.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Reset">
<summary>
Reset the pointers in the circular buffer, effectively noting the circular buffer as empty.
</summary>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Array">
<summary>
Get the reference to the array that's allocated.
</summary>
<remarks>
This property allows you to access the content of the data in the circular buffer in an efficient manner.
You can then use this property along with <see cref="P:RJCP.Datastructures.CircularBuffer`1.Start"/>, <see cref="P:RJCP.Datastructures.CircularBuffer`1.ReadLength"/>, <see cref="P:RJCP.Datastructures.CircularBuffer`1.End"/>
and <see cref="P:RJCP.Datastructures.CircularBuffer`1.WriteLength"/> for knowing where in the buffer to read and write.
</remarks>
</member>
<member name="P:RJCP.Datastructures.CircularBuffer`1.Item(System.Int32)">
<summary>
Access an element in the array using the Start as index 0.
</summary>
<param name="index">Index into the array referenced from <see cref="P:RJCP.Datastructures.CircularBuffer`1.Start"/>.</param>
<returns>Contents of the array.</returns>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(`0[])">
<summary>
Copy data from array to the end of this circular buffer and update the length.
</summary>
<param name="array">Array to copy from.</param>
<returns>Number of bytes copied.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<remarks>
Data is copied to the end of the Circular Buffer. The amount of data that could be copied is dependent on
the amount of free space. The result is the number of elements from the <c>buffer</c> array that is copied
into the Circular Buffer. Pointers in the circular buffer are updated appropriately.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(`0[],System.Int32,System.Int32)">
<summary>
Copy data from array to the end of this circular buffer and update the length.
</summary>
<param name="array">Array to copy from.</param>
<param name="offset">Offset to copy data from.</param>
<param name="count">Length of data to copy.</param>
<returns>Number of bytes copied.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="offset"/> or <paramref name="count"/> may not be negative.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="offset"/> and <paramref name="count"/> exceed <paramref name="array"/> boundaries.
</exception>
<remarks>
Data is copied to the end of the Circular Buffer. The amount of data that could be copied is dependent on
the amount of free space. The result is the number of elements from the <c>buffer</c> array that is copied
into the Circular Buffer. Pointers in the circular buffer are updated appropriately.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(RJCP.Datastructures.CircularBuffer{`0})">
<summary>
Copy data from the circular buffer to the end of this circular buffer.
</summary>
<param name="buffer">Buffer to append.</param>
<returns>Amount of data appended.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="buffer"/> may not be <see langword="null"/>.
</exception>
<remarks>
Data is copied to the end of the Circular Buffer. The amount of data that could be copied is dependent on
the amount of free space. The result is the number of elements from the <c>buffer</c> array that is copied
into the Circular Buffer. Pointers in the circular buffer are updated appropriately.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(RJCP.Datastructures.CircularBuffer{`0},System.Int32)">
<summary>
Copy data from the circular buffer to the end of this circular buffer.
</summary>
<param name="buffer">Buffer to append.</param>
<param name="count">Number of bytes to append.</param>
<returns>Amount of data appended.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="buffer"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="count"/> would exceed boundaries of <paramref name="buffer"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="count"/> may not be negative.</exception>
<remarks>
Data is copied to the end of the Circular Buffer. The amount of data that could be copied is dependent on
the amount of free space. The result is the number of elements from the <c>buffer</c> array that is copied
into the Circular Buffer. Pointers in the circular buffer are updated appropriately.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(RJCP.Datastructures.CircularBuffer{`0},System.Int32,System.Int32)">
<summary>
Copy data from the circular buffer to the end of this circular buffer.
</summary>
<param name="buffer">Buffer to append.</param>
<param name="count">Number of bytes to append.</param>
<param name="offset">Offset into the buffer to start appending.</param>
<returns>Amount of data appended.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="buffer"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="offset"/> may not be negative;
<para>- or -</para>
<paramref name="count"/> may not be negative.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="offset"/> and <paramref name="count"/> would exceed boundaries of <paramref name="buffer"/>.
</exception>
<remarks>
Data is copied to the end of the Circular Buffer. The amount of data that could be copied is dependent on
the amount of free space. The result is the number of elements from the <c>buffer</c> array that is copied
into the Circular Buffer. Pointers in the circular buffer are updated appropriately.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Append(`0)">
<summary>
Append a single element to the end of the Circular Buffer.
</summary>
<param name="element">The element to add at the end of the buffer.</param>
<returns>Amount of data appended. 1 if successful, 0 if no space available.</returns>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.Pop">
<summary>
Retrieve a single element from the Circular buffer and consume it.
</summary>
<returns>The value at index 0.</returns>
<exception cref="T:System.InvalidOperationException">Circular buffer is empty.</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.MoveTo(`0[])">
<summary>
Copy data from the circular buffer to the array and then consume the data from the circular buffer.
</summary>
<param name="array">The array to copy the data to.</param>
<returns>The number of bytes that were moved.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<remarks>Data is copied to the first element in the array, up to the length of the array.</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.MoveTo(`0[],System.Int32,System.Int32)">
<summary>
Copy data from the circular buffer to the array and then consume the data from the circular buffer.
</summary>
<param name="array">The array to copy the data to.</param>
<param name="offset">Offset into the array to copy to.</param>
<param name="count">Amount of data to copy to.</param>
<returns>The number of bytes that were moved.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="count"/> may not be negative;
<para>- or -</para>
<paramref name="offset"/> may not be negative.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="offset"/> and <paramref name="count"/> would exceed <paramref name="array"/> length.
</exception>
<remarks>
This method is very similar to the <see cref="M:RJCP.Datastructures.CircularBuffer`1.CopyTo(`0[],System.Int32,System.Int32)"/> method, but it will also consume the
data that was copied also.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.CopyTo(`0[])">
<summary>
Copy data from the circular buffer to the array.
</summary>
<param name="array">The array to copy the data to.</param>
<returns>The number of bytes that were copied.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<remarks>
Data is copied from the first element in the array, up to the length of the array. The data from the
Circular Buffer is <i>not</i> consumed. You must do this yourself. Else use the MoveTo() method.
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBuffer`1.CopyTo(`0[],System.Int32,System.Int32)">
<summary>
Copy data from the circular buffer to the array.
</summary>
<param name="array">The array to copy the data to.</param>
<param name="offset">Offset into the array to copy to.</param>
<param name="count">Amount of data to copy to.</param>
<returns>The number of bytes that were copied.</returns>
<exception cref="T:System.ArgumentNullException">
<paramref name="array"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="count"/> may not be negative;
<para>- or -</para>
<paramref name="offset"/> may not be negative.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="offset"/> and <paramref name="count"/> would exceed <paramref name="array"/> length.
</exception>
<remarks>
Data is copied from the circular buffer into the array specified, at the offset given. The data from the
Circular Buffer is <i>not</i> consumed. You must do this yourself. Else use the MoveTo() method.
</remarks>
</member>
<member name="T:RJCP.Datastructures.CircularBufferExtensions">
<summary>
A set of useful extensions to the CircularBuffer for specific data types.
</summary>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.GetString(RJCP.Datastructures.CircularBuffer{System.Char})">
<summary>
Convert the contents of the circular buffer into a string.
</summary>
<param name="buff">The circular buffer based on char.</param>
<returns>A string containing the contents of the circular buffer.</returns>
<remarks>This method will not consume the data in the CircularBuffer{char}.</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.GetString(RJCP.Datastructures.CircularBuffer{System.Char},System.Int32)">
<summary>
Convert the contents of the circular buffer into a string.
</summary>
<param name="buff">The circular buffer based on char.</param>
<param name="length">Number of characters to convert to a string.</param>
<returns>A string of up to length characters.</returns>
<remarks>This method will not consume the data in the CircularBuffer{char}.</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.GetString(RJCP.Datastructures.CircularBuffer{System.Char},System.Int32,System.Int32)">
<summary>
Convert the contents of the circular buffer into a string.
</summary>
<param name="buff">The circular buffer based on char.</param>
<param name="offset">The offset into the circular buffer.</param>
<param name="length">Number of characters to convert to a string.</param>
<returns>
A string of up to length characters, from the circular buffer starting at the offset specified..
</returns>
<remarks>This method will not consume the data in the CircularBuffer{char}.</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.Convert(System.Text.Decoder,RJCP.Datastructures.CircularBuffer{System.Byte},System.Char[],System.Int32,System.Int32,System.Boolean,System.Int32@,System.Int32@,System.Boolean@)">
<summary>
Use a decoder to convert from a Circular Buffer of bytes into a char array.
</summary>
<param name="decoder">The decoder to do the conversion.</param>
<param name="bytes">The circular buffer of bytes to convert from.</param>
<param name="chars">An array to store the converted characters.</param>
<param name="charIndex">The first element of <i>chars</i> in which data is stored.</param>
<param name="charCount">Maximum number of characters to write.</param>
<param name="flush">
<see langword="true"/> to indicate that no further data is to be converted; otherwise,
<see langword="false"/>.
</param>
<param name="bytesUsed">
When this method returns, contains the number of bytes that were used in the conversion. This parameter is
passed uninitialized.
</param>
<param name="charsUsed">
When this method returns, contains the number of characters from chars that were produced by the conversion.
This parameter is passed uninitialized.
</param>
<param name="completed">
When this method returns, contains <see langword="true"/> if all the characters specified by byteCount were
converted; otherwise, <see langword="false"/>. This parameter is passed uninitialized.
</param>
<exception cref="T:System.ArgumentException">
The output buffer <paramref name="chars"/> is too small to contain any of the converted input.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="bytes"/> or <paramref name="chars"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="charIndex"/> may not be negative;
<para>- or -</para>
<paramref name="charCount"/> may not be negative.
</exception>
<remarks>
This method should behave the same as the decoder for an array of bytes of equal size.
<para>
The <i>completed</i> output parameter indicates whether all the data in the input buffer was converted and
stored in the output buffer. This parameter is set to <see langword="false"/> if the number of bytes
specified by the <i>bytes.Length</i> parameter cannot be converted without exceeding the number of
characters specified by the charCount parameter.
</para>
<para>
The completed parameter can also be set to <see langword="false"/>, even though the all bytes were consumed.
This situation occurs if there is still data in the Decoder object that has not been stored in the bytes
buffer.
</para>
<para>
There are a few noted deviations from using the Decoder on an array of bytes, instead of a Circular Buffer.
</para>
<list type="bullet">
<item>
When converting a sequence of bytes to multiple chars, if those sequences result in the minimum number of
characters being written as 2 or more characters, slight discrepancies occur. A UTF8 decoder would convert
the sequence F3 A0 82 84 to the two characters DB40 DC84. The UTF8 decoder would not consume any of the 4
bytes if all 4 bytes are immediately available to a single call to the Decoder.Convert() function and
instead raise an exception. This Convert() function may consume some of these bytes and indicate success, if
the byte sequence wraps over from the end of the array to the beginning of the array. The number of bytes
consumed (bytesUsed) is correct and characters produced (charsUsed) is also correct. There is no error found
according to the MS documentation. The next call will result in an exception instead. So this function may:
consume more bytes than expected (but with the correct results); and may not raise an exception immediately
if those bytes were consumed.
</item>
</list>
</remarks>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.Convert(System.Text.Decoder,RJCP.Datastructures.CircularBuffer{System.Byte},RJCP.Datastructures.CircularBuffer{System.Char},System.Int32,System.Boolean,System.Int32@,System.Int32@,System.Boolean@)">
<summary>
Use a decoder to convert from a Circular Buffer of bytes into a Circular Buffer of chars.
</summary>
<param name="decoder">The decoder to do the conversion.</param>
<param name="bytes">The circular buffer of bytes to convert from.</param>
<param name="chars">The circular buffer of chars to convert to.</param>
<param name="charCount">Maximum number of characters to write.</param>
<param name="flush">
<see langword="true"/> to indicate that no further data is to be converted; otherwise,
<see langword="false"/>.
</param>
<param name="bytesUsed">
When this method returns, contains the number of bytes that were used in the conversion. This parameter is
passed uninitialized.
</param>
<param name="charsUsed">
When this method returns, contains the number of characters from chars that were produced by the conversion.
This parameter is passed uninitialized.
</param>
<param name="completed">
When this method returns, contains <see langword="true"/> if all the characters specified by byteCount were
converted; otherwise, <see langword="false"/>. This parameter is passed uninitialized.
</param>
<exception cref="T:System.ArgumentException">
The output buffer <paramref name="chars"/> is too small to contain any of the converted input.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="bytes"/> or <paramref name="chars"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="charCount"/> may not be negative.</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.Convert(System.Text.Decoder,RJCP.Datastructures.CircularBuffer{System.Byte},RJCP.Datastructures.CircularBuffer{System.Char},System.Boolean,System.Int32@,System.Int32@,System.Boolean@)">
<summary>
Use a decoder to convert from a Circular Buffer of bytes into a Circular Buffer of chars.
</summary>
<param name="decoder">The decoder to do the conversion.</param>
<param name="bytes">The circular buffer of bytes to convert from.</param>
<param name="chars">The circular buffer of chars to convert to.</param>
<param name="flush">
<see langword="true"/> to indicate that no further data is to be converted; otherwise,
<see langword="false"/>.
</param>
<param name="bytesUsed">
When this method returns, contains the number of bytes that were used in the conversion. This parameter is
passed uninitialized.
</param>
<param name="charsUsed">
When this method returns, contains the number of characters from chars that were produced by the conversion.
This parameter is passed uninitialized.
</param>
<param name="completed">
When this method returns, contains <see langword="true"/> if all the characters specified by byteCount were
converted; otherwise, <see langword="false"/>. This parameter is passed uninitialized.
</param>
<exception cref="T:System.ArgumentException">
The output buffer <paramref name="chars"/> is too small to contain any of the converted input.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="bytes"/> or <paramref name="chars"/> may not be <see langword="null"/>.
</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.Convert(System.Text.Decoder,System.Byte[],System.Int32,System.Int32,RJCP.Datastructures.CircularBuffer{System.Char},System.Boolean,System.Int32@,System.Int32@,System.Boolean@)">
<summary>
Use a decoder to convert from an array of bytes into a char CircularBuffer.
</summary>
<param name="decoder">The decoder to do the conversion.</param>
<param name="bytes">The array of bytes to convert.</param>
<param name="byteIndex">Start index in bytes array.</param>
<param name="byteCount">Number of bytes to convert in the byte array.</param>
<param name="chars">The circular buffer of chars to convert to.</param>
<param name="flush">
<see langword="true"/> to indicate that no further data is to be converted; otherwise,
<see langword="false"/>.
</param>
<param name="bytesUsed">
When this method returns, contains the number of bytes that were used in the conversion. This parameter is
passed uninitialized.
</param>
<param name="charsUsed">
When this method returns, contains the number of characters from chars that were produced by the conversion.
This parameter is passed uninitialized.
</param>
<param name="completed">
When this method returns, contains <see langword="true"/> if all the characters specified by byteCount were
converted; otherwise, <see langword="false"/>. This parameter is passed uninitialized.
</param>
<exception cref="T:System.ArgumentException">
The output buffer <paramref name="bytes"/> is too small to contain any of the converted input.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="bytes"/> or <paramref name="chars"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="byteIndex"/> may not be negative;
<para>- or -</para>
<paramref name="byteCount"/> may not be negative.
</exception>
</member>
<member name="M:RJCP.Datastructures.CircularBufferExtensions.Convert(System.Text.Encoder,System.Char[],System.Int32,System.Int32,RJCP.Datastructures.CircularBuffer{System.Byte},System.Boolean,System.Int32@,System.Int32@,System.Boolean@)">
<summary>
Converts an array of Unicode characters to a byte sequence storing the result in a circular buffer.
</summary>
<param name="encoder">The encoder to use for the conversion.</param>
<param name="chars">An array of characters to convert.</param>
<param name="charIndex">The first element of <i>chars</i> to convert.</param>
<param name="charCount">The number of elements of <i>chars</i> to convert.</param>
<param name="bytes">Circular buffer where converted bytes are stored.</param>
<param name="flush">
<see langword="true"/> to indicate no further data is to be converted; otherwise, <see langword="false"/>
</param>
<param name="charsUsed">
When this method returns, contains the number of characters from chars that were produced by the conversion.
This parameter is passed uninitialized.
</param>
<param name="bytesUsed">
When this method returns, contains the number of bytes that were used in the conversion. This parameter is
passed uninitialized.
</param>
<param name="completed">
When this method returns, contains <see langword="true"/> if all the characters specified by byteCount were
converted; otherwise, <see langword="false"/>. This parameter is passed uninitialized.
</param>
<exception cref="T:System.ArgumentException">
The output buffer <paramref name="chars"/> is too small to contain any of the converted input.
</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="bytes"/> or <paramref name="chars"/> may not be <see langword="null"/>.
</exception>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="charIndex"/> may not be negative;
<para>- or -</para>
<paramref name="charCount"/> may not be negative.
</exception>
</member>
<member name="T:RJCP.Datastructures.TimerExpiry">
<summary>
A class to maintain how much time is remaining since the last reset, until
expiry.
</summary>
<remarks>
This class is useful when implementing time outs in other methods. It can
provide the remaining time, in units of milliseconds, that can be used
with many Operating System calls as an expiry time.
<para>One example is the <see cref="M:System.Threading.WaitHandle.WaitOne"/>
method which expects a time out parameter. Either instantiate the
<see cref="T:RJCP.Datastructures.TimerExpiry"/> class at the beginning immediately before its
use, or call the <see cref="M:RJCP.Datastructures.TimerExpiry.Reset"/> method at the beginning
of the time out operation. Then on return of the function, if no other
operation occurred, the method <see cref="M:RJCP.Datastructures.TimerExpiry.RemainingTime"/> should return 0 indicating
that the timer has expired.</para>
<para>Another thread can be programmed to <see cref="M:RJCP.Datastructures.TimerExpiry.Reset"/> the timer class during
a time out operation, so that even if the result of Wait operation by the
Operating system resulted in a time out, a <see cref="M:RJCP.Datastructures.TimerExpiry.Reset"/>, which results in the
<see cref="M:RJCP.Datastructures.TimerExpiry.RemainingTime"/> being more than 0 milliseconds, indicates that another
wait operation should occur.</para>
<para>Even if no expiry is to occur, but the Operating System function
returns early, you can opt to restart the time out operation which will
then take into account the current time and reduce the time out so that
the operation ends as expected.</para>
<para>As an example, say you need to wait for data by calling a method which waits
for the first set of data within a time out. But your method must wait for at least
two elements of data within the time out. This can be implemented as follows:</para>
<example>
public true MyFunc(int timeOut)
{
TimerExpiry myExpiry = new TimerExpiry(timeOut);
int elements = 0;
do {
elements += GetData(myExpiry.RemainingTime());
} while (elements < 2 && !myExpiry.Expired);
if (elements >=2) return true;
return false;
}
</example>
</remarks>
</member>
<member name="M:RJCP.Datastructures.TimerExpiry.#ctor(System.Int32)">
<summary>
Constructor. Initialise expiry based on the current time.
</summary>
<param name="milliseconds">The initial time out in milliseconds.</param>
<remarks>
The constructor sets the initial time out that should be used. On construction
of the new object, the timer is automatically started.
</remarks>
</member>
<member name="P:RJCP.Datastructures.TimerExpiry.Timeout">
<summary>
The time for expiry on the next reset. <see cref="F:System.Threading.Timeout.Infinite"/> indicates no expiry.
</summary>
</member>
<member name="M:RJCP.Datastructures.TimerExpiry.RemainingTime">
<summary>
Estimate the amount of time (ms) remaining from when this function is called
until expiry.
</summary>
<returns>The time to expiry in milliseconds.</returns>
</member>
<member name="P:RJCP.Datastructures.TimerExpiry.Expired">
<summary>
Test if the timer expiry has expired.
</summary>
</member>
<member name="M:RJCP.Datastructures.TimerExpiry.Reset">
<summary>
Reset the time out so it occurs with the given <see cref="P:RJCP.Datastructures.TimerExpiry.Timeout"/>.
</summary>
</member>
<member name="T:RJCP.IO.Ports.Handshake">
<summary>
Handshaking mode to use.
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.None">
<summary>
No handshaking.
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.XOn">
<summary>
Software handshaking.
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.Rts">
<summary>
Hardware handshaking (RTS/CTS).
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.Dtr">
<summary>
Hardware handshaking (DTR/DSR) (uncommon).
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.RtsXOn">
<summary>
RTS and Software handshaking.
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.DtrXOn">
<summary>
DTR and Software handshaking (uncommon).
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.DtrRts">
<summary>
Hardware handshaking with RTS/CTS and DTR/DSR (uncommon).
</summary>
</member>
<member name="F:RJCP.IO.Ports.Handshake.DtrRtsXOn">
<summary>
Hardware handshaking with RTS/CTS and DTR/DSR and Software handshaking (uncommon).
</summary>
</member>
<member name="T:RJCP.IO.Ports.InternalApplicationException">
<summary>
Indicates an unexpected internal error occurred in the application.
</summary>
<remarks>
The InternalApplicationError indicates a programming error in the application. Such an
error should never occur and always indicates a bug in the application itself.
</remarks>
</member>
<member name="M:RJCP.IO.Ports.InternalApplicationException.#ctor">
<summary>
Initializes a new instance of the <see cref="T:RJCP.IO.Ports.InternalApplicationException"/> class.
</summary>
</member>
<member name="M:RJCP.IO.Ports.InternalApplicationException.#ctor(System.String)">
<summary>
Initializes a new instance of the <see cref="T:RJCP.IO.Ports.InternalApplicationException"/> class.
</summary>
<param name="message">The message that describes the error.</param>
</member>
<member name="M:RJCP.IO.Ports.InternalApplicationException.#ctor(System.String,System.Exception)">
<summary>
Initializes a new instance of the <see cref="T:RJCP.IO.Ports.InternalApplicationException"/> class.
</summary>
<param name="message">The error message that explains the reason for the exception.</param>
<param name="innerException">The exception that is the cause of the current exception, or a null reference (Nothing in Visual Basic) if no inner exception is specified.</param>
</member>
<member name="T:RJCP.IO.Ports.ISerialPortStream">
<summary>
Interface for the <see cref="T:RJCP.IO.Ports.SerialPortStream"/>, which can be used for mocking in unit tests.
</summary>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.Version">
<summary>
Get the version of this assembly (or components driving this assembly).
</summary>
<value>The version of the assembly and/or subcomponents.</value>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.PortName">
<summary>
Gets the port for communications, including but not limited to all available COM ports.
</summary>
<remarks>
A list of valid port names can be obtained using the GetPortNames method.
<para>
When changing the port name, and the property UpdateOnPortSet is <b>true</b>, setting this property will
cause the port to be opened, status read and the port then closed. Thus, you can use this behaviour to
determine the actual settings of the port (which remain constant until a program actually changes the port settings).
</para>
<para>
Setting this property to itself, while having UpdateOnPortSet to <b>true</b> has the effect of updating the
local properties based on the current port settings.
</para>
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.IsOpen">
<summary>
Gets a value indicating the open or closed status of the SerialPortStream object.
</summary>
<remarks>
The IsOpen property tracks whether the port is open for use by the caller, not whether the port is open by
any application on the machine.
</remarks>
<value>True if the serial port is open; otherwise, false. The default is false.</value>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.Encoding">
<summary>
Gets or sets the byte encoding for pre- and post-transmission conversion of text.
</summary>
<remarks>
The encoding is used for encoding string information to byte format when sending over the serial port, or
receiving data via the serial port. It is only used with the read/write functions that accept strings (and
not used for byte based reading and writing).
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.NewLine">
<summary>
Gets or sets the value used to interpret the end of a call to the ReadLine and WriteLine methods.
</summary>
<remarks>A value that represents the end of a line. The default is a line feed, (NewLine).</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.DriverInQueue">
<summary>
Specify the driver In Queue at the time it is opened.
</summary>
<remarks>
This provides the driver a recommended internal input buffer, in bytes.
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.DriverOutQueue">
<summary>
Specify the driver Out Queue at the time it is opened.
</summary>
<remarks>
This provides the driver a recommended internal output buffer, in bytes.
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.CanTimeout">
<summary>
Gets a value that determines whether the current stream can time out.
</summary>
<returns>A value that determines whether the current stream can time out.</returns>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.CanRead">
<summary>
Check if this stream supports reading.
</summary>
<remarks>
Supported so long as the stream is not disposed.
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.ReadTimeout">
<summary>
Define the time out when reading data from the stream.
</summary>
<remarks>
This defines the time out when data arrives in the buffered memory of this stream, that is, when the driver
indicates that data has arrived to the application.
<para>
Should the user perform a read operation and no data is available to copy in the buffer, a time out will occur.
</para>
<para>Set this property to <see cref="F:RJCP.IO.Ports.SerialPortStream.InfiniteTimeout"/> for an infinite time out.</para>
</remarks>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.ReadBufferSize">
<summary>
Gets or sets the size of the SerialPortStream input buffer.
</summary>
<remarks>
Sets the amount of buffering to use when reading data from the serial port. Data is read locally into this
buffered stream through another port.
<para>
The Microsoft implementation uses this to set the buffer size of the underlying driver. This implementation
interprets the ReadBufferSize differently by setting the local buffer which can be much larger (megabytes)
and independent of the low level driver.
</para>
</remarks>
<exception cref="T:System.InvalidOperationException">
An attempt was used to change the size of the buffer while the port is open (and therefore buffering is active).
</exception>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.ReceivedBytesThreshold">
<summary>
Gets or sets the number of bytes in the read buffer before a DataReceived event occurs.
</summary>
</member>
<member name="P:RJCP.IO.Ports.ISerialPortStream.BytesToRead">
<summary>
Gets the number of bytes of data in the receive buffer.