#include <BufferWriter.h>

Inheritance diagram for swoc::BufferWriter:

Collaboration diagram for swoc::BufferWriter:

Public Member Functions
virtual BufferWriter &	write (char c)=0

virtual BufferWriter &	write (void const *data, size_t length)

BufferWriter &	write (MemSpan< void const > span)

virtual const char *	data () const =0

virtual bool	error () const =0

virtual char *	aux_data ()

virtual size_t	capacity () const =0

virtual size_t	extent () const =0

size_t	size () const

size_t	remaining () const

MemSpan< char >	aux_span ()

virtual bool	commit (size_t n)=0

virtual BufferWriter &	discard (size_t n)=0

virtual BufferWriter &	restrict (size_t n)=0

virtual BufferWriter &	restore (size_t n)=0

virtual BufferWriter &	copy (size_t dst, size_t src, size_t n)=0

template<typename... Args>
BufferWriter &	print (const TextView &fmt, Args &&...args)

template<typename... Args>
BufferWriter &	print_v (const TextView &fmt, const std::tuple< Args... > &args)

template<typename... Args>
BufferWriter &	print (const bwf::Format &fmt, Args &&...args)

template<typename... Args>
BufferWriter &	print_v (const bwf::Format &fmt, const std::tuple< Args... > &args)

template<typename Binding, typename Extractor>
BufferWriter &	print_nfv (Binding &&names, Extractor &&ex, bwf::ArgPack const &args)

template<typename Binding, typename Extractor>
BufferWriter &	print_nfv (Binding const &names, Extractor &&ex)

template<typename Binding>
BufferWriter &	print_n (Binding const &names, TextView const &fmt)

template<typename T>
BufferWriter &	format (bwf::Spec const &spec, T &&t)

template<typename T>
BufferWriter &	format (bwf::Spec const &spec, T const &t)

virtual std::ostream &	operator>> (std::ostream &stream) const =0

Detailed Description

Wrapper for operations on a buffer.

This maintains information about the size and amount in use of the buffer, preventing data overruns. In all cases, methods that write to the buffer clip the input to the size of the remaining buffer space. The error method can be used to detect such clipping. The theoretical size of the buffer is also tracked such that if there is not enough buffer space, the amount needed can be determined by the method extent.

Note: This is a protocol class, concrete subclasses implement the functionality.

Definition at line 35 of file BufferWriter.h.

Constructor & Destructor Documentation

◆ ~BufferWriter()

swoc::BufferWriter::~BufferWriter ( )

inlinevirtual

Definition at line 458 of file BufferWriter.h.

Member Function Documentation

◆ aux_data()

char * swoc::BufferWriter::aux_data ( )

inlinevirtual

Address of the first unused byte in the output buffer.

The address is fragile and calls to non-const methods can invalidate it.

Returns: Address of the next output byte, or nullptr if there is no remaining capacity.

Reimplemented in swoc::FixedBufferWriter.

Definition at line 483 of file BufferWriter.h.

◆ aux_span()

MemSpan< char > swoc::BufferWriter::aux_span ( )

inline

A memory span of the unused bytes.

Returns: A span of the unused bytes.

This is a convenience method that is identical to

BufferWriter w;
// ...
MemSpan<char>{ w.aux_data(), w.remaining() };

Definition at line 962 of file bwf_base.h.

◆ capacity()

virtual size_t swoc::BufferWriter::capacity ( ) const

pure virtual

Returns: The number of bytes that can be successfully written to this buffer.

Implemented in swoc::FixedBufferWriter.

◆ commit()

virtual bool swoc::BufferWriter::commit ( size_t n )

pure virtual

Increase the extent by n bytes.

Parameters

n	Number of bytes.

Returns: true if the commit is final, false if it should be retried.

This is used to add data written in the aux_data to the written data in the buffer.

The return value should be true unless the write operation proceeding the call to commit along with the commit call should be retried. That is only reasonable if some state in the concrete implementation has changed to make success possible on the next try. Generally this will be because the implementation increased capacity.

Implemented in swoc::ArenaWriter, and swoc::FixedBufferWriter.

◆ copy()

virtual BufferWriter & swoc::BufferWriter::copy	(	size_t	dst,
		size_t	src,
		size_t	n )

pure virtual

Copy data from one part of the buffer to another.

The copy is guaranteed to be correct even if the src and dst overlap. The regions are clipped by the current extent. That is, bytes cannot be copied to nor from unwritten buffer. If the extent is currently more than the capacity, the copy is performed as if the buffer existed and then clipped to the actual buffer space.

