Error

`BlockStream` used to initialize a stream of type `Block`. This `BlockStream` refers to the stream that embedded to
the I/O byte channels.


Initialize a `BlockStream` using a `io:ReadableByteChannel`.



init

The `io:ReadableByteChannel` that this block stream is referred to


readableByteChannel

ReadableByteChannel

blockSize

The next function reads and return the next block of the related stream.



close

Returns null when the closing was successful or an `io:Error`


BlockStream

`LineStream` used to initialize a stream of type strings(lines). This `LineStream` refers to the stream that embedded to
the I/O record channels.


Initialize a `CSVStream` using a `io:ReadableTextRecordChannel`.



The `io:ReadableTextRecordChannel` that this CSV stream is referred to


readableTextRecordChannel

ReadableTextRecordChannel

The next function reads and return the next CSV record of the related stream.



Returns a CSV record as a string array when a record is avaliable in the stream or
return null when the stream reaches the end


Close the stream. The primary usage of this function is to close the stream without reaching the end.
If the stream reaches the end, the `csvStream.next()` will automatically close the stream.



CSVStream

`LineStream` used to initialize a stream of type strings(lines). This `LineStream` refers to the stream that embedded to
the I/O character channels.


Initialize a `LineStream` using a `io:ReadableCharacterChannel`.



The `io:ReadableCharacterChannel` that this line stream is referred to


readableCharacterChannel

ReadableCharacterChannel

The next function reads and return the next line of the related stream.



Returns a line as a string when a line is avaliable in the stream or return null when the stream reaches the end


Close the stream. The primary usage of this function is to close the stream without reaching the end.
If the stream reaches the end, the `lineStream.next()` will automatically close the stream.



LineStream

ReadableByteChannel represents an input resource (i.e file). which could be used to source bytes.
A file path or an in-memory `byte` array can be used to obtain a `io:ReadableByteChannel`.
A `io:ReadableByteChannel` do not support initilization, and it should be obtained using the following methods or implement natively.
`io:openReadableFile("./files/sample.txt")` - used to obtain a `io:ReadableByteChannel` from a given file path
`io:createReadableChannel(byteArray)` - used to obtain a `io:ReadableByteChannel` from a given `byte` array


Source bytes from a given input resource.
This operation will be asynchronous in which the total number of required bytes might not be returned at a given
time. An `io:EofError` will return once the channel reaches the end.
```ballerina
byte[]|io:Error result = readableByteChannel.read(1000);
```



read

A positive integer. Represents the number of bytes, which should be read


nBytes

Content (the number of bytes) read, an `EofError` once the channel reaches the end or else an `io:Error`


Read all content of the channel as a `byte` array and return a read only `byte` array.
```ballerina
byte[]|io:Error result = readableByteChannel.readAll();
```



readAll

Either a read only `byte` array or else an `io:Error`


Return a block stream that can be used to read all `byte` blocks as a stream.
```ballerina
stream<io:Block, io:Error>|io:Error result = readableByteChannel.blockStream();
```


blockStream

Either a block stream or else an `io:Error`


Encodes a given `ReadableByteChannel` using the Base64 encoding scheme.
```ballerina
io:ReadableByteChannel|Error encodedChannel = readableByteChannel.base64Encode();
```



base64Encode

An encoded `ReadableByteChannel` or else an `io:Error`


Decodes a given Base64 encoded `io:ReadableByteChannel`.
```ballerina
io:ReadableByteChannel|Error encodedChannel = readableByteChannel.base64Decode();
```



base64Decode

A decoded `ReadableByteChannel` or else an `io:Error`


Closes a given `ReadableByteChannel`.
After a channel is closed, any further reading operations will cause an error.
```ballerina
io:Error? err = readableByteChannel.close();
```



Represents a channel, which could be used to read characters through a given ReadableByteChannel.


Constructs a `ReadableCharacterChannel` from a given `ReadableByteChannel` and `Charset`.



