Class LrcWriter

Namespace

ModernLrc

Assembly

ModernLrc.dll

Entry-point for writing an LrcDocument. All overloads converge on the canonical Write(LrcDocument, LrcWriteOptions?).

public static class LrcWriter

Inheritance

object

LrcWriter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using ModernLrc;
using ModernLrc.Model;

var doc = new LrcDocumentBuilder()
    .WithTitle("My Song")
    .AddLine("00:12.00", "first line")
    .AddLine("00:14.20", "second line", LrcVoice.Female)
    .Build();

string lrc = LrcWriter.Write(doc);
// [ti:My Song]
//
// [00:12.00]first line
// [00:14.20]F: second line

Remarks

Sinks: string, TextWriter, Stream, IBufferWriter<T> (chars or encoded bytes), fixed Span<T> (via the TryWrite family), and a path on disk (WriteFile(LrcDocument, string, LrcWriteOptions?), atomic via temp + rename).

The IBufferWriter<T> char sink and UTF-8 byte sinks are zero-allocation beyond consumer-buffer growth.

Methods

EstimateByteSize(LrcDocument, LrcWriteOptions?)

O(lines + words + tags) byte-length estimate (UTF-8 worst-case: up to 4 bytes per char + headroom).

[Pure]
public static int EstimateByteSize(LrcDocument document, LrcWriteOptions? options = null)

Parameters

document LrcDocument

options LrcWriteOptions

Returns

int

EstimateSize(LrcDocument, LrcWriteOptions?)

O(lines + words + tags) char-length estimate. Pure.

[Pure]
public static int EstimateSize(LrcDocument document, LrcWriteOptions? options = null)

Parameters

document LrcDocument

options LrcWriteOptions

Returns

int

TryWrite(LrcDocument, Span<byte>, out int, LrcWriteOptions?)

Try-render into a fixed byte buffer using Encoding.

