4.16 sdds::InputSource, sdds::OutputSink, and adapters

• name:
  sdds::InputSource, sdds::OutputSink, source and sink factories
• description:
  Provide byte-oriented I/O behind readers and writers. Custom implementations advertise read, write, seek, truncate, flush, sync, and reopen support through SourceCapabilities. Built-in adapters support paths, standard streams, borrowed or owned FILE*, borrowed C++ streams, and caller-owned memory.
• synopsis:
  std::unique_ptr<InputSource> inputFromPath(path);  
  std::unique_ptr<InputSource> inputFromStdin();  
  std::unique_ptr<InputSource> inputFromFile(FILE *file,  
                                             bool takeOwnership = false);  
  std::unique_ptr<InputSource> inputFromStream(std::istream &stream);  
  std::unique_ptr<InputSource> inputFromMemory(const void *data,  
                                               std::size_t size);  
  std::unique_ptr<OutputSink> outputToPath(path, bool truncate = true);  
  std::unique_ptr<OutputSink> outputToStdout();  
  std::unique_ptr<OutputSink> outputToFile(FILE *file,  
                                           bool takeOwnership = false);  
  std::unique_ptr<OutputSink> outputToStream(std::ostream &stream);  
  std::unique_ptr<OutputSink> outputToMemory(  
      std::vector<std::uint8_t> &data);

• arguments:
  • path — Path opened by the adapter.
  • file, stream — Already-open stream to wrap.
  • takeOwnership — Whether adapter closure also closes a FILE*.
  • data, size — Caller-owned input or output memory.
  • truncate — Whether path output replaces existing contents.
• return value:
  An owned adapter suitable for Reader::fromSource or Writer::toSink. The wrapped stream or memory must outlive a borrowed adapter.
• exceptions:
  sdds::IoError for failed operations and sdds::StateError when an optional operation is requested without the corresponding capability.
• see also:
  Sections 4.12 and 4.18.