java.lang.Object
- swim.codec.Encoder<I,O>
- - swim.codec.Writer<I,O>

```
public abstract class Writer<I,O>
extends Encoder<I,O>
```
Continuation of how to write subsequent Output tokens to a stream. Writer enables efficient, interruptible writing of network protocols and data formats, without intermediate buffering.
Output tokens

A Writer writes tokens to an Output writer. Output tokens are modeled as primitive ints, commonly representing Unicode code points, or raw octets. Each Writer implementation specifies the semantic type of output tokens it produces.

Writer states

A Writer is always in one of three states: continue, done, or error. The cont state indicates that pull is ready to produce Output; the done state indicates that writing terminated successfully, and that bind will return the written result; the error state indicates that writing terminated in failure, and that trap will return the write error. Writer subclasses default to the cont state.

Feeding input

The feed(I) method returns a Writer that represents the continuation of how to write the given input object to subsequent Output writers. feed can be used to specify an initial object to write, or to change the object to be written.

Pulling output

The pull(Output) method incrementally writes as much Output as it can, before returning another Writer that represents the continuation of how to write additional Output. The Output passed to pull is only guaranteed to be valid for the duration of the method call; references to the provided Output instance must not be stored.

Writer results

A Writer produces a written result of type O, obtained via the bind() method. bind is only guaranteed to return a result when in the done state; though bind may optionally make available partial results in other states. A failed Writer provides a write error via the trap() method. trap is only guaranteed to return an error when in the error state.

Continuations

A Writer instance represents a continuation of how to write remaining Output. Rather than writing a complete output in one go, a Writer takes an Output chunk and returns another Writer instance that knows how to write subsequent Output chunks. This enables non-blocking, incremental writing that can be interrupted whenever an Output writer runs out of space. A Writer terminates by returning a continuation in either the done state, or the error state. done(Object) returns a Writer in the done state. error(Throwable) returns a Writer in the error state.

Forking

The fork(Object) method passes an out-of-band condition to a Writer, yielding a Writer continuation whose behavior may be altered by the given condition. For example, a console Writer might support a fork condition that changes the color and style of printed text. The types of conditions accepted by fork, and their intended semantics, are implementation defined.

Constructor Summary

Constructors
Constructor Description

Writer()

Method Summary

Modifier and Type	Method	Description
`<O2> Writer<I,O2>`	`andThen(Encoder<I,O2> that)`	Returns an `Encoder` that continues encoding `that` `Encoder`, after it finishes encoding `this` `Encoder`.
`<O2> Writer<I,O2>`	`andThen(Writer<I,O2> that)`	Returns a `Writer` that continues writing `that` `Writer`, after it finishes writing `this` `Writer`.
`<I2> Writer<I2,O>`	`asDone()`	Casts a done `Writer` to a different input type.
`<I2,O2> Writer<I2,O2>`	`asError()`	Casts an errored `Writer` to different input and output types.
`O`	`bind()`	Returns the written result.
`static <I,O> Writer<I,O>`	`done()`	Returns a `Writer` in the done state that `bind`s a `null` written result.
`static <I,O> Writer<I,O>`	`done(O output)`	Returns a `Writer` in the done state that `bind`s the given written `output`.
`static <I,O> Writer<I,O>`	`error(Throwable error)`	Returns a `Writer` in the error state that `trap`s the given write `error`.
`Writer<I,O>`	`feed(I input)`	Returns a `Writer` that represents the continuation of how to write the given `input` object.
`Writer<I,O>`	`fork(Object condition)`	Returns a `Writer` continuation whose behavior may be altered by the given out-of-band `condition`.
`boolean`	`isCont()`	Returns `true` when `pull` is able to produce `Output`.
`boolean`	`isDone()`	Returns `true` when writing has terminated successfully, and `bind` will return the written result.
`boolean`	`isError()`	Returns `true` when writing has terminated in failure, and `trap` will return the write error.
`abstract Writer<I,O>`	`pull(Output<?> output)`	Incrementally writes as much `output` as possible, and returns another `Writer` that represents the continuation of how to write additional `Output`.
`Writer<I,O>`	`pull(OutputBuffer<?> output)`	Incrementally encodes as much `output` buffer data as possible, and returns another `Encoder` that represents the continuation of how to write additional buffer data.
`Throwable`	`trap()`	Returns the write error.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Writer
```
public Writer()
```
- Method Detail
  - done
