@@ -8,7 +8,7 @@ namespace Kaitai
8
8
{
9
9
/// <summary>
10
10
/// The base Kaitai stream which exposes an API for the Kaitai Struct framework.
11
- /// It's based off a <code >BinaryReader</code >, which is a little-endian reader.
11
+ /// It's based off a <c >BinaryReader</c >, which is a little-endian reader.
12
12
/// </summary>
13
13
public partial class KaitaiStream : BinaryReader
14
14
{
@@ -22,7 +22,7 @@ public KaitaiStream(Stream stream) : base(stream)
22
22
}
23
23
24
24
/// <summary>
25
- /// Create a KaitaiStream backed by a closed file ( in read-only binary- mode).
25
+ /// Create a KaitaiStream by opening a file in read-only binary mode (FileStream ).
26
26
/// </summary>
27
27
public KaitaiStream ( string filename ) : base ( File . Open ( filename , FileMode . Open , FileAccess . Read , FileShare . Read ) )
28
28
{
@@ -36,23 +36,26 @@ public KaitaiStream(byte[] data) : base(new MemoryStream(data))
36
36
}
37
37
38
38
/// <summary>
39
- /// Used internally.
39
+ /// Temporary 64-bit buffer for leftover bits left from an unaligned bit
40
+ /// read operation. Following unaligned bit operations would consume bits
41
+ /// left in this buffer first, and then, if needed, would continue
42
+ /// consuming bytes from the stream.
40
43
/// </summary>
41
44
private ulong Bits = 0 ;
42
45
/// <summary>
43
- /// Used internally .
46
+ /// Number of bits left in <c>Bits</c> buffer .
44
47
/// </summary>
45
48
private int BitsLeft = 0 ;
46
49
47
50
/// <summary>
48
- /// Used internally .
49
- /// Caches the current plaftorm endianness and allows emited bytecode to be optimised. Thanks to @Arlorean.
51
+ /// Caches the current platform endianness and allows emitted bytecode to be optimized. Thanks to @Arlorean .
52
+ /// https://github.com/kaitai-io/kaitai_struct_csharp_runtime/pull/9
50
53
/// </summary>
51
54
static readonly bool IsLittleEndian = BitConverter . IsLittleEndian ;
52
55
53
56
static KaitaiStream ( )
54
57
{
55
- compute_single_rotations ( ) ;
58
+ computeSingleRotations ( ) ;
56
59
}
57
60
58
61
#endregion
@@ -61,7 +64,7 @@ static KaitaiStream()
61
64
62
65
/// <summary>
63
66
/// Check if the stream position is at the end of the stream (at EOF).
64
- /// WARNING: This requires a seekable and tellable stream .
67
+ /// WARNING: This requires a stream that supports seeking (memory-based or file-based) .
65
68
/// </summary>
66
69
public bool IsEof
67
70
{
@@ -70,7 +73,7 @@ public bool IsEof
70
73
71
74
/// <summary>
72
75
/// Move the stream to a specified absolute position.
73
- /// WARNING: This requires a seekable stream.
76
+ /// WARNING: This requires a stream that supports seeking (memory-based or file-based) .
74
77
/// </summary>
75
78
/// <param name="position">The position to seek to, as non-negative integer</param>
76
79
public void Seek ( long position )
@@ -80,7 +83,7 @@ public void Seek(long position)
80
83
81
84
/// <summary>
82
85
/// Get the current position within the stream.
83
- /// WARNING: This requires a tellable stream.
86
+ /// WARNING: This requires a stream that supports seeking (memory-based or file-based) .
84
87
/// </summary>
85
88
public long Pos
86
89
{
@@ -89,7 +92,7 @@ public long Pos
89
92
90
93
/// <summary>
91
94
/// Get the total length of the stream (ie. file size).
92
- /// WARNING: This requires a seekable and tellable stream .
95
+ /// WARNING: This requires a stream that supports seeking (memory-based or file-based) .
93
96
/// </summary>
94
97
public long Size
95
98
{
@@ -285,7 +288,11 @@ public double ReadF8le()
285
288
#region Unaligned bit values
286
289
287
290
/// <summary>
288
- /// ???
291
+ /// Clears the temporary buffer which holds not-yet-consumed parts of
292
+ /// the byte, which might have left over after last unaligned bit read
293
+ /// operation. Effectively, aligns the pointer in the stream to next
294
+ /// whole byte, discarding the rest of partially byte, if it existed.
295
+ /// Does nothing if unaligned bit reading is not used.
289
296
/// </summary>
290
297
public void AlignToByte ( )
291
298
{
@@ -294,8 +301,15 @@ public void AlignToByte()
294
301
}
295
302
296
303
/// <summary>
297
- /// ???
304
+ /// Read next n bits from the stream. By convention, starts from most
305
+ /// significant bits first and goes to least significant bits.
298
306
/// </summary>
307
+ /// <remarks>
308
+ /// If n is not a multiple of 8, then bits left over from partially
309
+ /// consumed byte would be stored in stream internal buffer. Subsequent
310
+ /// calls to this method would consume bits from that buffer first, and
311
+ /// then proceed with fetching the new bytes from the stream.
312
+ /// </remarks>
299
313
public ulong ReadBitsInt ( int n )
300
314
{
301
315
int bitsNeeded = n - BitsLeft ;
@@ -329,7 +343,7 @@ public ulong ReadBitsInt(int n)
329
343
}
330
344
331
345
/// <summary>
332
- /// Used internally.
346
+ /// ???
333
347
/// </summary>
334
348
private static ulong GetMaskOnes ( int n )
335
349
{
@@ -518,7 +532,7 @@ public byte[] ProcessXor(byte[] data, byte[] key)
518
532
{
519
533
if ( key . Length == 1 )
520
534
return ProcessXor ( data , key [ 0 ] ) ;
521
- if ( key . Length <= 64 && ByteArrayZero ( key ) )
535
+ if ( key . Length <= 64 && IsByteArrayZero ( key ) )
522
536
return data ;
523
537
524
538
int dl = data . Length ;
@@ -535,14 +549,14 @@ public byte[] ProcessXor(byte[] data, byte[] key)
535
549
/// <summary>
536
550
/// Used internally.
537
551
/// </summary>
538
- private static byte [ ] [ ] precomputed_single_rotations ;
552
+ private static byte [ ] [ ] precomputedSingleRotations ;
539
553
540
554
/// <summary>
541
555
/// Used internally.
542
556
/// </summary>
543
- private static void compute_single_rotations ( )
557
+ private static void computeSingleRotations ( )
544
558
{
545
- precomputed_single_rotations = new byte [ 8 ] [ ] ;
559
+ precomputedSingleRotations = new byte [ 8 ] [ ] ;
546
560
for ( int amount = 1 ; amount < 8 ; amount ++ )
547
561
{
548
562
byte [ ] translate = new byte [ 256 ] ;
@@ -551,7 +565,7 @@ private static void compute_single_rotations()
551
565
// formula taken from: http://stackoverflow.com/a/812039
552
566
translate [ i ] = ( byte ) ( ( i << amount ) | ( i >> ( 8 - amount ) ) ) ;
553
567
}
554
- precomputed_single_rotations [ amount ] = translate ;
568
+ precomputedSingleRotations [ amount ] = translate ;
555
569
}
556
570
}
557
571
@@ -566,7 +580,7 @@ private static void compute_single_rotations()
566
580
public byte [ ] ProcessRotateLeft ( byte [ ] data , int amount , int groupSize )
567
581
{
568
582
if ( groupSize < 1 )
569
- throw new Exception ( "group size must be at least 1 to be valid" ) ;
583
+ throw new ArgumentException ( "group size must be at least 1 to be valid" , "groupSize ") ;
570
584
571
585
amount = Mod ( amount , groupSize * 8 ) ;
572
586
if ( amount == 0 )
@@ -578,7 +592,7 @@ public byte[] ProcessRotateLeft(byte[] data, int amount, int groupSize)
578
592
579
593
if ( groupSize == 1 )
580
594
{
581
- byte [ ] translate = precomputed_single_rotations [ amount ] ;
595
+ byte [ ] translate = precomputedSingleRotations [ amount ] ;
582
596
583
597
for ( int i = 0 ; i < dl ; i ++ )
584
598
{
@@ -751,7 +765,7 @@ public static bool ByteArrayEqual(byte[] a, byte[] b)
751
765
/// <summary>
752
766
/// Check if byte array is all zeroes.
753
767
/// </summary>
754
- public static bool ByteArrayZero ( byte [ ] a )
768
+ public static bool IsByteArrayZero ( byte [ ] a )
755
769
{
756
770
foreach ( byte x in a )
757
771
if ( x != 0 )
0 commit comments