tango.io.Buffer 翻译

(提交后发觉内容不在了很多，故加了一个附件）

tango.io.Buffer (r4792)

License:

BSD style: see license.txt

Version:

Mar 2004: Initial release Dec 2006: Outback release

Authors:

Kris

class Buffer : IBuffer ¶#

缓冲器是 TangoI/O的中心概念。每个缓冲器作为一个队列“ queue”（行， line）发挥作用，项目从前面被移除新项目添加到后面。缓冲器模型在 tango.io.model.IBuffer中，一个具体的实现通过这个类提供。

缓冲器可以直接读、写，不过各种数据转换器和过滤器通常可以起杠杆作用应用到使用简单的原始数据（ raw data)的结构上。

缓冲器也可以通过应用一个迭代器被标记化（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()方法。

invariant ¶#

确保在方法调用期保持有效。

this(IConduit conduit) ¶#

构造一个缓冲器。

参数：

conduit

到缓冲器的管道。

备注：

在提供的管道上构造一个缓冲器。一个相关的缓冲器大小通过提供的管道提供。

this(InputStream stream, size_t capacity) ¶#

构造一个缓冲器。

参数：

stream	一个输入流。
capacity	渴望得到的缓冲器容积。

备注：

在提供的输入流上构造一个缓冲器。

this(OutputStream stream, size_t capacity) ¶#

构造一个缓冲器。

参数：

stream	一个输出流。
capacity	渴望得到的缓冲器容积。

备注：

在提供的输出流上构造一个缓冲器。

this(size_t capacity = 0) ¶#

构造一个缓冲器。

参数：

capacity

可用到的字节数。

备注：

用指定的字节数构造一个缓冲器。

this(void[] data) ¶#

构造一个缓冲器。

参数：

data

缓冲区内的支持数组

Remarks:

用一个应用程序提供的数组准备好（ Prime ）一个缓冲器。所有内容均视为读时有效，因此没有可写空间在最初可用。

this(void[] data, size_t readable) ¶#

构造一个缓冲器。

Params:

data	缓冲器内的支持数组。
readable	最初安排可读的字节数。

备注：

用应用程序提供的数组准备缓冲器，并指明在那里已经有多少可读数据准备好。一个写操作在一存在可读内容后就开始写。

这通常用于附加一个缓冲器实例到局部数组。

IBuffer share(InputStream stream, size_t size = size_t.max) [static] ¶#

试图共享一个上游缓冲器，没有可用缓冲器的地方就创建一个实例。

参数：

stream	一个输入流。
size	期望得到的缓冲器尺寸的提示。默认为管道定义的尺寸。

备注：

如果一个上游缓冲器是可见的，它将被共享。否则，将创建一个基于流末端 endpoint（管道）揭示的缓冲器尺寸的缓冲器实例。

IBuffer share(OutputStream stream, size_t size = size_t.max) [static] ¶#

试图共享一个上游缓冲器，没有可用缓冲器的地方就创建一个实例。

参数：

stream	一个输出流。
size	期望得到的缓冲器尺寸的提示。默认为管道定义的尺寸。

备注：

如果一个上游缓冲器是可见的，它将被共享。否则，将创建一个基于流末端 endpoint（管道）揭示的缓冲器尺寸的缓冲器实例。

IBuffer setContent(void[] data) ¶#

重置缓冲器内容。

参数：

data	缓冲器内部的支持数组。所有内容被认为是有效的。

返回：

缓冲器实例。

备注：

用所有可读的内容设置支持数组。写到它将会冲刷到关联管道或引发一个 Eof状态。用 clear() 去重置内容（让它全部可写）。

IBuffer setContent(void[] data, size_t readable) ¶#

重置缓冲器内容。

参数：

data	缓冲器内部支持数组。
readable	被认为有效的数据的字节数。

返回：

缓冲器实例。

备注:

用一些可读内容设置支持数组。写到它将会冲刷到关联管道或引发一个 Eof状态。用 clear()方法重置内容（让它全部可写）。

void[] slice() ¶#

取回有效的内容。

返回：

缓冲器的一个void[]切片。

备注：

返回缓冲器的一个void[]切片，从当前位置直到有效内容的限度。内容留在缓冲器中为将来提取。

void[] opSlice(size_t start, size_t end) [final] ¶#

返回缓冲器从开始到末尾的一个 void[] 切片，末尾是唯一的。

void[] slice(size_t size, bool eat = true) ¶#

访问缓冲器内容。

参数：

size	要访问的字节数。
eat	要不要消耗内容。

返回：

成功时，相应的缓冲器切片，没有足够数据可用 (Eof; Eob)时返回 null。

