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

FreeBSD Manual Pages

  
 
  

home | help 
std::ios_base::iword(3)	      C++ Standard Libary      std::ios_base::iword(3)

NAME
       std::ios_base::iword - std::ios_base::iword

Synopsis
	  long&	iword( int index );

	  First,  allocates  or	 resizes the private storage (dynamic array of
       long or another
	  indexable data structure) sufficiently to make index a valid	index,
       then returns a
	  reference  to	the long element of the	private	storage	with the index
       index.

	  The reference	may be invalidated by any operation on	this  ios_base
       object, including
	  another call to iword(), but the stored values are retained, so that
       reading from
	  iword(index)	with  the same index later will	produce	the same value
       until the next
	  call to std::basic_ios::copyfmt(). The value can  be	used  for  any
       purpose.	The index
	  of the element must be obtained by a previous	call to	xalloc(), oth-
       erwise the
	  behavior is undefined. New elements are initialized to 0.

	  If the function fails	(possibly caused by an allocation failure) and
       *this is	a base
	  class	subobject of a basic_ios<> object or subobject,	calls
	  std::basic_ios<>::setstate(badbit)	   which       may	 throw
       std::ios_base::failure.

Notes
	  Typical use of iword storage is to  pass  information	 (e.g.	custom
       formatting flags)
	  from	user-defined  I/O  manipulators	to user-defined	operator<< and
       operator>> or to
	  user-defined formatting facets imbued	into standard streams.

Parameters
	  index	- index	value of the element

Return value
	  A reference to the element.

Exceptions
	  May throw std::ios_base::failure when	setting	the badbit.

Example
       // Run this code

	#include <iostream>
	#include <string>

	struct Foo
	{
	    static int foo_xalloc;
	    std::string	data;

	    Foo(const std::string& s) :	data(s)	{}
	};

	// Allocates the iword storage for use with Foo	objects
	int Foo::foo_xalloc = std::ios_base::xalloc();

	// This	user-defined operator<<	prints the string in  reverse  if  the
       iword holds 1
	std::ostream& operator<<(std::ostream& os, Foo&	f)
	{
	    if (os.iword(Foo::foo_xalloc) == 1)
		return os << std::string(f.data.rbegin(), f.data.rend());
	    else
		return os << f.data;
	}

	// This	I/O manipulator	flips the number stored	in iword between 0 and
       1
	std::ios_base& rev(std::ios_base& os)
	{
	    os.iword(Foo::foo_xalloc) =	!os.iword(Foo::foo_xalloc);
	    return os;
	}

	int main()
	{
	    Foo	f("example");
	    std::cout << f << '\n' << rev << f << '\n' << rev << f << '\n';
	}

Output:
	example
	elpmaxe
	example

	  Defect reports

	  The following	behavior-changing defect reports were applied retroac-
       tively to
	  previously published C++ standards.

	    DR	  Applied  to	      Behavior as published		  Cor-
       rect behavior
			    the	stored value might not be	   the	stored
       value is	retained
	  LWG  36  C++98       retained	if the reference is	     until the
       next call of
			    invalidated				  copyfmt()
			    the	function set badbit by itself  on   badbit  is
       set by basic_ios
	  LWG 41 C++98	    failure,				  (if *this is
       its base	class
			    but	ios_base does not provide such	  subobject)
			    interface

See also
		   resizes  the	private	storage	if necessary and access	to the
       void* element at
	  pword	   the given index
		   (public member function)
	  xalloc   returns a program-wide unique integer that is safe  to  use
       as index	to
	  [static] pword() and iword()
		   (public static member function)

http://cppreference.com		  2024.06.10	       std::ios_base::iword(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::ios_base::iword&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help