public static bool TryWrite(LrcDocument document, Span<byte> destination, out int bytesWritten, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

destination Span<byte>

Destination span.

bytesWritten int

Number of bytes written on success; 0 on failure.

options LrcWriteOptions

Write options.

Returns

bool

false when destination is too small; true on success.

Exceptions

ArgumentNullException

document is null.

TryWrite(LrcDocument, Span<char>, out int, LrcWriteOptions?)

Try-render into a fixed char buffer.

public static bool TryWrite(LrcDocument document, Span<char> destination, out int charsWritten, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

destination Span<char>

Destination span.

charsWritten int

Number of chars written on success; 0 on failure.

options LrcWriteOptions

Write options.

Returns

bool

false when destination is too small; true on success.

Remarks

The implementation renders to a staging buffer first to know the exact size, then copies into destination. For zero-allocation rendering use the IBufferWriter<T> overload instead.

Exceptions

ArgumentNullException

document is null.

ValidateForWrite(LrcDocument, LrcWriteOptions?)

Pre-flight diagnostics (LRC0090 unrepresentable voice transitions). Pure — no rendering.

[Pure]
public static ImmutableArray<LrcDiagnostic> ValidateForWrite(LrcDocument document, LrcWriteOptions? options = null)

Parameters

document LrcDocument

options LrcWriteOptions

Returns

ImmutableArray<LrcDiagnostic>

Write(LrcDocument, LrcWriteOptions?)

Render to a string. Internally renders into an ArrayBufferWriter<T> of chars then materializes the final string. The buffer is pre-sized via EstimateSize(LrcDocument, LrcWriteOptions?) so large documents don't accumulate copy-on-grow waste.

public static string Write(LrcDocument document, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

options LrcWriteOptions

Write options. Defaults to Default.

Returns

string

The fully-rendered LRC text.

Exceptions

ArgumentNullException

document is null.

Write(LrcDocument, IBufferWriter<byte>, LrcWriteOptions?)

Render directly into an IBufferWriter<T> of encoded bytes. The UTF-8 path has zero allocations beyond consumer buffer growth.

public static void Write(LrcDocument document, IBufferWriter<byte> writer, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

writer IBufferWriter<byte>

Destination buffer writer.

options LrcWriteOptions

Write options.

Exceptions

ArgumentNullException

document or writer is null.

Write(LrcDocument, IBufferWriter<char>, LrcWriteOptions?)

Render directly into an IBufferWriter<T> of chars. Zero allocations beyond consumer buffer growth.

public static void Write(LrcDocument document, IBufferWriter<char> writer, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

writer IBufferWriter<char>

Destination buffer writer.

options LrcWriteOptions

Write options.

Examples

var bw = new System.Buffers.ArrayBufferWriter<char>();
LrcWriter.Write(doc, bw);
var span = bw.WrittenSpan;

Exceptions

ArgumentNullException

document or writer is null.

Write(LrcDocument, Stream, LrcWriteOptions?)

Render to a Stream using Encoding (default UTF-8 with no BOM). When the encoding is UTF-8, the writer takes a fast path that renders directly into bytes — no intermediate string copy.

public static void Write(LrcDocument document, Stream stream, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

stream Stream

Destination stream; must be writable.

options LrcWriteOptions

Write options.

Exceptions

ArgumentNullException

document or stream is null.

ArgumentException

stream is not writable.

Write(LrcDocument, TextWriter, LrcWriteOptions?)

Render to a TextWriter via a single span write — no intermediate string allocation.

public static void Write(LrcDocument document, TextWriter writer, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

writer TextWriter

Destination writer.

options LrcWriteOptions

Write options.

Exceptions

ArgumentNullException

document or writer is null.

WriteAsync(LrcDocument, Stream, LrcWriteOptions?, CancellationToken)

Async render to a Stream. When the encoding is UTF-8, the writer takes a fast path that renders directly into bytes — no intermediate string copy.

public static ValueTask WriteAsync(LrcDocument document, Stream stream, LrcWriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

document LrcDocument

The document to render.

stream Stream

Destination stream; must be writable.

options LrcWriteOptions

Write options.

cancellationToken CancellationToken

Honored before render and during async write.

Returns

ValueTask

Examples

using var fs = File.Create("out.lrc");
await LrcWriter.WriteAsync(doc, fs, cancellationToken: ct);

Exceptions

ArgumentNullException

document or stream is null.

ArgumentException

stream is not writable.

OperationCanceledException

Cancellation was requested.

WriteAsync(LrcDocument, TextWriter, LrcWriteOptions?, CancellationToken)

Async render to a TextWriter.

public static ValueTask WriteAsync(LrcDocument document, TextWriter writer, LrcWriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

document LrcDocument

The document to render.

writer TextWriter

Destination writer.

options LrcWriteOptions

Write options.

cancellationToken CancellationToken

Honored before the synchronous render and during the asynchronous flush.

Returns

ValueTask

Exceptions

ArgumentNullException

document or writer is null.

OperationCanceledException

Cancellation was requested.

WriteFile(LrcDocument, string, LrcWriteOptions?)

Atomic file write: writes to a temp file in the destination directory then moves it into place with overwrite. Uses None on the temp file. The temp file is cleaned up only on failure.

public static void WriteFile(LrcDocument document, string path, LrcWriteOptions? options = null)

Parameters

document LrcDocument

The document to render.

path string

Destination file path. Must be non-empty.

options LrcWriteOptions

Write options.

Examples

LrcWriter.WriteFile(doc, "song.lrc");
// On success: "song.lrc" exists, no temp file remains.
// On failure: any temp file in the destination dir is best-effort cleaned up.

Exceptions

ArgumentNullException

document is null.

ArgumentException

path is null, empty, or whitespace.

IOException

A filesystem error occurred. The temp file is cleaned up best-effort.

UnauthorizedAccessException

The destination cannot be written.

WriteFileAsync(LrcDocument, string, LrcWriteOptions?, CancellationToken)

Async atomic file write: writes to a temp file in the destination directory and then moves it into place with overwrite. The temp file is cleaned up only on failure.

public static ValueTask WriteFileAsync(LrcDocument document, string path, LrcWriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

document LrcDocument

The document to render.

path string

Destination file path. Must be non-empty.

options LrcWriteOptions

Write options.

cancellationToken CancellationToken

Honored before opening and during writes.

Returns

ValueTask

Exceptions

ArgumentNullException

document is null.

ArgumentException

path is null, empty, or whitespace.

IOException

A filesystem error occurred. The temp file is cleaned up best-effort.

UnauthorizedAccessException

The destination cannot be written.

OperationCanceledException

Cancellation was requested.