/// Validation
/// ==========
/// Each argument to Su has a single canonical syntax.
/// These validation functions check to ensure
/// that each argument is valid,
/// in order to provide useful errors
/// before attempting to calculate the results/
///
/// @group x-validation
///
/// @see su-valid-columns
/// @see su-valid-gutters
/// @see su-valid-spread
/// @see su-valid-location



// Valid Span
// ----------
/// Check that the `span` argument
/// is a number, length, or column-list
///
/// @group x-validation
///
/// @param {number | list} $span -
///   Number of columns, or length of span
///
/// @return {number | list} -
///   Validated `$span` number, length, or columns list
///
/// @throw
///   when span value is not a number, or valid column list
@function su-valid-span(
  $span
) {
  $type: type-of($span);
  @if ($type == 'number') {
    @return $span;
  } @else if ($type == 'list') and su-valid-columns($span, 'silent-failure') {
    @return $span;
  }

  $actual: '[#{type-of($span)}] `#{inspect($span)}`';
  @return _susy-error(
    '#{$actual} is not a valid number, length, or column-list for $span.',
    'su-valid-span');
}



// Valid Columns
// -------------
/// Check that the `columns` argument is a valid
/// list of column-lengths
///
/// @group x-validation
///
/// @param {list} $columns -
///   List of column-lengths
/// @param {bool} $silent-failure [true] -
///   Set false to return null on failure
///
/// @return {list} -
///   Validated `$columns` list
///
/// @throw
///   when column value is not a valid list of numbers
@function su-valid-columns(
  $columns,
  $silent-failure: false
) {
  @if (type-of($columns) == 'list') {
    $fail: false;

    @each $col in $columns {
      @if (type-of($col) != 'number') {
        $fail: true;
      }
    }

    @if not $fail {
      @return $columns;
    }
  }

  // Silent Failure
  @if $silent-failure {
    @return null;
  }

  // Error Message
  $actual: '[#{type-of($columns)}] `#{inspect($columns)}`';

  @return _susy-error(
    '#{$actual} is not a valid list of numbers for $columns.',
    'su-valid-columns');
}



// Valid Gutters
// -------------
/// Check that the `gutters` argument is a valid number
///
/// @group x-validation
///
/// @param {number} $gutters -
///   Width of a gutter
///
/// @return {number} -
///   Validated `$gutters` number
///
/// @throw
///   when gutter value is not a number
@function su-valid-gutters(
  $gutters
) {
  $type: type-of($gutters);

  @if ($type == 'number') {
    @return $gutters;
  }

  $actual: '[#{$type}] `#{inspect($gutters)}`';
  @return _susy-error(
    '#{$actual} is not a number or length for $gutters.',
    'su-valid-gutters');
}



// Valid Spread
// ------------
/// Check that the `spread` argument is a valid
/// intiger between `-1` and `1`
///
/// @group x-validation
///
/// @param {0 | 1 | -1} $spread -
///   Number of gutters to include in a span,
///   relative to the number columns
///
/// @return {0 | 1 | -1} -
///   Validated `$spread` number
///
/// @throw
///   when spread value is not a valid spread
@function su-valid-spread(
  $spread
) {
  @if index(0 1 -1, $spread) {
    @return $spread;
  }

  $actual: '[#{type-of($spread)}] `#{inspect($spread)}`';
  @return _susy-error(
    '#{$actual} is not a normalized [0 | 1 | -1] value for `$spread`.',
    'su-valid-spread');
}



// Valid Location
// --------------
/// Check that the `location` argument is a valid number,
/// within the scope of available columns
///
/// @group x-validation
///
/// @param {number} $span -
///   Number of grid-columns to be spanned
/// @param {integer | string} $location -
///   Starting (1-indexed) column-position of that span
/// @param {list} $columns -
///   List of available columns in the grid
///
/// @return {integer} -
///   Validated `$location` intiger
///
/// @throw
///   when location value is not a valid index,
///   given the context and span.
@function su-valid-location(
  $span,
  $location,
  $columns
) {
  $count: length($columns);

  @if $location {
    @if (type-of($location) != 'number') or (not unitless($location)) {
      $actual: '[#{type-of($location)}] `#{$location}`';
      @return _susy-error(
        '#{$actual} is not a unitless number for $location.',
        'su-valid-location');
    } @else if (round($location) != $location) {
      @return _susy-error(
        'Location (`#{$location}`) must be a 1-indexed intiger position.',
        'su-valid-location');
    } @else if ($location > $count) or ($location < 1) {
      @return _susy-error(
        'Position `#{$location}` does not exist in grid `#{$columns}`.',
        'su-valid-location');
    } @else if ($location + $span - 1 > $count) {
      $details: 'grid `#{$columns}` for span `#{$span}` at `#{$location}`';
      @return _susy-error(
        'There are not enough columns in #{$details}.',
        'su-valid-location');
    }
  }

  @return $location;
}