备注：

从缓冲器读数据的切片，根据情况从管道载入。指定的字节数从缓冲器中被切割， 'eat'参数设置为 true时标记为已读。 'eat'参数设置为 false时，读位置不被调整。

要注意的是切片不能比缓冲器的尺寸大——在你只是简单地想要复制的内容地方用 fill(void[])方法代替，或用conduit.read()直接从附加管道提取。也要注意如果你需要保留切片，在缓冲器被压缩或重构前对它使用.dup。

例子：

1 2 3 4 5

// 用一些内容创建一个缓冲器。 auto buffer = new Buffer ("hello world"); // 消耗一切未读内容。 auto slice = buffer.slice (buffer.readable);

size_t fill(void[] dst) ¶#

填充提供的缓冲器。返回实际上已读的字节数，当 Eof已经到达或 IConduit.Eof之后它要比 dst.length小。

void[] readExact(void* dst, size_t bytes) ¶#

复制缓冲器内容到提供的 dst。

参数：

dst	目的内容。
bytes	dst的尺寸。

返回：

一个到组成内容的引用。

备注：

用内容填充提供的数组。我们设法满足缓冲器内容的要求，在需要更多内容的地方我们直接从一个附加管道读取。

IBuffer append(void[] src) ¶#

添加内容。

参数：

src	到 _append 的内容。如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。

备注：

添加一个数组到这个缓冲器，并视情况冲刷到管道。这通常用于代替一个 Writer。

IBuffer append(void* src, size_t length) ¶#

添加内容。

参数：

src	到 _append的内容。
length	在 src 中的字节数。如果如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。

备注：

添加一个数组到这个缓冲器，并视情况冲刷到管道。这通常用于代替一个 Writer。

IBuffer append(IBuffer other) ¶#

添加内容。

参数：

other

有可用内容的缓冲器。

返回：

如果如果所有内容已经写就返回一个连锁引用，否则抛出一个IOException异常指出eof 或 eob。

备注：

添加另一个缓冲器到这个，并视情况冲刷到管道，这通常用于代替一个 Writer。。

void consume(void[] x) ¶#

从一个生产者消耗内容。

参数：

raw	要消耗的内容。这是逐字地消耗，并且用原始的二进制格式——没有隐式转换被执行。

备注：

这通常用于替换一个 Writer，使简单的类，如 FilePath和 Uri，可以直接发送内容到一个缓冲器（这样可以避免潜在的堆活动）。

例子：

1 2 3

auto path = new FilePath (somepath); path.produce (&buffer.consume);

bool skip(int size) ¶#

移动当前读的位置。

参数：

size

要移动的字节数。

返回：

成功返回 true，否则返回 false。

备注：

向前路过指定的字节数，必要时从关联的管道流过。

也可以通过'size'字节让它成负的来翻转读位置。这可以用于支持预取（lookahead）操作。注意在缓冲器中可用的内容不足时负的size会失败（不能跳过超越开头）。

bool next(size_t delegate (void[]) scan) ¶#

迭代器支持。

Params:

scan	要包含当前内容的委托。

返回：

如果记号是孤立的返回 true，否则返回 false。

备注：

在成功后，委托会返回基于字节的耗尽模式（它的尾端）的索引。失败时返回一个 IConduit.Eof指明匹配模式。

每个模式被预期剥离定界符。一个文件尾（end-of-file）情况会引起尾部内容被放到记号中。请求在超过Eof会导致空匹配（长度为零）。

注意额外的迭代器和/或reader实例在绑定到一个公共缓冲器时会用密集连锁的步伐操作。

bool compress(bool yes) [final] ¶#

为迭代器配置压缩策略。

备注：

为了给新数据留出最大的空间，迭代器倾向于压缩已缓冲的内容。你可以通过设置这个布尔值为 false禁用这个行为。

size_t readable() ¶#

可用的内容。

备注：

返回在缓冲器中还剩下的可读字节计数。这将作为limit() - position() 简单地计算。

size_t writable() ¶#

可用空间。

备注：

返回在缓冲器中可用的可写字节计数。这将作为 limit() - position() 简单地计算。

size_t reserve(size_t space) [final] ¶#

在缓冲器中预留指定空间，必要时压缩存在内容让出地方。

返回当前读的地方，如果需要的话之后进行压缩。

size_t writer(size_t delegate (void[]) dg) ¶#

写进这个缓冲器。

参数：

dg	对提供的缓冲器访问到的回调函数。

返回：

返回委托返回的东西。

备注：

揭示在当前写位置的原始数据缓冲器，委托用 void[]表示的对当前写位置的缓冲器中可用空间来提供。

