Class LrcWriter

Namespace

ModernLrc

Assembly

ModernLrc.dll

Entry-point for writing an LrcDocument. All overloads converge on a single char renderer; byte sinks encode its output with Encoding.

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).

Methods

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.

Exceptions

ArgumentNullException

document is null.

ValidateForWrite(LrcDocument, LrcWriteOptions?)

Pre-flight diagnostics (LRC0090 unrepresentable voice transitions). No rendering.

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.

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 into an IBufferWriter<T> of bytes encoded with Encoding.

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.

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, no BOM unless EmitByteOrderMark is set).

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 using Encoding.

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 write.

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. 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.