The `ReadableByteChannel`, which would be used to read the characters


byteChannel

The character set, which would be used to encode/decode the given bytes to characters


charset

string

Reads a given number of characters. This will attempt to read up to the `numberOfChars` characters of the channel.
An `io:EofError` will return once the channel reaches the end.
```ballerina
string|io:Error result = readableCharChannel.read(1000);
```



Number of characters, which should be read


numberOfChars

Content, which is read, an `EofError` once the channel reaches the end or else an `io:Error`


Read the entire channel content as a string.
```ballerina
string|io:Error content = readableCharChannel.readString();
```


readString

Read the entire channel content as a list of lines.
```ballerina
string[]|io:Error content = readableCharChannel.readAllLines();
```


readAllLines

Reads a JSON from the given channel.
```ballerina
json|io:Error result = readableCharChannel.readJson();
```



readJson

The read JSON string or else an `io:Error`


Reads an XML from the given channel.
```ballerina
json|io:Error result = readableCharChannel.readXml();
```



readXml

Reads a property from a .properties file with a default value.
```ballerina
string|io:Error result = readableCharChannel.readProperty(key, defaultValue);
```


readProperty

defaultValue

The read property value or else an `io:Error`


Return a stream of lines that can be used to read all the lines in a file as a stream.
```ballerina
stream<string, io:Error>|io:Error? result = readableCharChannel.lineStream();
```



lineStream

Either a stream of strings(lines) or an io:Error.


Reads all properties from a .properties file.
```ballerina
map<string>|io:Error result = readableCharChannel.readAllProperties();
```



readAllProperties

Closes a given character channel.
After a channel is closed, any further reading operations will cause an error.
```ballerina
io:Error? err = readableCharChannel.close();
```



Represents a ReadableCSVChannel which could be used to read records from CSV file.


Constructs a CSV channel from a CharacterChannel to read/write CSV records.



The CharacterChannel, which will represent the content in the CSV file


Field separator, which will separate between the records in the CSV file


Separator

Number of headers, which should be skipped prior to reading records


nHeaders

Skips the given number of headers.
```ballerina
readableCSVChannel.skipHeaders(5);
```



skipHeaders

The number of headers, which should be skipped


Indicates whether there's another record, which could be read.
```ballerina
boolean hasNext = readableCSVChannel.hasNext();
```



hasNext

boolean

Gets the next record from the CSV file.
```ballerina
string[]|io:Error? record = readableCSVChannel.getNext();
```



getNext

List of fields in the CSV or else an `io:Error`


Returns a CSV record stream that can be used to CSV records as a stream.
```ballerina
stream<string[], io:Error>|io:Error? record = readableCSVChannel.csvStream();
```



csvStream

Either a stream of records(string[]) or else an `io:Error`


Closes a given `CSVChannel`.
After a channel is closed, any further reading operations will cause an error.
```ballerina
io:Error? err = readableCSVChannel.close();
```



Returns a table, which corresponds to the CSV records.
```ballerina
var tblResult1 = readableCSVChannel.getTable(Employee);
var tblResult2 = readableCSVChannel.getTable(Employee, ["id", "name"]);
```



getTable

The object in which the CSV records should be deserialized


structType

The names of the fields used as the (composite)key of the table


fieldNames

Table, which represents the CSV records or else an `io:Error`


ReadableCSVChannel

Represents a data channel for reading data.


The channel, which would represent the source to read/write data


bOrder

ByteOrder

Reads a 16 bit integer.
```ballerina
int|io:Error result = dataChannel.readInt16();
```



readInt16

The value of the integer, which is read or else an `io:Error` if any error occurred


Reads a 32 bit integer.
```ballerina
int|io:Error result = dataChannel.readInt32();
```



readInt32

Reads a 64 bit integer.
```ballerina
int|io:Error result = dataChannel.readInt64();
```