委托将会在它写了有效内容时返回适当的字节数，错误发生时返回IConduit.Eof。

size_t reader(size_t delegate (void[]) dg) ¶#

直接从缓冲器中读取。

参数:

dg	对提供的缓冲器访问到的回调函数。

返回：

返回委托返回的东西。

Remarks:

揭示在当前读位置的原始数据缓冲器。委托用一个 void[]表示的可用数据提供，离开当前完好无损的读位置会返回 0。

如果委托消耗了数据，它会返回消耗掉的字节数，如果要指示一个错误就返回IConduit.Eof。

IBuffer compress() ¶#

压缩缓冲器空间。

返回：

缓冲器实例。

备注：

如果我们有一些数据在输出后留下，移动它到缓冲器前面并设置位置到留下部分的紧跟后面。这是为了支持要选择写刚好请求的初始部分的某些管道。

限度是设置到数据剩余的总数。位置总是被重置到零。

size_t fill(InputStream src) ¶#

从指定管道填充缓冲器。

返回：

返回读取的字节数或 Conduit.Eof 。

备注：

试图用从指定管道的内容去填充可用的缓冲器。当所有内容已经被吃掉时我们试图通过清除缓冲器而尽可能多地读取。如果没有空间可用，没有东西被读取。

size_t drain(OutputStream dst) [final] ¶#

排尽缓冲器内容到指定管道。

返回：

返回已写的字节数。

备注：

写出尽可能多的缓冲器内容，关联管道可以消耗。管道不被强制消耗所有内容，因此有些可能会留在缓冲器中。

过早到达Eof时抛出一个IOException（IO异常）。

bool truncate(size_t length) ¶#

截短缓冲器内容。

备注：

截取缓冲区在它的范围内。如果新长度有效返回 true，否则返回 false。

size_t limit() ¶#

访问缓冲区限度。

返回：

返回在这个缓冲区内可读内容的限度。

备注：

每个缓冲区有一个容积（ capacity）、一个限度（ limit）、和一个位置（ position）。容积是缓冲区可以容纳的最大内容，限度表示有效内容的范围，位置标记当前读取位置。

size_t capacity() ¶#

访问缓冲区容积。

返回：

返回这个缓冲区的最大容积。

备注：

每个缓冲区有一个容积（ capacity）、一个限度（ limit）、和一个位置（ position）。容积是缓冲区可以容纳的最大内容，限度表示有效内容的范围，位置标记当前读取位置。

size_t position() ¶#

访问缓冲区读取的位置。

Returns:

Returns the current read-position within this buffer

备注：

每个缓冲区有一个容积（ capacity）、一个限度（ limit）、和一个位置（ position）。容积是缓冲区可以容纳的最大内容，限度表示有效内容的范围，位置标记当前读取位置。

IBuffer setConduit(IConduit conduit) ¶#

设置外部管道。

参数：

conduit

要绑定的管道。

备注：

设置与这个缓冲区关联的外部管道。

缓冲区不需要一个外部管道来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它来在必要时导入/导出（import/export）内容。

IBuffer output(OutputStream boutput) [final] ¶#

设置输出流。

参数：

boutput

要绑定的流。

备注：

设置与这个缓冲区关联的外部输出流。

缓冲区不需要一个外部流来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它来在必要时导入/导出（import/export）内容。

IBuffer input(InputStream binput) [final] ¶#

设置输入流。

参数：

binput

要绑定的流。

备注：

设置与这个缓冲区关联的外部输入流。

缓冲区不需要一个外部流来操作，但它可以方便地关联一个。例如，方法fill() & drain()用它们来在必要时导入/导出（import/export）内容。

void[] getContent() [protected] ¶#

访问缓冲区内容。

备注：

返回完整的支持数组（ backing array)。仅为子类用法展示。

void copy(void * src, size_t size) [protected] ¶#

复制内容到缓冲区。

参数：

src	内容的源。
size	在src上的内容的长度。

备注：

从 'src'的散装（ Bulk）数据副本。新内容可以给读取用。这个仅展示给子类使用。

size_t expand(size_t size) [protected] ¶#

扩大现有的缓冲区空间。

返回：

可用空间 ,没有任何的扩张。

备注：

放一些额外空间到缓冲区中，至少是规定尺寸。这可以被子类酌情使用。

T[] convert(T)(void[] x) [static] ¶#

转换到目标类型，没有为误差（ misalignment）调用运行时检查的愤怒（ wrath）。相反 ,我们截短了数组的长度。

IBuffer buffer() ¶#

缓冲区接口。

InputBuffer bin() ¶#