function _CourseList::find_best_grade_match

5.x _CourseList.php _CourseList::find_best_grade_match(Course $course_c, $min_grade = "", $bool_mark_repeats_exclude = false, $degree_id = 0, $bool_skip_already_assigned_to_degree = TRUE, $bool_skip_subs = FALSE, $group_id = 0)

Find a list of matches to Course courseC, which fulfill the min_grade requirement, ordered by most best grade first.

Returns FALSE if no matches were found, else it will return the matched Course object.

Return value

Course

1 call to _CourseList::find_best_grade_match()
_CourseList::find_best_match in classes/_CourseList.php
Find the "best" match for this course, based on what the university considers a best match. This largely has to do with repeats. If the student has more than one credit, what is the "best" match?

File

classes/_CourseList.php, line 449

Class

_CourseList

Code

function find_best_grade_match(Course $course_c, $min_grade = "", $bool_mark_repeats_exclude = false, $degree_id = 0, $bool_skip_already_assigned_to_degree = TRUE, $bool_skip_subs = FALSE, $group_id = 0) 
 {


  $list_matches = parent::find_all_matches($course_c);
  if (!$list_matches) {
    return false;
  }

  $list_matches = CourseList::cast($list_matches);

  //sort the courses into largest hours first, so equal grades will be sorted by hours
  $list_matches->sort_largest_hours_first();

  // Sort the courses into best grade first.
  $list_matches->sort_best_grade_first();


  if (!$list_matches || $list_matches->is_empty) 
   {
    return false;
  }

  // If we are here, then we have more than one match.
  // Meaning, we have more than one class which might fit
  // into this course requirement.


  $withdrew_grades = csv_to_array(variable_get("withdrew_grades", "W"));


  // So, now that it's sorted, we should look through the list,
  // checking the min grade requirements (if any).  When we find
  // a good one, we will select it.

  $list_matches->reset_counter();
  while ($list_matches->has_more()) 
   {
    $c = $list_matches->get_next();

    if ($c->get_bool_exclude_repeat($degree_id) == TRUE) 
     {
      continue;
    }


    // Has the course already been assigned [to this degree]?
    if ($bool_skip_already_assigned_to_degree && $c->get_has_been_assigned_to_degree_id($degree_id)) {
      // Yes, it's been assigned, so we can just skip it.
      continue;
    }

    if ($bool_skip_subs && $c->get_bool_substitution($degree_id) == TRUE) {
      // It is already being used in a substitution for this degree id, so we skip it.
      continue;
    }

    //////////////////////////////////////////
    ///  Check for min grade, etc, here.      
    if (!$c->meets_min_grade_requirement_of(null, $min_grade)) 
     {

      if ($bool_mark_repeats_exclude == true) 
       {
        // Since this course does not meet the min_grade,
        // check to see if it may be repeated.  If it can't,
        // then we must mark ALL previous attempts at this
        // course as being excluded from further consideration.
        // (ULM policy on repeats).
        // We don't do this consideration if they simply
        // withdrew from a course...
        if (in_array($c->grade, $withdrew_grades)) {
          continue;
        }

        if ($c->min_hours < 1 || $c->min_hours == "") {
          $c->load_descriptive_data(); // make sure we get hour data for this course.
        }

        if ($c->repeat_hours <= $c->min_hours) 
         {
          // No repeats.
          $this->mark_repeats_exclude($c, $degree_id);

          return false;

        }
        else {
          // Repeats allowed, so just continue.
          continue;
        }

      } // if bool_mark_repeats_exclude == true 
      else {
        // We did NOT meet the min_grade requirement!
        $c = FALSE;
        continue;
      }
    } // course did NOT meet the min_grade requirement
    else {
      // The course DID meet the min grade requirement.

      // Are we supposed to exclude repeats?
      if ($bool_mark_repeats_exclude) {
        // Make sure the course isn't allowed to be repeated...
        if ($c->repeat_hours <= $c->min_hours) {
          // No repeats allowed.
          $this->mark_repeats_exclude($c, $degree_id, $c);
        }
      }

    }


    // At this point, we are going to invoke a hook, to give add-on modules
    // one last chance to "skip" the course or not.
    $bool_can_proceed = TRUE;
    $result = invoke_hook("courselist_find_match_allow_course", array($c, $course_c, $list_matches, $degree_id, $group_id));
    foreach ($result as $m => $val) {
      // If *any* module said FALSE, then we must skip this course and not assign it to this degree.
      if ($val === FALSE) {
        $bool_can_proceed = $val;
      }
    }

    if (!$bool_can_proceed) {
      continue;
    }

    return $c;
  } // while

  return FALSE;

}