stream.h

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <limits>
 
#include "pw_assert/assert.h"
#include "pw_bytes/span.h"
#include "pw_result/result.h"
#include "pw_span/span.h"
#include "pw_status/status.h"
#include "pw_status/status_with_size.h"
#include "pw_toolchain/internal/sibling_cast.h"
 
namespace pw::stream {
 
class Stream {
 public:
  enum Whence : uint8_t {
    kBeginning = 0b001,
 
    kCurrent = 0b010,
 
    kEnd = 0b100,
  };
 
  static constexpr size_t kUnlimited = std::numeric_limits<size_t>::max();
 
  static constexpr size_t kUnknownPosition = std::numeric_limits<size_t>::max();
 
  virtual ~Stream() = default;
 
  constexpr bool readable() const { return readable_; }
 
  constexpr bool writable() const { return writable_; }
 
  constexpr bool seekable() const { return seekability_ != Seekability::kNone; }
 
  constexpr bool seekable(Whence origin) const {
    return (static_cast<uint8_t>(seekability_) & origin) != 0u;
  }
 
  Result<ByteSpan> Read(ByteSpan dest) {
    PW_DASSERT(dest.empty() || dest.data() != nullptr);
    StatusWithSize result = DoRead(dest);
 
    if (result.ok()) {
      return dest.first(result.size());
    }
    return result.status();
  }
  Result<ByteSpan> Read(void* dest, size_t size_bytes) {
    return Read(span(static_cast<std::byte*>(dest), size_bytes));
  }
 
  Result<ByteSpan> ReadExact(ByteSpan const buffer) {
    ByteSpan dest = buffer;
    while (!dest.empty()) {
      auto result = Read(dest);
      if (!result.ok()) {
        return result.status();
      }
      const size_t bytes_read = result->size();
      PW_DASSERT(bytes_read != 0);  // Should never happen, according to API.
      dest = dest.subspan(bytes_read);
    }
    return buffer;
  }
 
  Status Write(ConstByteSpan data) {
    PW_DASSERT(data.empty() || data.data() != nullptr);
    return DoWrite(data);
  }
  Status Write(const void* data, size_t size_bytes) {
    return Write(span(static_cast<const std::byte*>(data), size_bytes));
  }
  Status Write(const std::byte b) { return Write(&b, 1); }
 
  Status Seek(ptrdiff_t offset, Whence origin = kBeginning) {
    return DoSeek(offset, origin);
  }
 
  size_t Tell() { return DoTell(); }
 
  size_t ConservativeReadLimit() const {
    return ConservativeLimit(LimitType::kRead);
  }
 
  size_t ConservativeWriteLimit() const {
    return ConservativeLimit(LimitType::kWrite);
  }
 
 protected:
  // Used to indicate the type of limit being queried in ConservativeLimit.
  enum class LimitType : bool { kRead, kWrite };
 
 private:
  // The Stream class should not be extended directly, so its constructor is
  // private. To implement a new Stream, extend one of its derived classes.
  friend class Reader;
  friend class RelativeSeekableReader;
  friend class SeekableReader;
  friend class NonSeekableReader;
 
  friend class Writer;
  friend class RelativeSeekableWriter;
  friend class SeekableWriter;
  friend class NonSeekableWriter;
 
  friend class ReaderWriter;
  friend class RelativeSeekableReaderWriter;
  friend class SeekableReaderWriter;
  friend class NonSeekableReaderWriter;
 
  enum class Seekability : uint8_t {
    kNone = 0,
 
    kRelative = kCurrent,
 
    kAbsolute = kBeginning | kCurrent | kEnd,
  };
 
  // These are the virtual methods that are implemented by derived classes. The
  // public API functions call these virtual functions.
 
  constexpr Stream(bool readable, bool writable, Seekability seekability)
      : readable_(readable), writable_(writable), seekability_(seekability) {}
 
  virtual StatusWithSize DoRead(ByteSpan destination) = 0;
 
  virtual Status DoWrite(ConstByteSpan data) = 0;
 
  virtual Status DoSeek(ptrdiff_t offset, Whence origin) = 0;
 
  virtual size_t DoTell() { return kUnknownPosition; }
 
  virtual size_t ConservativeLimit(LimitType limit_type) const {
    if (limit_type == LimitType::kRead) {
      return readable() ? kUnlimited : 0;
    }
    return writable() ? kUnlimited : 0;
  }
 
  bool readable_;
  bool writable_;
  Seekability seekability_;
};
 
class Reader : public Stream {
 private:
  friend class RelativeSeekableReader;
  friend class NonSeekableReader;
 
  constexpr Reader(Seekability seekability)
      : Stream(true, false, seekability) {}
 
  using Stream::Write;
 
  Status DoWrite(ConstByteSpan) final { return Status::Unimplemented(); }
};
 
class RelativeSeekableReader : public Reader {
 protected:
  constexpr RelativeSeekableReader()
      : RelativeSeekableReader(Seekability::kRelative) {}
 
 private:
  friend class SeekableReader;
 
  constexpr RelativeSeekableReader(Seekability seekability)
      : Reader(seekability) {}
};
 
class SeekableReader : public RelativeSeekableReader {
 protected:
  constexpr SeekableReader() : RelativeSeekableReader(Seekability::kAbsolute) {}
};
 
class NonSeekableReader : public Reader {
 protected:
  constexpr NonSeekableReader() : Reader(Seekability::kNone) {}
 
 private:
  using Reader::Seek;
 