readInt64

Reads a 32 bit float.
```ballerina
float|io:Error result = dataChannel.readFloat32();
```



readFloat32

The value of the float which is read or else `io:Error` if any error occurred


Reads a 64 bit float.
```ballerina
float|io:Error result = dataChannel.readFloat64();
```



readFloat64

Reads a byte and convert its value to boolean.
```ballerina
boolean|io:Error result = dataChannel.readBool();
```



readBool

boolean value which is read or else `io:Error` if any error occurred


Reads the string value represented through the provided number of bytes.
```ballerina
string|io:Error string = dataChannel.readString(10, "UTF-8");
```



Specifies the number of bytes, which represents the string


Specifies the char-set encoding of the string


encoding

The value of the string or else `io:Error` if any error occurred


Reads a variable length integer.
```ballerina
int|io:Error result = dataChannel.readVarInt();
```



readVarInt

The value of the integer which is read or else `io:Error` if any error occurred


Closes the data channel.
After a channel is closed, any further reading operations will cause an error.
```ballerina
io:Error? err = dataChannel.close();
```


`()` if the channel is closed successfully or else an `io:Error` if any error occurred


ReadableDataChannel

Represents a channel which will allow to read.


Constructs a ReadableTextRecordChannel from a given ReadableCharacterChannel.



CharacterChannel which will point to the input/output resource


charChannel

Record separator (this could be a regex)


Checks whether there's a record left to be read.
```ballerina
boolean hasNext = readableRecChannel.hasNext();
```



True if there's a record left to be read


Get the next record from the input/output resource.
```ballerina
string[]|io:Error record = readableRecChannel.getNext();
```



Set of fields included in the record or else `io:Error`


Closes a given record channel.
After a channel is closed, any further reading operations will cause an error.
```ballerina
io:Error err = readableRecChannel.close();
```



An `io:Error` if the record channel could not be closed properly


Represents a reader which will wrap string content as a channel.


content

Encoding of the characters of the content


Reads string as JSON using the reader.
```ballerina
io:StringReader reader = new("{\"name\": \"Alice\"}");
json|io:Error? person = reader.readJson();
```



JSON or else `io:Error` if any error occurred


Reads a string as XML using the reader.
```ballerina
io:StringReader reader = new("<Person><Name>Alice</Name></Person>");
xml|io:Error? person = reader.readXml();
```



XML or else `io:Error` if any error occurred


Reads the characters from the given string.
```ballerina
io:StringReader reader = new("Some text");
string|io:Error? person = reader.readChar(4);
```



readChar

nCharacters

String or else `io:Error` if any error occurred


Closes the reader.
```ballerina
io:Error? err = reader.close();
```



An `io:Error` if could not close the channel or else `()`


StringReader

WritableByteChannel represents an output resource (i.e file) which could be used to sink bytes
A file path can be used to obtain a `io:WritableByteChannel`.
A `io:WritableByteChannel` can only be obtained using the following method or by providing a native implementation.
It cannot be instantiated.
`io:openWritableFile("./files/sample.txt")` - used to obtain a `io:WritableByteChannel` from a given file path


Sinks bytes from a given input/output resource.

This is an asynchronous operation. The method might return before writing all the content.
```ballerina
int|io:Error result = writableByteChannel.write(record, 0);
```



write

Offset of the provided content, which needs to be kept when writing bytes


offset

Number of bytes written or else `io:Error`


Closes a given byte channel.
After a channel is closed, any further writing operations will cause an error.
```ballerina
io:Error err = writableByteChannel.close();
```



WritableByteChannel

Represents a channel which could be used to write characters through a given WritableCharacterChannel.


Constructs a `WritableByteChannel` from a given `WritableByteChannel` and `Charset`.



The `WritableByteChannel`, which would be used to write the characters


bChannel

The character set, which would be used to encode the given bytes to characters


