/* -----------------------------------------------------------------------------
Copyright 2021,2024 Kevin P. Barry

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
----------------------------------------------------------------------------- */

// Author: Kevin P. Barry [ta0kira@gmail.com]

// Helpers to extend functionality to the Order<#x> built-in.
concrete OrderH {
  // Extend lessThan, based on position-wise comparisons.
  //
  // Notes:
  // - If one sequence is a strict prefix of the other, that sequence will
  //   evaluate as less-than the other.
  //
  // Example:
  //
  //   Bool lt <- x.defaultOrder() `OrderH:lessThan` y.defaultOrder()
  @category lessThan<#x>
    #x defines LessThan<#x>
  (optional Order<#x>, optional Order<#x>) -> (Bool)

  // The same as lessThan, but with a custom comparator.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #xx: Comparator type providing the LessThan<#x> comparison.
  //
  // Example:
  //
  //   Bool lt <- x.defaultOrder() `OrderH:lessThanWith<?, Reversed<Int>>` y.defaultOrder()
  @category lessThanWith<#x, #xx>
    #xx defines LessThan<#x>
  (optional Order<#x>, optional Order<#x>) -> (Bool)

  // Extend equals, based on position-wise comparisons.
  //
  // Example:
  //
  //   Bool eq <- x.defaultOrder() `OrderH:equals` y.defaultOrder()
  @category equals<#x>
    #x defines Equals<#x>
  (optional Order<#x>, optional Order<#x>) -> (Bool)

  // The same as equals, but with a custom comparator.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #xx: Comparator type providing the Equals<#x> comparison.
  //
  // Example:
  //
  //   Bool eq <- x.defaultOrder() `OrderH:equalsWith<?, BySize>` y.defaultOrder()
  @category equalsWith<#x, #xx>
    #xx defines Equals<#x>
  (optional Order<#x>, optional Order<#x>) -> (Bool)

  // Copies references to all elements to the destination.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #c: Container type.
  //
  // Args:
  // - optional Order<#x>: Element source.
  // - #c: Output container.
  //
  // Returns:
  // - #c: The container originally passed.
  @category copyTo<#x, #c>
    #c requires Append<#x>
  (optional Order<#x>, #c) -> (#c)

  // Duplicates all elements to the destination.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #c: Container type.
  //
  // Args:
  // - optional Order<#x>: Element source.
  // - #c: Output container.
  //
  // Returns:
  // - #c: The container originally passed.
  @category duplicateTo<#x, #c>
    #x requires Duplicate
    #c requires Append<#x>
  (optional Order<#x>, #c) -> (#c)
}

// Helpers to extend functionality to the ReadAt<#x> built-in.
concrete ReadAtH {
  // Extend lessThan, based on position-wise comparisons.
  //
  // Notes:
  // - If one sequence is a strict prefix of the other, that sequence will
  //   evaluate as less-than the other.
  //
  // Example:
  //
  //   Bool lt <- x `ReadAtH:lessThan` y
  @category lessThan<#x>
    #x defines LessThan<#x>
  (ReadAt<#x>, ReadAt<#x>) -> (Bool)

  // The same as lessThan, but with a custom comparator.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #xx: Comparator type providing the LessThan<#x> comparison.
  //
  // Example:
  //
  //   Bool lt <- x `ReadAtH:lessThanWith<?, Reversed<Int>>` y
  @category lessThanWith<#x, #xx>
    #xx defines LessThan<#x>
  (ReadAt<#x>, ReadAt<#x>) -> (Bool)

  // Extend equals, based on position-wise comparisons.
  //
  // Example:
  //
  //   Bool eq <- x `ReadAtH:equals` y
  @category equals<#x>
    #x defines Equals<#x>
  (ReadAt<#x>, ReadAt<#x>) -> (Bool)

  // The same as equals, but with a custom comparator.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #xx: Comparator type providing the Equals<#x> comparison.
  //
  // Example:
  //
  //   Bool eq <- x `ReadAtH:equalsWith<?, BySize>` y
  @category equalsWith<#x, #xx>
    #xx defines Equals<#x>
  (ReadAt<#x>, ReadAt<#x>) -> (Bool)

  // Copies references to all elements to the destination.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #c: Container type.
  //
  // Args:
  // - ReadAt<#x>: Element source.
  // - #c: Output container.
  //
  // Returns:
  // - #c: The container originally passed.
  @category copyTo<#x, #c>
    #c requires Append<#x>
  (ReadAt<#x>, #c) -> (#c)

  // Duplicates all elements to the destination.
  //
  // Params:
  // - #x: Element type managed by the container.
  // - #c: Container type.
  //
  // Args:
  // - ReadAt<#x>: Element source.
  // - #c: Output container.
  //
  // Returns:
  // - #c: The container originally passed.
  @category duplicateTo<#x, #c>
    #x requires Duplicate
    #c requires Append<#x>
  (ReadAt<#x>, #c) -> (#c)

  // Iterates over the container from 0 to the end.
  @category forwardOrder<#x> (ReadAt<#x>) -> (optional Order<#x>)

  // Iterates over the container from the end to 0.
  @category reverseOrder<#x> (ReadAt<#x>) -> (optional Order<#x>)

  // Iterates over the container using the provided index order.
  @category iterateWith<#x> (ReadAt<#x>, optional Order<Int>) -> (optional Order<#x>)
}

// Helpers to extend functionality to the Formatted built-in.
concrete FormattedH {
  // Attempts to convert the value to Formatted.
  //
  // Notes:
  // - This is primarily meant for debugging and logging. Program logic should
  //   not rely on the returned values.
  // - If the value is not Formatted, a fabricated Formatted will be returned.
  //
  // Example:
  //
  //   fail(FormattedH:try(badValue))
  @category try<#x> (optional #x) -> (Formatted)
}

// Reverse an existing LessThan<#x> comparison.
concrete Reversed<#x|> {
  defines LessThan<#x>
  #x defines LessThan<#x>
}

// Base ordering on container size alone.
concrete BySize {
  defines Equals<Container>
  defines LessThan<Container>
}

// Always evaluate objects as equal.
//
// Notes:
// - This will allow comparing any two objects with each other (e.g., Int and
//   ErrorOr<String>), regardless of if they are of compatible types.
concrete AlwaysEqual {
  defines Equals<any>
  defines LessThan<any>
}

// Creates a LessThan2 from a LessThan.
//
// Params:
// - #x: Object type to be compared.
// - #xx: Comparator for #x.
concrete AsLessThan2<#x|#xx|> {
  #xx defines LessThan<#x>

  @type new () -> (LessThan2<#x>)
}

// Helpers for Append<#x>.
concrete AppendH {
  // Appends all items in order.
  @category from<#x, #a>
    #a requires Append<#x>
  (#a, optional Order<#x>) -> (#a)
}