Parameters

dst	Offset of the first by to copy onto.
src	Offset of the first byte to copy from.
n	Number of bytes to copy.

Returns: *this

Implemented in swoc::FixedBufferWriter.

◆ data()

virtual const char * swoc::BufferWriter::data ( ) const

pure virtual

Returns: Pointer to first byte in buffer.

Implemented in swoc::FixedBufferWriter.

◆ discard()

virtual BufferWriter & swoc::BufferWriter::discard ( size_t n )

pure virtual

Decrease the extent by n.

Parameters

n	Number of bytes to remove from the extent.

Returns: this.

The buffer content is unchanged, only the extent value is adjusted. This effectively discards n bytes of already written data.

Implemented in swoc::FixedBufferWriter.

◆ error()

virtual bool swoc::BufferWriter::error ( ) const

pure virtual

Get the error state.

Returns: true if in an error state, false if not.

Implemented in swoc::FixedBufferWriter.

◆ extent()

virtual size_t swoc::BufferWriter::extent ( ) const

pure virtual

Returns: Number of characters written to the buffer, including those discarded.

Implemented in swoc::FixedBufferWriter.

◆ format() [1/2]

template<typename T>

BufferWriter & swoc::BufferWriter::format	(	bwf::Spec const &	spec,
		T &&	t )

Write formattted data.

Template Parameters

T	Data type.

Parameters

spec	Format specifier.
t	Instance to print.

Returns: this

Essentially this forwards t to bwformat.

Definition at line 1346 of file bwf_base.h.

◆ format() [2/2]

template<typename T>

BufferWriter & swoc::BufferWriter::format	(	bwf::Spec const &	spec,
		T const &	t )

Write formattted data.

Template Parameters

T	Data type.

Parameters

spec	Format specifier.
t	Instance to print.

Returns: this

Essentially this forwards t to bwformat.

Definition at line 1340 of file bwf_base.h.

◆ operator>>()

virtual std::ostream & swoc::BufferWriter::operator>> ( std::ostream & stream ) const

pure virtual

IO stream operator.

Parameters

stream Output stream.

Returns: stream

Write the buffer contents to stream.

Implemented in swoc::FixedBufferWriter.

◆ print() [1/2]

template<typename... Args>

BufferWriter & swoc::BufferWriter::print	(	const bwf::Format &	fmt,
		Args &&...	args )

Formatted output to the buffer.

Template Parameters

Args	Types of the format input parameters.

Parameters

fmt	Pre-condensed format.
args	Arguments for the format string.

Returns: this.

Definition at line 933 of file bwf_base.h.

◆ print() [2/2]

template<typename... Args>

BufferWriter & swoc::BufferWriter::print	(	const TextView &	fmt,
		Args &&...	args )

Formatted output to the buffer.

Template Parameters

Args	Types of the format arguments.

Parameters

fmt	Format string to control formatted output.
args	Parameters for the format string.

Returns: this.

The format string is Python style. See http://docs.solidwallofcode.com/libswoc/code/BW_Format.en.html for further information.

Note: This must be declared here, but the implementation is in bwf_base.h. That file does not need to be included if formatted output is not used.

Definition at line 927 of file bwf_base.h.

◆ print_n()

template<typename Binding>

BufferWriter & swoc::BufferWriter::print_n	(	Binding const &	names,
		TextView const &	fmt )

Write formatted output to this buffer.

Parameters

names	Name set for specifier names.
fmt	Format string.

This is intended to be use with context name binding where names has the bindings and the format string fmt contains only references to those names, not to any arguments.

Definition at line 957 of file bwf_base.h.

◆ print_nfv() [1/2]

template<typename Binding, typename Extractor>

BufferWriter & swoc::BufferWriter::print_nfv	(	Binding &&	names,
		Extractor &&	ex,
		bwf::ArgPack const &	args )

Write formatted output of args to this buffer.

Template Parameters

Binding	Type for the name binding instance.
Extractor	Format extractor type.

Parameters

names	Name set for specifier names.
ex	Format processor instance, which parse the format piecewise.
args	The format parameters.

Extractor must have at least two methods

A conversion to bool that indicates if there is data left.
A function of the signature bool ex(std::string_view& lit, bwf::Spec & spec)

The latter must return whether a specifier was parsed, while filling in lit and spec as appropriate for the next chunk of format string. No literal is represented by a empty lit.

The name binding must have a function operator that takes two arguments, a BufferWriter& and a format specifier bwf::Spec. It is expected to generate output to the BufferWriter instance based on data in the format specifier (which contains, among other things, the name which caused the binding to be invoked).

Note: This is the base implementation, all of the other variants are wrappers for this.

See also: NameBinding

Definition at line 865 of file bwf_base.h.

◆ print_nfv() [2/2]

template<typename Binding, typename Extractor>

BufferWriter & swoc::BufferWriter::print_nfv	(	Binding const &	names,
		Extractor &&	ex )

Write formatted output of args to this buffer.

Template Parameters

Binding	Name binding functor.
Extractor	Format processor type.

Parameters

names	Name set for specifier names.
ex	Format processor instance, which parse the format piecewise.

Note: This is primarily an internal convenience for certain situations where a format parameter tuple is not needed and difficult to create.

Definition at line 951 of file bwf_base.h.

◆ print_v() [1/2]

template<typename... Args>

BufferWriter & swoc::BufferWriter::print_v	(	const bwf::Format &	fmt,
		const std::tuple< Args... > &	args )

Formatted output to the buffer.

Template Parameters

Args	Types of the parameter for formatting.

Parameters

fmt	Pre-condensed format string.
args	The format parameters in a tuple.

Returns: this

This is the equivalent of the "va..." form for printing. Alternate front ends to formatted output should gather their formatting arguments into a tuple, usually using std::forward_as_tuple().

Definition at line 945 of file bwf_base.h.

◆ print_v() [2/2]

template<typename... Args>

BufferWriter & swoc::BufferWriter::print_v	(	const TextView &	fmt,
		const std::tuple< Args... > &	args )

Formatted output to the buffer.

Template Parameters

Args	Types of the arguments for formatting.

Parameters

fmt	Format string.
args	The format arguments in a tuple.

Returns: this

This is the equivalent of the "va..." form for printing. Alternate front ends to formatted output should gather their formatting arguments into a tuple, usually using std::forward_as_tuple().

Definition at line 939 of file bwf_base.h.

◆ remaining()

size_t swoc::BufferWriter::remaining ( ) const

inline

Returns: The number of bytes which have not yet been written.

Definition at line 493 of file BufferWriter.h.

◆ restore()

virtual BufferWriter & swoc::BufferWriter::restore ( size_t n )

pure virtual

Restore n bytes of capacity. If there is an error condition, this function clears it and sets the extent to the size. It then increases the capacity by n characters.

Note: This does not make the internal buffer size larger. It can only restore capacity earlier removed by restrict.

See also: restrict

Implemented in swoc::FixedBufferWriter.

◆ restrict()

virtual BufferWriter & swoc::BufferWriter::restrict ( size_t n )

pure virtual

Reduce the capacity by n bytes If the capacity is reduced below the current size the instance goes in to an error state.

See also: restore

Returns: *this

Implemented in swoc::FixedBufferWriter.

◆ size()

size_t swoc::BufferWriter::size ( ) const

inline

Returns: Number of bytes of valid (used) data in the buffer.

Definition at line 488 of file BufferWriter.h.

◆ write() [1/3]

virtual BufferWriter & swoc::BufferWriter::write ( char c )

pure virtual

Write c to the buffer.

Parameters

c	Character to write.

Returns: this.

Implemented in swoc::ArenaWriter, and swoc::FixedBufferWriter.

◆ write() [2/3]

BufferWriter & swoc::BufferWriter::write ( MemSpan< void const > span )

inline

Write data to the buffer.

Parameters

span	Data source.

Returns: this

Data from span is written directly to the buffer, and clipped to the size of the buffer.

Definition at line 478 of file BufferWriter.h.

◆ write() [3/3]

BufferWriter & swoc::BufferWriter::write	(	void const *	data,
		size_t	length )

inlinevirtual

Write length bytes starting at data to the buffer.

Parameters

data	Source data.
length	Number of bytes in the source data.

Returns: this.

Reimplemented in swoc::ArenaWriter, and swoc::FixedBufferWriter.

Definition at line 461 of file BufferWriter.h.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~BufferWriter()

Member Function Documentation

◆ aux_data()

◆ aux_span()

◆ capacity()

◆ commit()

◆ copy()

◆ data()

◆ discard()

◆ error()

◆ extent()

◆ format() [1/2]

◆ format() [2/2]

◆ operator>>()

◆ print() [1/2]

◆ print() [2/2]

◆ print_n()

◆ print_nfv() [1/2]

◆ print_nfv() [2/2]

◆ print_v() [1/2]

◆ print_v() [2/2]

◆ remaining()

◆ restore()

◆ restrict()

◆ size()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]