```
public static <I,O> Writer<I,O> done()
```
    Returns a Writer in the done state that binds a null written result.
  - done
```
public static <I,O> Writer<I,O> done(O output)
```
    Returns a Writer in the done state that binds the given written output.
  - error
```
public static <I,O> Writer<I,O> error(Throwable error)
```
    Returns a Writer in the error state that traps the given write error.
  - isCont
```
public boolean isCont()
```
    Returns true when pull is able to produce Output. i.e. this Writer is in the cont state.
    
    Overrides:
    
    isCont in class Encoder<I,O>
  - isDone
```
public boolean isDone()
```
    Returns true when writing has terminated successfully, and bind will return the written result. i.e. this Writer is in the done state.
    
    Overrides:
    
    isDone in class Encoder<I,O>
  - isError
```
public boolean isError()
```
    Returns true when writing has terminated in failure, and trap will return the write error. i.e. this Writer is in the error state.
    
    Overrides:
    
    isError in class Encoder<I,O>
  - feed
```
public Writer<I,O> feed(I input)
```
    Returns a Writer that represents the continuation of how to write the given input object.
    
    Overrides:
    
    feed in class Encoder<I,O>
    
    Throws:
    
    IllegalArgumentException - if this Writer does not know how to write the given input object.
  - pull
```
public abstract Writer<I,O> pull(Output<?> output)
```
    Incrementally writes as much output as possible, and returns another Writer that represents the continuation of how to write additional Output. If output enters the done state, pull must return a terminated Writer, i.e. a Writer in the done state, or in the error state. The given output is only guaranteed to be valid for the duration of the method call; references to output must not be stored.
  - pull
```
public Writer<I,O> pull(OutputBuffer<?> output)
```
    Description copied from class: Encoder
    
    Incrementally encodes as much output buffer data as possible, and returns another Encoder that represents the continuation of how to write additional buffer data. If isLast is true, then pull must return a terminated Encoder, i.e. an Encoder in the done state, or in the error state. The given output buffer is only guaranteed to be valid for the duration of the method call; references to output must not be stored.
    
    Specified by:
    
    pull in class Encoder<I,O>
  - fork
```
public Writer<I,O> fork(Object condition)
```
    Returns a Writer continuation whose behavior may be altered by the given out-of-band condition.
    
    Overrides:
    
    fork in class Encoder<I,O>
  - bind
```
public O bind()
```
    Returns the written result. Only guaranteed to return a result when in the done state.
    
    Overrides:
    
    bind in class Encoder<I,O>
    
    Throws:
    
    IllegalStateException - if this Writer is not in the done state.
  - trap
```
public Throwable trap()
```
    Returns the write error. Only guaranteed to return an error when in the error state.
    
    Overrides:
    
    trap in class Encoder<I,O>
    
    Throws:
    
    IllegalStateException - if this Writer is not in the error state.
  - asDone
```
public <I2> Writer<I2,O> asDone()
```
    Casts a done Writer to a different input type. A Writer in the done state can have any input type.
    
    Overrides:
    
    asDone in class Encoder<I,O>
    
    Throws:
    
    IllegalStateException - if this Writer is not in the done state.
  - asError
```
public <I2,O2> Writer<I2,O2> asError()
```
    Casts an errored Writer to different input and output types. A Writer in the error state can have any input type, and any output type.
    
    Overrides:
    
    asError in class Encoder<I,O>
    
    Throws:
    
    IllegalStateException - if this Writer is not in the error state.
  - andThen
```
public <O2> Writer<I,O2> andThen(Writer<I,O2> that)
```
    Returns a Writer that continues writing that Writer, after it finishes writing this Writer.
  - andThen
```
public <O2> Writer<I,O2> andThen(Encoder<I,O2> that)
```
    Description copied from class: Encoder
    
    Returns an Encoder that continues encoding that Encoder, after it finishes encoding this Encoder.
    
    Overrides:
    
    andThen in class Encoder<I,O>

Class Writer<I,​O>

Output tokens

Writer states

Feeding input

Pulling output

Writer results

Continuations

Forking

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Writer

Method Detail

done

done

error

isCont

isDone

isError

feed

pull

pull

fork

bind

trap

asDone

asError

andThen

andThen

Class Writer<I,O>