Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FBB::Mstream(3bobcat)		Message	handler		 FBB::Mstream(3bobcat)

NAME
       FBB::Mstream - Generic message handling stream

SYNOPSIS
       #include	<bobcat/mstream>
       Linking option: -lbobcat

DESCRIPTION
       Objects	of this	class may be used to handle messages in	a standardized
       way. Messages may be prefixed with order	numbers	and labels and/or line
       numbers.	 Messages  generated  by Mstream objects may optionally	end by
       throwing	an FBB::Exception (which is an std::exception),	allowing  sim-
       ple implementation of, e.g., fatal error	messages.

       Four message streams are	provided by the	BOBCAT library and may be used
       after including the mstream header file.	They are all  defined  in  the
       FBB namespace:

       o      FBB::emsg	 for  generating standard (labeled and numbered) error
	      messages,	e.g.

	      [Error 1]	this is	an error message

       o      FBB::fmsg	for generating (labeled) fatal error messages,	ending
	      in an exception, e.g.,

	      [Fatal] this fatal message is followed by	an exception

	      The  exception's	what member contains FBB::fmsg's id value (see
	      member id	below).

       o      FBB::imsg	for generating plain informational messages, e.g.,

	      this is a	plain message

       o      FBB::wmsg	for generating (labeled) warning messages;

	      [Warning]	this is	a warning

	      By default all messages are inserted into	 the  standard	output
	      stream,  but  other  destinations	(standard error, a named file,
	      etc.) can	easily be configured.

       Mstream objects themselves are std::ostream objects,  so	 they  can  be
       used  as	 objects passed	to functions expecting ostream arguments. Mes-
       sages inserted into Mstream objects are buffered	until  the  buffer  is
       flushed	by  their  std::ostream	 parts or when either the FBB::endl or
       FBB::flush is inserted into the message stream. Since  these  manipula-
       tors  act like std::endl	and std::flush when inserted into another kind
       of std::ostream object, using FBB::endl and using FBB::flush  might  be
       worth  considering.  Also, when using namespace std and using namespace
       FBB is specified	the FBB::endl and FBB::flush manipulator will automat-
       ically be used with Mstream objects.

       Messages	 inserted into Mstream objects are considered completed	at the
       insertion of the	FBB::endl or FBB::flush	manipulators. Message  labels,
       line  number  labels  and  line numbers will only be shown for the next
       line after these	manipulators have been inserted	and exceptions are, if
       needed, thrown from these manipulators.

NAMESPACE
       FBB
       All  elements  mentioned	in this	man-page, are defined in the namespace
       FBB.

INHERITS FROM
       std::ostream

CONSTRUCTORS
       o      Mstream():
	      The   default   constructor   generates	messages   using   the
	      std::streambuf  used by std::cout. There is no limit to the num-
	      ber of messages that may be inserted. No message or line numbers
	      are shown, no exceptions are thrown when inserting messages.

       o      explicit	Mstream(std::ostream &ostr, size_t maxCount = std::nu-
	      meric_limits<size_t>::max(), std::string const &tag =  "",  bool
	      throwing = false):
	      This  constructor	 uses  the std::streambuf that is also used by
	      the ostream ostr.	By default (using the default argument values)
	      there  is	 no  limit  to	the number of messages that may	be in-
	      serted. No message or line numbers are shown, no exceptions  are
	      thrown  when inserting messages. Specifying any other value than
	      std::numeric_limits_size_t_::max() will set the  maximum	number
	      of  messages that	can be inserted	to that	value. The tag defines
	      the text of the message label (e.g., Error).

	      When throwing is true an exception is thrown after completing  a
	      message.	The  generated	exception's  what  member may show the
	      FBB::Mstream object's id (see below at the  member  id)  of  the
	      Mstream object throwing the exception.

       o      explicit Mstream(std::streambuf &buf, size_t maxCount = std::nu-
	      meric_limits<size_t>::max(), std::string const &tag =  "",  bool
	      throwing = false):
	      This constructor uses buf	to insert messages into. The remaining
	      parameters are identical to those	of the previous	constructor.

       o      explicit Mstream(std::string  const  &name,  size_t  maxCount  =
	      std::numeric_limits<size_t>::max(), std::string const &tag = "",
	      bool throwing = false):
	      This constructor creates a std::ofstream from the	provided  name
	      parameter. It throws an exception	if the stream cannot be	opened
	      for writing. If a	file by	that name already exists it is rewrit-
	      ten.   The  remaining  parameters	 are identical to those	of the
	      previous two constructors.  As Mstream  inherits	from  std::os-
	      tream the	copy constructor is not	available. Neither is the move
	      constructor.