Writes a given sequence of characters (string).
```ballerina
int|io:Error result = writableCharChannel.write("Content", 0);
```



Number of characters to be offset when writing the content


startOffset

Content length that written or else `io:Error`


Writes a string as a line with a following newline character `\n`.
```ballerina
io:Error? result = writableCharChannel.writeLine("Content");
```



writeLine

Returns null if the writing was successful or an `io:Error`


Writes a given JSON to the given channel.
```ballerina
io:Error? err = writableCharChannel.writeJson(inputJson, 0);
```



writeJson

json

Writes a given XML to the channel.
```ballerina
io:Error? err = writableCharChannel.writeXml(inputXml, 0);
```



writeXml

Optional argument to specify the XML DOCTYPE configurations


xmlDoctype

XmlDoctype

`()` or else `io:Error` if any error occurred


Writes a given key-valued pair `map<string>` to a property file.
```ballerina
io:Error? err = writableCharChannel.writeProperties(properties);
```


writeProperties

The map<string> that contains keys and values


properties

comment

Closes a given `WritableCharacterChannel` channel.
After a channel is closed, any further writing operations will cause an error.
```ballerina
io:Error err = writableCharChannel.close();
```



`()` or else an `io:Error` if any error occurred


WritableCharacterChannel

## Package Overview

The following diagram depicts the overview architecture of the I/O package.

![architecture](./resources/package-architecture.svg)

The I/O package allows you to read from the console or a file. 
Further, the file I/O operations can be categorized based on serialization and deserialization types such as:
- Bytes I/O
- Strings I/O
- CSV I/O
- JSON I/O
- XML I/O


### Console I/O
The console I/O APIs, which help the user to read from the console as well as write to the console are as follows.
- print
- println
- readln

### Bytes I/O
The bytes I/O APIs provide the reading and writing APIs in both streaming and non-streaming ways. Those APIs are,
- `io:fileReadBytes`
- `io:fileReadBlocksAsStream`
- `io:fileWriteBytes`
- `io:fileWriteBlocksFromStream`

To learn how to use bytes read and write APIs, see the [Read/Write Bytes example](https://ballerina.io/learn/by-example/bytes-io.html).

### Strings I/O
The strings I/O APIs provide the reading and writing APIs in 3 different ways:
1. Read the whole file content as a string and write a given string to a file
1. Read the whole file content as a set of lines and write a given set of lines to a file
1. Read the whole file content as a stream of lines and write a given stream of lines to a file

The strings I/O APIs are as follows:
- `io:fileReadString`
- `io:fileReadLines`
- `io:fileReadLinesAsStream`
- `io:fileWriteLines`
- `io:fileWriteLinesFromStream`

To learn how to use strings read and write APIs, see the  [Read/Write Strings example](https://ballerina.io/learn/by-example/strings-io.html).

### CSV I/O
The CSV I/O APIs provide the reading and writing APIs in both streaming and non-streaming ways. Those APIs are,
- `io:fileReadCsv`
- `io:fileReadCsvAsStream`
- `io:fileWriteCsv`
- `io:fileWriteCsvFromStream`

To learn how to use CSV read and write APIs, see the [Read/Write CSV example](https://ballerina.io/learn/by-example/csv-io.html).

### JSON I/O
The JSON I/O APIs provide the reading and writing APIs for JSON content. Those APIs are,
- `io:fileReadJson`
- `io:fileWriteJson`

To learn how to use JSON read and write APIs, see the [Read/Write JSON example](https://ballerina.io/learn/by-example/json-io.html).

### XML I/O
The XML I/O APIs provide the reading and writing APIs for XML content. Those APIs are,
- `io:fileReadXml`
- `io:fileWriteXml`

To learn how to use XML read and write APIs, see the [Read/Write XML example](https://ballerina.io/learn/by-example/json-io.html).


The following diagram depicts the overview architecture of the I/O package.


Errors