Add binary_stream_example.cpp. Improve docs.

git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@71463 b8fc166d-592f-0410-95f2-cb63ce0dd405
2025-08-01 05:24:39 +02:00 · 2011-04-24 10:59:20 +00:00
parent 793e21594c
commit c3d5f2e2f8
4 changed files with 148 additions and 14 deletions
--- a/libs/integer/doc/binary_stream.html
+++ b/libs/integer/doc/binary_stream.html
@@ -11,14 +11,14 @@

 <body>

-<h1>Proposal for Enhanced Binary Stream I/O</h1>
+<h1>Proposal for Binary Stream I/O</h1>
 <h2>Introduction</h2>
 <p>The C++ standard library's stream I/O facilities are type-safe and very 
-convenient for performing formatted (i.e. human readable) I/O, but offer only 
-rudimentary and not very type-safe operations for performing binary I/O.&nbsp; 
+convenient for performing formatted (i.e. human readable) I/O. But they offer only 
+rudimentary and not very type-safe operations for performing unformatted binary I/O.&nbsp; 
 Although formatted I/O is often preferable, some applications need the speed and 
-storage efficiency of binary I/O or need to interoperate with third-party 
-applications that require binary file or network data formats.</p>
+storage efficiency of unformatted binary I/O or need to interoperate with third-party 
+applications that require unformatted binary file or network data formats.</p>
 <p>Standard library streams can be opened with filemode <code>
 std::ios_base::binary</code>, so binary I/O is possible. But the only 
 unformatted I/O functions available are <code>get()</code>, <code>put()</code>,
@@ -33,9 +33,9 @@ have in mind is for the simple case where the application that reads data knows
 the data types, so this is not as complicated as the general marshalling 
 situation.</p>
 </blockquote>
-<p>This proposal provides a simple solution that works will standard library 
-input and output streams. The one caveat is that they should be open with 
-filemode <code>std::ios_base::binary</code>.</p>
+<p>This proposal provides a simple solution that works with standard library 
+input and output streams. The one caveat is that the stream must be opened with filemode <code>std::ios_base::binary</code> 
+to avoid certain data values being treated as line endings.</p>
 <h2>Synopsis</h2>
 <div dir="ltr">
  <pre>namespace boost
@@ -62,19 +62,33 @@ are implementation supplied types.</p>
 <blockquote>
  <pre>int main()
 {
-  int i = 0x41424344;
-  std::cout &lt;&lt; std::hex &lt;&lt; i &lt;&lt; &quot; &quot; &lt;&lt; bin(i) &lt;&lt; '\n';
+  fstream f(&quot;binary_stream_example.dat&quot;,
+    std::ios_base::trunc | std::ios_base::in | std::ios_base::out | std::ios_base::binary);
+
+  int32_t x = 0x01020304;
+  int32_t y = 0;
+
+  f &lt;&lt; bin(x);
+  f.seekg(0);
+  f &gt;&gt; bin(y);
+
+  BOOST_ASSERT(x == y);
+
  return 0;
 }</pre>
 </blockquote>
-<p>On a little-endian machine, the output is:</p>
+<p>The file produced with be four bytes in length. On a big-endian machine, the 
+contents in hexadecimal are:</p>
 <blockquote>
-  <pre>41424344 DCBA</pre>
+  <pre>01020304</pre>
+</blockquote>
+<p>On a little-endian machine, the contents in hexadecimal are:</p>
+<blockquote>
+  <pre>04030201</pre>
 </blockquote>
-<p>&nbsp;</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->22 April, 2011<!--webbot bot="Timestamp" endspan i-checksum="29826" --></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->24 April, 2011<!--webbot bot="Timestamp" endspan i-checksum="29830" --></p>
 <p><EFBFBD> Copyright Beman Dawes,  2009, 2011</p>
 <p>Distributed under the Boost Software License, Version 1.0. See
 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>
