gui-cs.Terminal.Gui/Terminal.Gui/Text/RuneExtensions.cs

using System.Globalization;
using System.Text;
using Wcwidth;

namespace Terminal.Gui;

/// <summary>
/// Extends <see cref="System.Text.Rune"/> to support TUI text manipulation.
/// </summary>
public static class RuneExtensions {
	/// <summary>
	/// Maximum Unicode code point.
	/// </summary>
	public static int MaxUnicodeCodePoint = 0x10FFFF;

	/// <summary>
	/// Gets the number of columns the rune occupies in the terminal.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune">The rune to measure.</param>
	/// <returns>
	/// The number of columns required to fit the rune, 0 if the argument is the null character, or
	/// -1 if the value is not printable, 
	/// otherwise the number of columns that the rune occupies.
	/// </returns>
	public static int GetColumns (this Rune rune)
	{
		return UnicodeCalculator.GetWidth (rune);
	}

	/// <summary>
	/// Returns <see langword="true"/> if the rune is a combining character.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune"></param>
	/// <returns></returns>
	public static bool IsCombiningMark (this System.Text.Rune rune)
	{
		UnicodeCategory category = Rune.GetUnicodeCategory (rune);
		return Rune.GetUnicodeCategory (rune) == UnicodeCategory.NonSpacingMark
			|| category == UnicodeCategory.SpacingCombiningMark
			|| category == UnicodeCategory.EnclosingMark;
	}

	/// <summary>
	/// Ensures the rune is not a control character and can be displayed by translating characters below 0x20
	/// to equivalent, printable, Unicode chars.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune"></param>
	/// <returns></returns>
	public static Rune MakePrintable (this System.Text.Rune rune) => Rune.IsControl (rune) ? new Rune (rune.Value + 0x2400) : rune;

	/// <summary>
	/// Get number of bytes required to encode the rune, based on the provided encoding.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune">The rune to probe.</param>
	/// <param name="encoding">The encoding used; the default is UTF8.</param>
	/// <returns>The number of bytes required.</returns>
	public static int GetEncodingLength (this Rune rune, Encoding encoding = null)
	{
		encoding ??= Encoding.UTF8;
		var bytes = encoding.GetBytes (rune.ToString ().ToCharArray ());
		var offset = 0;
		if (bytes [^1] == 0) {
			offset++;
		}
		return bytes.Length - offset;
	}

	/// <summary>
	/// Writes into the destination buffer starting at offset the UTF8 encoded version of the rune.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune">The rune to encode.</param>
	/// <param name="dest">The destination buffer.</param>
	/// <param name="start">Starting offset to look into.</param>
	/// <param name="count">Number of bytes valid in the buffer, or -1 to make it the length of the buffer.</param>
	/// <returns>he number of bytes written into the destination buffer.</returns>
	public static int Encode (this Rune rune, byte [] dest, int start = 0, int count = -1)
	{
		var bytes = Encoding.UTF8.GetBytes (rune.ToString ());
		var length = 0;
		for (var i = 0; i < (count == -1 ? bytes.Length : count); i++) {
			if (bytes [i] == 0) {
				break;
			}
			dest [start + i] = bytes [i];
			length++;
		}
		return length;
	}

	/// <summary>
	/// Attempts to decode the rune as a surrogate pair to UTF-16.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune">The rune to decode.</param>
	/// <param name="chars">The chars if the rune is a surrogate pair. Null otherwise.</param>
	/// <returns><see langword="true"/> if the rune is a valid surrogate pair; <see langword="false"/> otherwise.</returns>
	public static bool DecodeSurrogatePair (this Rune rune, out char [] chars)
	{
		if (rune.IsSurrogatePair ()) {
			chars = rune.ToString ().ToCharArray ();
			return true;
		}
		chars = null;
		return false;
	}

	/// <summary>
	/// Attempts to encode (as UTF-16) a surrogate pair.
	/// </summary>
	/// <param name="highSurrogate">The high surrogate code point.</param>
	/// <param name="lowSurrogate">The low surrogate code point.</param>
	/// <param name="result">The encoded rune.</param>
	/// <returns><see langword="true"/> if the encoding succeeded; <see langword="false"/> otherwise.</returns>
	public static bool EncodeSurrogatePair (char highSurrogate, char lowSurrogate, out Rune result)
	{
		result = default;
		if (char.IsSurrogatePair (highSurrogate, lowSurrogate)) {
			result = (Rune)char.ConvertToUtf32 (highSurrogate, lowSurrogate);
			return true;
		}
		return false;
	}

	/// <summary>
	/// Reports whether a rune is a surrogate code point.
	/// </summary>
	/// <remarks>
	/// This is a Terminal.Gui extension method to <see cref="System.Text.Rune"/> to support TUI text manipulation.
	/// </remarks>
	/// <param name="rune">The rune to probe.</param>
	/// <returns><see langword="true"/> if the rune is a surrogate code point; <see langword="false"/> otherwise.</returns>
	public static bool IsSurrogatePair (this Rune rune)
	{
		return char.IsSurrogatePair (rune.ToString (), 0);
	}

	/// <summary>
	/// Reports if the provided array of bytes can be encoded as UTF-8.
	/// </summary>
	/// <param name="buffer">The byte array to probe.</param>
	/// <value><c>true</c> if is valid; otherwise, <c>false</c>.</value>
	public static bool CanBeEncodedAsRune (byte [] buffer)
	{
		var str = Encoding.Unicode.GetString (buffer);
		foreach (var rune in str.EnumerateRunes ()) {
			if (rune == Rune.ReplacementChar) {
				return false;
			}
		}
		return true;
	}
}