Skip to content

Convenience Utilities

Jump to bottom
kevin-montrose edited this page Apr 10, 2021 · 2 revisions

Convenience Utilities

Introduction

Cesil provides the CesilUtils class which has a number of methods for quickly reading and writing data to and from streams or files. These methods are not the most performant or most configurable ways to use Cesil, but they are very quick to use.

Reading

CesilUtils exposes the following methods for quick reading:

All returned enumerations are lazy, that is work will happen as you enumerate them.

When reading from a file, Cesil will attempt to detect encodings automatically using StreamReader's byte-order mark (BOM) inspection logic.

Writing

CesilUtils exposes the following methods for quick reading:

When writing to a file, Cesil will create the file (overwriting it if it already exists) and use the UTF-8 encoding when writing data.

Inefficiency

Using CesilUtils introduces the following inefficiencies:

IBoundConfiguration<TRow> Cannot Be Reused

CesilUtils makes a new configuration object for each invocation. This involves extensively consulting the ITypeDescriber of the given (or default) Options, and generating some code for reading or writing members of various types. Explicitly creating and managing your IBoundConfiguration<TRow> will let you re-use this work.

This inefficiency is only present if your code repeatedly reads or writes the same types with the same Options, giving you an opportunity to benefit from re-using the work.

Async Fast Paths in IAsyncReader<TRow> And IAsyncWriter<TRow>

The async code behind the interfaces goes through substantial effort to avoid using any async machinery if the code can complete synchronously without blocking. By contrast, the code behind CesilUtils is relatively simple and naive - only leveraging ValueTask to avoid unnecessary allocations.

This inefficiency is only likely to matter in very hot code paths where completing synchronously is commonplace.

Control

The various reading, writing, and configuration interfaces provide many methods that allow to control exactly what Cesil does in a fine grained manner. By contrast, CesilUtils only supports lazily reading and writing batches of rows to streams, files, or strings.

An incomplete list of things you can do with Cesil, but not directly with CesilUtils is:

Clone this wiki locally