--- a/libs/integer/example/binary_stream_example.cpp
+++ b/libs/integer/example/binary_stream_example.cpp
@@ -0,0 +1,30 @@
+//  binary_stream_example.cpp  ---------------------------------------------------------//
+
+//  Copyright Beman Dawes 2011
+
+//  Distributed under the Boost Software License, Version 1.0.
+//  See http://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/binary_stream.hpp>
+#include <boost/integer.hpp>
+#include <boost/assert.hpp>
+#include <fstream>
+
+using namespace boost;
+using namespace std;
+
+int main()
+{
+  fstream f("binary_stream_example.dat",
+    std::ios_base::trunc | std::ios_base::in | std::ios_base::out | std::ios_base::binary);
+
+  int32_t x = 0x01020304;
+  int32_t y = 0;
+
+  f << bin(x);
+  f.seekg(0);
+  f >> bin(y);
+  BOOST_ASSERT(x == y);
+
+  return 0;
+}
--- a/libs/integer/test/endian-in-sandbox/binary_stream_example/binary_stream_example.vcxproj
+++ b/libs/integer/test/endian-in-sandbox/binary_stream_example/binary_stream_example.vcxproj
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <ItemGroup Label="ProjectConfigurations">
+    <ProjectConfiguration Include="Debug|Win32">
+      <Configuration>Debug</Configuration>
+      <Platform>Win32</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|Win32">
+      <Configuration>Release</Configuration>
+      <Platform>Win32</Platform>
+    </ProjectConfiguration>
+  </ItemGroup>
+  <PropertyGroup Label="Globals">
+    <ProjectGuid>{06736C67-6305-4A9F-8D10-850FD0CE907D}</ProjectGuid>
+    <Keyword>Win32Proj</Keyword>
+    <RootNamespace>binary_stream_example</RootNamespace>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+  <ImportGroup Label="ExtensionSettings">
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+    <Import Project="..\common.props" />
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+    <Import Project="..\common.props" />
+  </ImportGroup>
+  <PropertyGroup Label="UserMacros" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <LinkIncremental>true</LinkIncremental>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <LinkIncremental>false</LinkIncremental>
+  </PropertyGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <ClCompile>
+      <PrecompiledHeader>
+      </PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <Optimization>Disabled</Optimization>
+      <PreprocessorDefinitions>WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+    <Link>
+      <SubSystem>Console</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <ClCompile>
+      <WarningLevel>Level3</WarningLevel>
+      <PrecompiledHeader>
+      </PrecompiledHeader>
+      <Optimization>MaxSpeed</Optimization>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+      <PreprocessorDefinitions>WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+    <Link>
+      <SubSystem>Console</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemGroup>
+    <ClCompile Include="..\..\..\example\binary_stream_example.cpp" />
+  </ItemGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+  <ImportGroup Label="ExtensionTargets">
+  </ImportGroup>
+</Project>
--- a/libs/integer/test/endian-in-sandbox/endian-in-sandbox.sln
+++ b/libs/integer/test/endian-in-sandbox/endian-in-sandbox.sln
@@ -19,6 +19,8 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "endian_binary_stream_test",
 EndProject
 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "endian_flip_test", "endian_flip_test\endian_flip_test.vcxproj", "{9FA33B0B-2B00-49E8-A892-E049D86076A9}"
 EndProject
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "binary_stream_example", "binary_stream_example\binary_stream_example.vcxproj", "{06736C67-6305-4A9F-8D10-850FD0CE907D}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Win32 = Debug|Win32
@@ -61,6 +63,10 @@ Global
 		{9FA33B0B-2B00-49E8-A892-E049D86076A9}.Debug|Win32.Build.0 = Debug|Win32
 		{9FA33B0B-2B00-49E8-A892-E049D86076A9}.Release|Win32.ActiveCfg = Release|Win32
 		{9FA33B0B-2B00-49E8-A892-E049D86076A9}.Release|Win32.Build.0 = Release|Win32
+		{06736C67-6305-4A9F-8D10-850FD0CE907D}.Debug|Win32.ActiveCfg = Debug|Win32
+		{06736C67-6305-4A9F-8D10-850FD0CE907D}.Debug|Win32.Build.0 = Debug|Win32
+		{06736C67-6305-4A9F-8D10-850FD0CE907D}.Release|Win32.ActiveCfg = Release|Win32
+		{06736C67-6305-4A9F-8D10-850FD0CE907D}.Release|Win32.Build.0 = Release|Win32
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE