tango.io.Buffer 翻译
(提交后发觉内容不在了很多，故加了一个附件）
tango.io.Buffer (r4792)
License:
BSD style: see license.txt
Version:
Mar 2004: Initial release Dec 2006: Outback release
Authors:
Kris
缓冲器也可以通过应用一个迭代器被标记化（tokenized）。当你处理文字输入和/或内容比典型的转换器支持的更适合流动格式（fluid format）时，这是很方便的。迭代器记号被直接映射到缓冲器内容（切割），让他们在实践中非常有效。象其他缓冲器客户端一样，多重迭代器可以映射到一个公共的缓冲器并且被序列化访问。
缓冲器有时是内存模式（memory-only），在一个客户端已经消耗所有的内容使它没有什么事情可做的情况下。别的缓冲器被它们自己绑定到一个外部设备叫做管道（conduit）。在这种情况下，一个消费者最终会导致一个缓冲器通过它的关联管道重载（reload）并且前一个缓冲器内容会丢失。
类似的途径途径施加到填入一个缓冲器的客户端，借此所有的缓冲器内容在继续之前被冲刷到绑定的管道。另一个变体是存储映像（memory-mapped）缓冲器，借此缓冲器内容被直接映射到虚拟内存通过OS陈列。这可以作为一个内容的数组访问大文件。
直接的缓冲器操作典型地包括添加，如下面的例子：
1 2 3 4 5 6 7 |
// 创建一个小的缓冲器。 auto buf = new Buffer (256); auto foo = "to write some D"; // 直接添加一些文字到这个缓冲器。 buf.append ("now is the time for all good men ").append(foo); |
另外，你可以用一个格式器支添加缓冲器。
1 2 |
auto output = new TextOutput (new Buffer(256)); output.format ("now is the time for {} good men {}", 3, foo); |
一个slice()方法会返回缓冲器中的所有有效内容。你希望添加的超越规格界限（specified limit）时，使用GrowBuffer 代替。
一个普遍用法是与一个管道合在一起，如FileConduit（文件管道）。每一个管道为它的关联缓冲器陈列一个优先尺寸（preferred-size），在缓冲器构建期间使用：
1 2 |
auto file = new File ("name"); auto buf = new Buffer (file); |
不过，这通常被更高级的构造如通过流包装的构造隐藏。例如：
1 |
auto input = new DataInput (new File ("name")); |
在结果流和文件间的确是一个缓冲器，但显式缓冲器构造通常产不必要的。
一个迭代器用类似方式构造，构造的地方，你提供给它一个输入流进行操作。在tango.io.stream包中，有各种迭代器可以使用，它们为utf8、utf16、utf32进行模板化。这个例子使用一个行迭代器（line-iterator)衍生到扫描的文本文件：
1 2 3 4 |
auto lines = new TextInput (new File ("name")); foreach (line; lines) Cout(line).newline; lines.close; |
对于Tango中的许多用途，缓冲器是很有用的，但有时要避开它们（当可能有更适当的途径时）。对于这样的情况，管道派生物（如File）支持基于数组的I/O，通过一对read()和write()方法。
参数：
| conduit |
到缓冲器的管道。 |
备注：
参数：
| stream |
一个输入流。 |
| capacity |
渴望得到的缓冲器容积。 |
备注：
参数：
| stream |
一个输出流。 |
| capacity |
渴望得到的缓冲器容积。 |
备注：
参数：
| capacity |
可用到的字节数。 |
备注：
参数：
| data |
缓冲区内的支持数组 |
Remarks:
Params:
| data |
缓冲器内的支持数组。 |
| readable |
最初安排可读的字节数。 |
备注：
参数：
| stream |
一个输入流。 |
| size |
期望得到的缓冲器尺寸的提示。默认为管道定义的尺寸。 |
备注：
参数：
| stream |
一个输出流。 |
| size |
期望得到的缓冲器尺寸的提示。默认为管道定义的尺寸。 |
备注：
参数：
| data |
缓冲器内部的支持数组。所有内容被认为是有效的。 |
返回：
缓冲器实例。
备注：
参数：
| data |
缓冲器内部支持数组。 |
| readable |
被认为有效的数据的字节数。 |
返回：
缓冲器实例。
备注:
返回：
缓冲器的一个void[]切片。
备注：
返回缓冲器的一个void[]切片，从当前位置直到有效内容的限度。内容留在缓冲器中为将来提取。
参数：
| size |
要访问的字节数。 |
| eat |
要不要消耗内容。 |
返回：
备注：
要注意的是切片不能比缓冲器的尺寸大——在你只是简单地想要复制的内容地方用 fill(void[])方法代替，或用conduit.read()直接从附加管道提取。也要注意如果你需要保留切片，在缓冲器被压缩或重构前对它使用.dup。
例子：
1 2 3 4 5 |
// 用一些内容创建一个缓冲器。 auto buffer = new Buffer ("hello world"); // 消耗一切未读内容。 auto slice = buffer.slice (buffer.readable); |
参数：
| dst |
目的内容。 |
| bytes |
dst的尺寸。 |
返回：
备注：
参数：
| src |
到 _append 的内容。如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。 |
备注：
参数：
| src |
到 _append的内容。 |
| length |
在 src 中的字节数。如果如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。 |
备注：
参数：
| other |
有可用内容的缓冲器。 |
返回：
如果如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。
备注：
参数：
| raw |
要消耗的内容。这是逐字地消耗，并且用原始的二进制格式——没有隐式转换被执行。 |
备注：
例子：
1 2 3 |
auto path = new FilePath (somepath); path.produce (&buffer.consume); |
参数：
| size |
要移动的字节数。 |
返回：
备注：
也可以通过'size'字节让它成负的来翻转读位置。这可以用于支持预取（lookahead）操作。注意在缓冲器中可用的内容不足时负的size会失败（不能跳过超越开头）。
Params:
| scan |
要包含当前内容的委托。 |
返回：
备注：
每个模式被预期剥离定界符。一个文件尾（end-of-file）情况会引起尾部内容被放到记号中。请求在超过Eof会导致空匹配（长度为零）。
注意额外的迭代器和/或reader实例在绑定到一个公共缓冲器时会用密集连锁的步伐操作。
备注：
备注：
返回在缓冲器中还剩下的可读字节计数。这将作为limit() - position() 简单地计算。
备注：
参数：
| dg |
对提供的缓冲器访问到的回调函数。 |
返回：
备注：
委托将会在它写了有效内容时返回适当的字节数，错误发生时返回IConduit.Eof。
参数:
| dg |
对提供的缓冲器访问到的回调函数。 |
返回：
Remarks:
如果委托消耗了数据，它会返回消耗掉的字节数，如果要指示一个错误就返回IConduit.Eof。
返回：
备注：
限度是设置到数据剩余的总数。位置总是被重置到零。
返回：
备注：
返回：
备注：
过早到达Eof时抛出一个IOException（IO异常）。
备注：
返回：
备注：
返回：
备注：
Returns:
备注：
参数：
| conduit |
要绑定的管道。 |
备注：
缓冲区不需要一个外部管道来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它来在必要时导入/导出（import/export）内容。
参数：
| boutput |
要绑定的流。 |
备注：
缓冲区不需要一个外部流来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它来在必要时导入/导出（import/export）内容。
参数：
| binput |
要绑定的流。 |
备注：
缓冲区不需要一个外部流来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它们来在必要时导入/导出（import/export）内容。
备注：
参数：
| src |
内容的源。 |
| size |
在src上的内容的长度。 |
备注：
返回：
备注：