Optional Utilities

[Panthr75]

Motivation

Working with Optional inside the library is already a pain with IsSpecified checks, and passing in "null" values into Optional's underlying value.

Optional.CreateFromNullable<T>

Creates an optional from the specified nullable value, where it returns Optional<T>.Unspecified if the value is null.

public static Optional<T> CreateFromNullable<T>(T? value)
    where T : struct
{
    return value.HasValue ? value.Value : Optional<T>.Unspecified;
}
public static Optional<T> CreateFromNullable<T>(T value)
{
    return value is null ? Optional<T>.Unspecified : value;
}

Optional.NotEmpty

Makes sure the optional's underlying collection isn't empty. If so, returns Unspecified.

public static Optional<TCollection> NotEmpty<TCollection>(this Optional<TCollection> val)
    where TCollection : IEnumerable
{
    TCollection value = val.GetValueOrDefault();
    if (value is not null)
    {
        // adopted from Linq Enumerable<T>.Any,
        // but for non-generic enumerable
        IEnumerator enumerator = value.GetEnumerator();
        bool hasValue = enumerator.MoveNext();
        if (enumerator is IDisposable disposable)
        {
            disposable.Dispose();
        }

        if (hasValue)
        {
            return val;
        }
    }
    return Optional<TCollection>.Unspecified;
}

public static Optional<TCollection> NotEmpty<TCollection, T>(this Optional<TCollection> val)
    where TCollection : IEnumerable<T>
{
    return (val.GetValueOrDefault()?.Any() ?? false) ? val : Optional<TCollection>.Unspecified;
}

Optional<T>.Map<U>

A utility method to map the value in the Optional to another. This removes a lot of IsSpecified checks inside API code.

public Optional<U> Map<U>(Func<T, U> mapper)
{
    return IsSpecified ? mapper(this.Value) : Optional<U>.Unspecified;
}
public Optional<U> Map<U>(Func<T, Optional<U>> mapper)
{
    return IsSpecified ? mapper(this.Value) : Optional<U>.Unspecified;
}

Take for example #2724, where there was an extra check due to IsSpecified

// ChannelHelper.cs
public static async Task<Model> ModifyAsync(IGuildChannel channel, BaseDiscordClient client,
    Action<GuildChannelProperties> func,
    RequestOptions options)
{
    var args = new GuildChannelProperties();
    func(args);
    var apiArgs = new API.Rest.ModifyGuildChannelParams
    {
        Name = args.Name,
        Position = args.Position,
        CategoryId = args.CategoryId,
        Overwrites = args.PermissionOverwrites.IsSpecified
            ? args.PermissionOverwrites.Value.Select(overwrite => new API.Overwrite
            {
                TargetId = overwrite.TargetId,
                TargetType = overwrite.TargetType,
                Allow = overwrite.Permissions.AllowValue.ToString(),
                Deny = overwrite.Permissions.DenyValue.ToString()
            }).ToArray()
            : Optional.Create<API.Overwrite[]>(),
        Flags = args.Flags.GetValueOrDefault(),
        IconEmoji = args.IconEmoji.IsSpecified
            ? args.IconEmoji.Value is Emote emote
                ? new API.Emoji { Id = emote.Id, Name = emote.Name }
                : args.IconEmoji.GetValueOrDefault(null) is Emoji emoji /*GetValueOrDefault not required*/
                    ? new API.Emoji { Name = emoji.Name }
                    : null
            : Optional<API.Emoji>.Unspecified,
    };
    return await client.ApiClient.ModifyGuildChannelAsync(channel.Id, apiArgs, options).ConfigureAwait(false);
} 

When using Optional<T>.Map, this code gets much easier to read:

// ChannelHelper.cs
public static async Task<Model> ModifyAsync(IGuildChannel channel, BaseDiscordClient client,
    Action<GuildChannelProperties> func,
    RequestOptions options)
{
    var args = new GuildChannelProperties();
    func(args);
    var apiArgs = new API.Rest.ModifyGuildChannelParams
    {
        Name = args.Name,
        Position = args.Position,
        CategoryId = args.CategoryId,
        Overwrites = args.PermissionOverwrites.Map(v => v.Select(overwrite => new API.Overwrite
        {
            TargetId = overwrite.TargetId,
            TargetType = overwrite.TargetType,
            Allow = overwrite.Permissions.AllowValue.ToString(),
            Deny = overwrite.Permissions.DenyValue.ToString()
        }).ToArray()),
        Flags = args.Flags.GetValueOrDefault(),
        IconEmoji = args.IconEmoji.Map(v => v is Emote emote ?
            new API.Emoji { Id = emote.Id, Name = emote.Name } :
                v is Emoji emoji ? 
                    new API.Emoji { Name = emoji.Name } :
                    Optional<API.Emoji>.Unspecified
        )
    };
    return await client.ApiClient.ModifyGuildChannelAsync(channel.Id, apiArgs, options).ConfigureAwait(false);
} 

Just these three methods alone can help clean up a lot of the code base as is:

// ChannelHelper.SendMessageAsync - old
var args = new CreateMessageParams
{
    Content = text,
    IsTTS = isTTS,
    Embeds = embeds.Any() ? embeds.Select(x => x.ToModel()).ToArray() : Optional<API.Embed[]>.Unspecified,
    AllowedMentions = allowedMentions?.ToModel(),
    MessageReference = messageReference?.ToModel(),
    Components = components?.Components.Select(x => new API.ActionRowComponent(x)).ToArray() ?? Optional<API.ActionRowComponent[]>.Unspecified,
    Stickers = stickers?.Any() ?? false ? stickers.Select(x => x.Id).ToArray() : Optional<ulong[]>.Unspecified,
    Flags = flags
}

// ChannelHelper.SendMessageAsync - new
var args = new CreateMessageParams
{
    Content = Optional.CreateFromNullable(text),
    IsTTS = isTTS,
    Embeds = Optional.Create(embeds)
        .NotEmpty()
        .Map(e => e.Select(x => x.ToModel()).ToArray()),
    AllowedMentions = Optional.CreateFromNullable(allowedMentions?.ToModel()),
    MessageReference = Optional.CreateFromNullable(messageReference?.ToModel()),
    Components = Optional.CreateFromNullable(components)
        .Map(c => c.Components
            .Select(x => new API.ActionRowComponent(x))
            .ToArray()),
    Stickers = Optional.CreateFromNullable(stickers)
        .NotEmpty()
        .Map(s => s.Select(x => x.Id).ToArray()),
    Flags = flags
};