MEMBER FUNCTIONS
       o      size_t count() const:
	      returns the number of inserted messages (if  setCount  has  been
	      called:  the value set by	the last setCount call plus the	number
	      of inserted messages since that call).

       o      bool  isActive() const:
	      returns true if messages can   actually  be  inserted  into  the
	      FBB::MStream object, and false if	inserted messages are ignored.
	      When ignoring messages the message count is not updated.

       o      int id() const:
	      returns the unique id of the Mstream object.

       o      bool lineExcess()	const:
	      returns true after attempting to insert  an  additional  message
	      after maxCount number of messages	have been inserted.

       o      std::string const	&lineTag() const:
	      returns the currently used line-tag (by default `Line').

       o      size_t maxCount()	const:
	      returns  the maximum number of messages that can be inserted. If
	      the  returned  value  equals  std::numeric_limits_size_t_::max()
	      then there is no limit to	the number of messages that can	be in-
	      serted.

       o      void noLineNr():
	      calling this member will suppress	the display of a  line	number
	      if it is called after calling setLineNr (see below) but before a
	      message is being (or has been) inserted.

       o      void off():
	      after calling off	messages inserted into the Mstream object  are
	      silently ignored.	After calling off the internal message counter
	      is not incremented when messages are inserted.

       o      void on():
	      by default and after  calling  on	 messages  inserted  into  the
	      Mstream object are sent to their destination stream.

       o      void reset(std::ostream &ostr):
	      messages	inserted  into	the  Mstream object are	handled	by the
	      std::streambuf also used by ostr.	Other parameters  (e.g.,  max-
	      Count, the message label)	are kept as-is.

       o      void reset(std::streambuf	*buf):
	      messages	inserted  into	the  Mstream  object  are  handled  by
	      std::streambuf buf. Other	parameters (e.g., maxCount,  the  mes-
	      sage label) are kept as-is.

       o      void reset(FBB::Mstream const &mstream):
	      the  current object is reset using the parameters	of the mstream
	      parameter.

       o      void reset(std::string const &name, size_t maxCount, std::string
	      const &tag, bool throwing):
	      messages inserted	into Mstream objects are handled by a std::of-
	      stream created using the provided	name parameter.	 An  exception
	      is  thrown if the	stream cannot be opened	for writing. If	a file
	      by that name already exists it is	 rewritten.  Other  parameters
	      (e.g., maxCount, the message label) are kept as-is.

       o      void  reset(std::ostream	&ostr,	size_t	maxCount,  std::string
	      const &tag, bool throwing):
	      messages inserted	 into  Mstream	objects	 are  handled  by  the
	      std::streambuf  also  used  by  ostr.   By  specifying  std::nu-
	      meric_limits_size_t_::max() for maxCount there is	 no  limit  to
	      the  number of messages that may be handled by this std::stream-
	      buf. The tag defines the text of the message label (e.g.,	 Error
	      or  the  empty  string  for  no message label). When throwing is
	      specified	as true	an exception is	thrown after completing	a mes-
	      sage.

       o      void  reset(std::streambuf  *buf,	 size_t	 maxCount, std::string
	      const &tag, bool throwing):
	      messages	inserted  into	Mstream	  objects   are	  handled   by
	      std::streambuf  buf.  The	 remaining parameters are identical to
	      those of the previous reset member.

       o      void reset(std::string const &name, size_t maxCount, std::string
	      const &tag, bool throwing):
	      messages inserted	into Mstream objects are handled by a std::of-
	      stream created using the provided	name parameter.	It  throws  an
	      exception	 if the	stream cannot be opened	for writing. If	a file
	      by that name already exists it is	rewritten.  The	remaining  pa-
	      rameters	are  identical to those	of the previous	two reset mem-
	      bers.

       o      void reset(FBB::Mstream const &mstream):
	      the current object is reset using	the parameters of the  mstream
	      parameter.  Following  the reset all of the current object's pa-
	      rameters can  independently  be  modified	 from  those  used  by
	      mstream.

       o      bool setActive(bool ifTrue):
	      If ifTrue	equals true the	Mstream	is activated otherwise its ac-
	      tions are	suppressed. Returns ifTrue.

       o      void setCount(size_t count):
	      assigns the value	count to the object's message counter.

       o      void setLineNr(size_t lineNr):
	      specifies	the value lineNr as the	message's line number when the
	      next  line  is  displayed	(see also noLineNr). This value	is not
	      changed by the Mstream object. To	display	 another  line	number
	      the  member  will	have to	be called again	(i.e., the line	number
	      is not displayed automatically again at every new	line).

       o      void setLineTag(std::string const	&tag):
	      specifies	the tag	prefixing line numbers.	By  default  the  line
	      tag equals `Line'.

       o      void setMaxCount(size_t maxCount):
	      defines  maxCount	 as the	maximum	number of messages that	can be
	      inserted into the	Mstream	object.

       o      void setTag(std::string const &tag):
	      specifies	the tag	prefixing messages.  By	 default  the  tag  is
	      empty.  If  not  empty  the  tag is enclosed by square brackets.
	      E.g., specifying the tag `Error' will prefix messages with  [Er-
	      ror].

       o      std::string const	&tag() const:
	      returns  the  currently  used  message  tag (by default an empty
	      string).

       o      bool throws():
	      returns true when	the Mstream object will	throw an exception  at
	      the  next	completed message. The generated exception's what mem-
	      ber contains the id (see earlier	for  the  member  id)  of  the
	      Mstream object throwing the exception.

       o      void throwing(bool ifTrue):
	      modifies	the behaviro of	Mstream	objects	at completed messages.
	      After passing true Mstream objects will throw  an	 exception  at
	      the  next	 completed  message,  otherwise	 this exception	is not
	      thrown. The generated exception's	what member  contains  the  id
	      (see  earlier  for the member id)	of the Mstream object throwing
	      the exception.

MANIPULATORS
       Note that the following two manipulators	are not	members	of  the	 class
       Mstream,	but are	free functions defined in the namespace	FBB.

       o      std::ostream &endl(std::ostream &out):
	      This  manipulator	 inserts  a newline character in the Mstream's
	      stream and then calls FBB::flush.	 This  manipulator  acts  like
	      std::endl	 and  std::flush  when	inserted  into another kind of
	      std::ostream object.

       o      std::ostream &flush(std::ostream &out):
	      This manipulator completes the message that is  currently	 being
	      inserted	into an	Mstream	object.	It flushes the object's	desti-
	      nation stream and	prepares the  object  for  the	next  message.
	      When the object's	throws member returns true it throws an	excep-
	      tion whose what member contains the id (see earlier for the mem-
	      ber  id) of the Mstream object throwing the exception. When used
	      in combination with another kind of std::ostream object it  acts
	      like std::flush.

       o      std::ostream &noid(std::ostream &out):
	      This  manipulator	 completes the message that is currently being
	      inserted into an Mstream object. It flushes the object's	desti-
	      nation  stream  and  prepares  the  object for the next message.
	      When the object's	throws member returns true it throws an	excep-
	      tion whose what member does not contain the Mstream object's ID.
	      When used	in combination with another kind of  std::ostream  ob-
	      ject it acts like	std::flush.

       o      std::ostream &noidl(std::ostream &out):
	      This  manipulator	 inserts  a newline character in the Mstream's
	      stream and then calls  FBB::noid.	 This  manipulator  acts  like
	      std::endl	 and  std::flush  when	inserted  into another kind of
	      std::ostream object.

       As the manipulators FBB::endl and FBB::flush  act  like,	 respectively,
       std::endl  and  std::flush  when	inserted into another kind of std::os-
       tream object, using  the	 declarations  `using  FBB::endl'  and	`using
       FBB::flush'  might be worth considering.	Also, when using namespace std
       and using namespace FBB is specified the	FBB::endl and  FBB::flush  ma-
       nipulator  will	automatically  be  called when inserting endl or flush
       into Mstream objects.

EXAMPLE
       #include	<iostream>
       #include	<algorithm>
       #include	<iterator>

       #include	<bobcat/mstream>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
	   cout	<< sizeof(Mstream) << '	' << sizeof(Mbuf) << '\n';

	   imsg	<< "Informational: " <<	endl;
	   imsg.off();
	   cout	<< "The	i-msg stream is	now off. This message should appear once" <<
									       endl;
	   imsg	<< "The	i-msg stream is	now off. This message should appear once" <<
									       endl;
	   imsg	<< "The	i-msg stream is	now off. This message should appear once" <<
									       endl;
	   cout	<< "But	this message is	shown" << endl;

	   wmsg	<< "Warning message" <<	endl;
	   emsg	<< "Oops, this this is an error	(not really)" << endl;
	   emsg	<< "Oops, this goes wrong, too"	<< noid;

	   imsg.on();
	   imsg	<< "And	another	informational msg: " <<	emsg.count() <<
		   " error messages\n" << flush;

	   emsg	<< "Third error" << endl;
	   emsg.setMaxCount(3);

	   imsg	<< "Msg	in between" << endl;

	   imsg.setTag("tag");
	   imsg	<< "tagged message" << endl;

	   imsg.setTag("label");
	   imsg	<< "labeled message" <<	endl;

	   cerr	<< "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
		   emsg.count()	<< endl;

	   emsg	<< "Fourth error\n" << noid;	   // no id is shown
	   emsg	<< "Fourth error\n" << flush;	   // shows id (remove the previous
						   // statement)

	   cerr	<< "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
		   emsg.count()	<< endl;

	   cerr	<< "Beyond\n";
       }
       catch(exception const &e)
       {
	   std::cerr <<	"Got a std::exception: " << e.what() <<	'\n';
       }
       catch(...)
       {
	   std::cerr <<	"Got an	exception\n";
       }

FILES
       bobcat/mstream -	defines	the class interface

SEE ALSO
       bobcat(7), exception(3bobcat), mbuf(3bobcat)

BUGS
       None Reported.

DISTRIBUTION FILES
       o      bobcat_3.25.01-x.dsc: detached signature;

       o      bobcat_3.25.01-x.tar.gz: source archive;

       o      bobcat_3.25.01-x_i386.changes: change log;

       o      libbobcat1_3.25.01-x_*.deb:  debian  package  holding  the   li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb:  debian  package holding the li-
	      braries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT
       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT
       This is free software, distributed under	the terms of the  GNU  General
       Public License (GPL).

AUTHOR
       Frank B.	Brokken	(f.b.brokken@rug.nl).

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015		 FBB::Mstream(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | CONSTRUCTORS | MEMBER FUNCTIONS | MANIPULATORS | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mstream&sektion=3bobcat&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help