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  in-
     dex.

	The  reference	may be invalidated by any operation on this ios_base ob-
     ject, 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 pur-
     pose. The index
	of the element must be obtained by a previous call to  xalloc(),  other-
     wise 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::fail-
     ure.

Notes
	Typical use of iword storage is to pass information (e.g. custom format-
     ting flags)
	from user-defined I/O manipulators to user-defined operator<< and opera-
     tor>> 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		 Correct
     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)
home | help