// constructors
 internal BsonBinaryReaderContext(BsonBinaryReaderContext parentContext, ContextType contextType, int startPosition, int size)
 {
     this.parentContext = parentContext;
     this.contextType = contextType;
     this.startPosition = startPosition;
     this.size = size;
 }

 // constructors
 internal BsonBinaryReaderBookmark(
     BsonReaderState state,
     BsonType currentBsonType,
     string currentName,
     BsonBinaryReaderContext context,
     int position)
     : base(state, currentBsonType, currentName)
 {
     _context = context.Clone();
     _position = position;
 }

 // constructors
 internal BsonBinaryReaderContext(
     BsonBinaryReaderContext parentContext,
     ContextType contextType,
     int startPosition, 
     int size)
 {
     _parentContext = parentContext;
     _contextType = contextType;
     _startPosition = startPosition;
     _size = size;
 }

 internal BsonBinaryReaderBookmark(
     BsonBinaryReaderContext context,
     BsonReadState state,
     BsonType currentBsonType,
     int position
 )
 {
     this.context = context;
     this.state = state;
     this.currentBsonType = currentBsonType;
     this.position = position;
 }

 /// <summary>
 /// Initializes a new instance of the BsonBinaryReader class.
 /// <param name="buffer">A BsonBuffer.</param>
 /// <param name="settings">A BsonBinaryReaderSettings.</param>
 /// </summary>
 public BsonBinaryReader(
     BsonBuffer buffer,
     BsonBinaryReaderSettings settings
 ) {
     if (buffer == null) {
         this.buffer = new BsonBuffer();
         this.disposeBuffer = true; // only call Dispose if we allocated the buffer
     } else {
         this.buffer = buffer;
         this.disposeBuffer = false;
     }
     this.settings = settings.Freeze();
     context = new BsonBinaryReaderContext(null, ContextType.TopLevel, 0, 0);
 }

 // constructors
 /// <summary>
 /// Initializes a new instance of the BsonBinaryReader class.
 /// </summary>
 /// <param name="buffer">A BsonBuffer.</param>
 /// <param name="settings">A BsonBinaryReaderSettings.</param>
 public BsonBinaryReader(BsonBuffer buffer, BsonBinaryReaderSettings settings)
     : base(settings)
 {
     if (buffer == null)
     {
         _buffer = new BsonBuffer();
         _disposeBuffer = true; // only call Dispose if we allocated the buffer
     }
     else
     {
         _buffer = buffer;
         _disposeBuffer = false;
     }
     _binaryReaderSettings = settings; // already frozen by base class
     _context = new BsonBinaryReaderContext(null, ContextType.TopLevel, 0, 0);
 }

        /// <summary>
        /// Initializes a new instance of the BsonBinaryReader class.
        /// </summary>
        /// <param name="stream">A stream (BsonBinary does not own the stream and will not Dispose it).</param>
        /// <param name="settings">A BsonBinaryReaderSettings.</param>
        public BsonBinaryReader(Stream stream, BsonBinaryReaderSettings settings)
            : base(settings)
        {
            if (stream == null)
            {
                throw new ArgumentNullException("stream");
            }
            if (!stream.CanSeek)
            {
                throw new ArgumentException("The stream must be capable of seeking.", "stream");
            }

            _streamReader = new BsonStreamReader(stream, settings.Encoding);
            _settings = settings; // already frozen by base class

            _context = new BsonBinaryReaderContext(null, ContextType.TopLevel, 0, 0);
        }

 private string GenerateDottedElementName(BsonBinaryReaderContext context, string elementName)
 {
     if (context.ContextType == ContextType.Document)
     {
         return GenerateDottedElementName(context.ParentContext, (context.CurrentElementName ?? "?") + "." + elementName);
     }
     else if (context.ContextType == ContextType.Array)
     {
         var indexElementName = context.CurrentArrayIndex.ToString(NumberFormatInfo.InvariantInfo);
         return GenerateDottedElementName(context.ParentContext, indexElementName + "." + elementName);
     }
     else if (context.ParentContext != null)
     {
         return GenerateDottedElementName(context.ParentContext, "?." + elementName);
     }
     else
     {
         return elementName;
     }
 }

        public override void ReadStartArray() {
            if (disposed) { ThrowObjectDisposedException(); }
            if (state != BsonReadState.Value || currentBsonType != BsonType.Array) {
                string message = string.Format("ReadStartArray cannot be called when ReadState is: {0} and BsonType is: {1}", state, currentBsonType);
                throw new InvalidOperationException(message);
            }

            var startPosition = buffer.Position; // position of size field
            var size = ReadSize();
            context = new BsonBinaryReaderContext(context, ContextType.Array, startPosition, size);
            state = BsonReadState.Type;
        }

        public override void ReadStartDocument() {
            if (disposed) { ThrowObjectDisposedException(); }
            if (
                state != BsonReadState.Initial &&
                state != BsonReadState.Done &&
                state != BsonReadState.ScopeDocument &&
                (state != BsonReadState.Value || currentBsonType != BsonType.Document)
            ) {
                string message = string.Format("ReadStartDocument cannot be called when ReadState is: {0} and BsonType is: {1}", state, currentBsonType);
                throw new InvalidOperationException(message);
            }

            var contextType = (state == BsonReadState.ScopeDocument) ? ContextType.ScopeDocument : ContextType.Document;
            var startPosition = buffer.Position; // position of size field
            var size = ReadSize();
            context = new BsonBinaryReaderContext(context, contextType, startPosition, size);
            state = BsonReadState.Type;
        }

        /// <summary>
        /// Reads a BSON JavaScript with scope from the reader (call ReadStartDocument next to read the scope).
        /// </summary>
        /// <returns>A string.</returns>
        public override string ReadJavaScriptWithScope()
        {
            if (Disposed) { ThrowObjectDisposedException(); }
            VerifyBsonType("ReadJavaScriptWithScope", BsonType.JavaScriptWithScope);

            var startPosition = _bsonStream.Position; // position of size field
            var size = ReadSize();
            _context = new BsonBinaryReaderContext(_context, ContextType.JavaScriptWithScope, startPosition, size);
            var code = _bsonStream.ReadString(_settings.Encoding);

            State = BsonReaderState.ScopeDocument;
            return code;
        }

        /// <summary>
        /// Reads the start of a BSON document.
        /// </summary>
        public override void ReadStartDocument() {
            if (disposed) { ThrowObjectDisposedException(); }
            VerifyBsonType("ReadStartDocument", BsonType.Document);

            var contextType = (state == BsonReaderState.ScopeDocument) ? ContextType.ScopeDocument : ContextType.Document;
            var startPosition = buffer.Position; // position of size field
            var size = ReadSize();
            context = new BsonBinaryReaderContext(context, contextType, startPosition, size);
            state = BsonReaderState.Type;
        }

        /// <summary>
        /// Reads a BSON JavaScript with scope from the reader (call ReadStartDocument next to read the scope).
        /// </summary>
        /// <returns>A string.</returns>
        public override string ReadJavaScriptWithScope() {
            if (disposed) { ThrowObjectDisposedException(); }
            VerifyBsonType("ReadJavaScriptWithScope", BsonType.JavaScriptWithScope);

            var startPosition = buffer.Position; // position of size field
            var size = ReadSize();
            context = new BsonBinaryReaderContext(context, ContextType.JavaScriptWithScope, startPosition, size);
            var code = buffer.ReadString();

            state = BsonReaderState.ScopeDocument;
            return code;
        }

        /// <summary>
        /// Reads the start of a BSON array.
        /// </summary>
        public override void ReadStartArray() {
            if (disposed) { ThrowObjectDisposedException(); }
            VerifyBsonType("ReadStartArray", BsonType.Array);

            var startPosition = buffer.Position; // position of size field
            var size = ReadSize();
            context = new BsonBinaryReaderContext(context, ContextType.Array, startPosition, size);
            state = BsonReaderState.Type;
        }

 public BsonBinaryReaderContext Clone()
 {
     var clone = new BsonBinaryReaderContext();
     clone.parentContext = this.parentContext;
     clone.contextType = this.contextType;
     clone.startPosition = this.startPosition;
     clone.size = this.size;
     return clone;
 }

 public BsonBinaryReader(
     BsonBuffer buffer,
     BsonBinaryReaderSettings settings
 ) {
     this.buffer = buffer ?? new BsonBuffer();
     this.disposeBuffer = buffer == null; // only call Dispose if we allocated the buffer
     this.settings = settings;
     context = null;
 }

 public BsonBinaryReader(
     BsonBuffer buffer,
     BsonBinaryReaderSettings settings
 ) {
     this.buffer = buffer ?? new BsonBuffer();
     this.disposeBuffer = buffer == null; // only call Dispose if we allocated the buffer
     this.settings = settings;
     context = null;
     state = BsonReadState.Initial;
     currentBsonType = BsonType.Document;
 }

        /// <summary>
        /// Reads a raw BSON document.
        /// </summary>
        /// <returns>
        /// The raw BSON document.
        /// </returns>
        public override IByteBuffer ReadRawBsonDocument()
        {
            if (Disposed) { ThrowObjectDisposedException(); }
            VerifyBsonType("ReadRawBsonDocument", BsonType.Document);

            var slice = ReadSlice();

            if (_context.ContextType == ContextType.JavaScriptWithScope)
            {
                _context = _context.PopContext(_streamReader.Position); // JavaScriptWithScope
            }
            switch (_context.ContextType)
            {
                case ContextType.Array: State = BsonReaderState.Type; break;
                case ContextType.Document: State = BsonReaderState.Type; break;
                case ContextType.TopLevel: State = BsonReaderState.Done; break;
                default: throw new BsonInternalException("Unexpected ContextType.");
            }

            return slice;
        }

 public override void ReturnToBookmark(
     BsonBinaryReaderBookmark bookmark
 ) {
     context = bookmark.Context;
     state = bookmark.State;
     currentBsonType = bookmark.CurrentBsonType;
     buffer.Position = bookmark.Position;
 }

        /// <summary>
        /// Reads the end of a BSON document from the reader.
        /// </summary>
        public override void ReadEndDocument() {
            if (disposed) { ThrowObjectDisposedException(); }
            if (
                context.ContextType != ContextType.Document &&
                context.ContextType != ContextType.ScopeDocument
            ) {
                var message = string.Format("ReadEndDocument cannot be called when ContextType is: {0}", context.ContextType);
                throw new InvalidOperationException(message);
            }
            if (state == BsonReaderState.Type) {
                ReadBsonType(); // will set state to EndOfDocument if at end of document
            }
            if (state != BsonReaderState.EndOfDocument) {
                var message = string.Format("ReadEndDocument cannot be called when State is: {0}", state);
                throw new InvalidOperationException(message);
            }

            context = context.PopContext(buffer.Position);
            if (context != null && context.ContextType == ContextType.JavaScriptWithScope) {
                context = context.PopContext(buffer.Position); // JavaScriptWithScope
            }
            switch (context.ContextType) {
                case ContextType.Array: state = BsonReaderState.Type; break;
                case ContextType.Document: state = BsonReaderState.Type; break;
                case ContextType.TopLevel: state = BsonReaderState.Done; break;
                default: throw new BsonInternalException("Unexpected ContextType");
            }
        }