  Status DoSeek(ptrdiff_t, Whence) final { return Status::Unimplemented(); }
};
 
class Writer : public Stream {
 private:
  friend class RelativeSeekableWriter;
  friend class NonSeekableWriter;
 
  constexpr Writer(Seekability seekability)
      : Stream(false, true, seekability) {}
 
  using Stream::Read;
 
  StatusWithSize DoRead(ByteSpan) final {
    return StatusWithSize::Unimplemented();
  }
};
 
class RelativeSeekableWriter : public Writer {
 protected:
  constexpr RelativeSeekableWriter()
      : RelativeSeekableWriter(Seekability::kRelative) {}
 
 private:
  friend class SeekableWriter;
 
  constexpr RelativeSeekableWriter(Seekability seekability)
      : Writer(seekability) {}
};
 
class SeekableWriter : public RelativeSeekableWriter {
 protected:
  constexpr SeekableWriter() : RelativeSeekableWriter(Seekability::kAbsolute) {}
};
 
class NonSeekableWriter : public Writer {
 protected:
  constexpr NonSeekableWriter() : Writer(Seekability::kNone) {}
 
 private:
  using Writer::Seek;
 
  Status DoSeek(ptrdiff_t, Whence) final { return Status::Unimplemented(); }
};
 
class ReaderWriter : public Stream {
 public:
  // ReaderWriters may be used as Readers.
  Reader& as_reader() { return internal::SiblingCast<Reader&, Stream>(*this); }
  const Reader& as_reader() const {
    return internal::SiblingCast<const Reader&, Stream>(*this);
  }
 
  operator Reader&() { return as_reader(); }
  operator const Reader&() const { return as_reader(); }
 
  // ReaderWriters may be used as Writers.
  Writer& as_writer() { return internal::SiblingCast<Writer&, Stream>(*this); }
  const Writer& as_writer() const {
    return internal::SiblingCast<const Writer&, Stream>(*this);
  }
 
  operator Writer&() { return as_writer(); }
  operator const Writer&() const { return as_writer(); }
 
 private:
  friend class RelativeSeekableReaderWriter;
  friend class NonSeekableReaderWriter;
 
  constexpr ReaderWriter(Seekability seekability)
      : Stream(true, true, seekability) {}
};
 
class RelativeSeekableReaderWriter : public ReaderWriter {
 public:
  // RelativeSeekableReaderWriters may be used as RelativeSeekableReaders or
  // RelativeSeekableWriters.
  operator RelativeSeekableReader&() {
    return internal::SiblingCast<RelativeSeekableReader&, Stream>(*this);
  }
  operator const RelativeSeekableReader&() const {
    return internal::SiblingCast<const RelativeSeekableReader&, Stream>(*this);
  }
  operator RelativeSeekableWriter&() {
    return internal::SiblingCast<RelativeSeekableWriter&, Stream>(*this);
  }
  operator const RelativeSeekableWriter&() const {
    return internal::SiblingCast<const RelativeSeekableWriter&, Stream>(*this);
  }
 
 protected:
  constexpr RelativeSeekableReaderWriter()
      : ReaderWriter(Seekability::kRelative) {}
 
 private:
  friend class SeekableReaderWriter;
 
  constexpr RelativeSeekableReaderWriter(Seekability seekability)
      : ReaderWriter(seekability) {}
};
 
class SeekableReaderWriter : public RelativeSeekableReaderWriter {
 public:
  // SeekableReaderWriters may be used as SeekableReaders.
  SeekableReader& as_seekable_reader() {
    return internal::SiblingCast<SeekableReader&, Stream>(*this);
  }
  const SeekableReader& as_seekable_reader() const {
    return internal::SiblingCast<const SeekableReader&, Stream>(*this);
  }
 
  operator SeekableReader&() { return as_seekable_reader(); }
  operator const SeekableReader&() const { return as_seekable_reader(); }
 
  // SeekableReaderWriters may be used as SeekableWriters.
  SeekableWriter& as_seekable_writer() {
    return internal::SiblingCast<SeekableWriter&, Stream>(*this);
  }
  const SeekableWriter& as_seekable_writer() const {
    return internal::SiblingCast<const SeekableWriter&, Stream>(*this);
  }
 
  operator SeekableWriter&() { return as_seekable_writer(); }
  operator const SeekableWriter&() const { return as_seekable_writer(); }
 
 protected:
  constexpr SeekableReaderWriter()
      : RelativeSeekableReaderWriter(Seekability::kAbsolute) {}
};
 
class NonSeekableReaderWriter : public ReaderWriter {
 public:
  // NonSeekableReaderWriters may be used as either NonSeekableReaders or
  // NonSeekableWriters. Note that NonSeekableReaderWriter& generally should not
  // be used in APIs, which should accept ReaderWriter& instead.
  operator NonSeekableReader&() {
    return internal::SiblingCast<NonSeekableReader&, Stream>(*this);
  }
  operator const NonSeekableReader&() const {
    return internal::SiblingCast<const NonSeekableReader&, Stream>(*this);
  }
  operator NonSeekableWriter&() {
    return internal::SiblingCast<NonSeekableWriter&, Stream>(*this);
  }
  operator const NonSeekableWriter&() const {
    return internal::SiblingCast<const NonSeekableWriter&, Stream>(*this);
  }
 
 protected:
  constexpr NonSeekableReaderWriter() : ReaderWriter(Seekability::kNone) {}
 
 private:
  using ReaderWriter::Seek;
 
  Status DoSeek(ptrdiff_t, Whence) final { return Status::Unimplemented(); }
};
 
}  // namespace pw::stream