/* -----------------------------------------------------------------------------
Copyright 2021-2022 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]

// Creates Order<Int> counters, for use with traverse.
concrete Counter {
  // Create a sequence of indices for a Container of the given size.
  @type zeroIndexed (Int) -> (optional Order<Int>)
  // Create a reversed sequence of indices for a Container of the given size.
  @type revZeroIndexed (Int) -> (optional Order<Int>)
  // Create an unbounded Int sequence.
  @type unlimited () -> (optional Order<Int>)
  // Create a counter using a builder.
  @type builder () -> (CounterBuilder)
}

// Creates an Order<#x> that repeats a single value, for use with traverse.
concrete Repeat<#x> {
  // Repeat the value the specified number of times.
  @category times<#y>     (#y, Int) -> (optional Order<#y>)
  // Repeat the value an unlimited number of times.
  @category unlimited<#y> (#y)     -> (optional Order<#y>)
}

// Determines min and max of two values.
concrete Ranges {
  // Get the lower value. (Defaults to the first value.)
  @category min<#x>
    #x defines LessThan<#x>
  (#x, #x) -> (#x)

  // Get the higher value. (Defaults to the second value.)
  @category max<#x>
    #x defines LessThan<#x>
  (#x, #x) -> (#x)

  // Determine the lower and higher values. (Defaults to the same order.)
  @category minMax<#x>
    #x defines LessThan<#x>
  (#x, #x) -> (#x, #x)
}

// Builds a sequence of values.
//
// Many of the functions here overlap; therefore, you should never need all of
// them for a single counter.
//
// Example combinations:
//
// - start+count: Set the first value and the number of items, using the default
//   increment between items.
// - count+reverse: Use the default start and default increment, but reverse the
//   order that the items are returned in.
// - start+increment+limit: Count by the specified increment starting with the
//   specified starting point until the specified limit.
concrete CounterBuilder {
  @type new () -> (#self)

  // Finalize the counter.
  @value done () -> (optional Order<Int>)

  // Set the first value in the counter.
  @value start (Int) -> (#self)

  // Set the number of items returned.
  //
  // Notes:
  // - This overrides limit.
  @value count (Int) -> (#self)

  // Set a strict threshold that will not be met or exceeded.
  //
  // Notes:
  // - If increment < 0 then all items will be > limit.
  // - If increment > 0 then all items will be < limit.
  // - This overrides count.
  @value limit (Int) -> (#self)

  // Set the difference between consecutive items.
  @value increment (Int) -> (#self)

  // Reverse the order that the items are returned in.
  //
  // Notes:
  // - This has no effect if the count is unlimited, since the last item does
  //   not exist.
  // - This has the same effect regardless of when it gets called.
  // - Calling this twice reverts the counter to forward again.
  @value reverse () -> (#self)
}