Revert "MDL-33105 flexible apply_units() function"
[moodle.git] / question / type / numerical / question.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Numerical question definition class.
19  *
20  * @package    qtype
21  * @subpackage numerical
22  * @copyright  2009 The Open University
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Represents a numerical question.
31  *
32  * @copyright  2009 The Open University
33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 class qtype_numerical_question extends question_graded_automatically {
36     /** @var array of question_answer. */
37     public $answers = array();
39     /** @var int one of the constants UNITNONE, UNITRADIO, UNITSELECT or UNITINPUT. */
40     public $unitdisplay;
41     /** @var int one of the constants UNITGRADEDOUTOFMARK or UNITGRADEDOUTOFMAX. */
42     public $unitgradingtype;
43     /** @var number the penalty for a missing or unrecognised unit. */
44     public $unitpenalty;
46     /** @var qtype_numerical_answer_processor */
47     public $ap;
49     public function get_expected_data() {
50         $expected = array('answer' => PARAM_RAW_TRIMMED);
51         if ($this->has_separate_unit_field()) {
52             $expected['unit'] = PARAM_RAW_TRIMMED;
53         }
54         return $expected;
55     }
57     public function has_separate_unit_field() {
58         return $this->unitdisplay == qtype_numerical::UNITRADIO ||
59                 $this->unitdisplay == qtype_numerical::UNITSELECT;
60     }
62     public function start_attempt(question_attempt_step $step, $variant) {
63         $step->set_qt_var('_separators',
64                 $this->ap->get_point() . '$' . $this->ap->get_separator());
65     }
67     public function apply_attempt_state(question_attempt_step $step) {
68         list($point, $separator) = explode('$', $step->get_qt_var('_separators'));
69                 $this->ap->set_characters($point, $separator);
70     }
72     public function summarise_response(array $response) {
73         if (isset($response['answer'])) {
74             $resp = $response['answer'];
75         } else {
76             $resp = null;
77         }
79         if ($this->has_separate_unit_field() && !empty($response['unit'])) {
80             $resp = $this->ap->add_unit($resp, $response['unit']);
81         }
83         return $resp;
84     }
86     public function is_gradable_response(array $response) {
87         return array_key_exists('answer', $response) &&
88                 ($response['answer'] || $response['answer'] === '0' || $response['answer'] === 0);
89     }
91     public function is_complete_response(array $response) {
92         if (!$this->is_gradable_response($response)) {
93             return false;
94         }
96         list($value, $unit) = $this->ap->apply_units($response['answer']);
97         if (is_null($value)) {
98             return false;
99         }
101         if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
102             return false;
103         }
105         if ($this->has_separate_unit_field() && empty($response['unit'])) {
106             return false;
107         }
109         if ($this->ap->contains_thousands_seaparator($response['answer'])) {
110             return false;
111         }
113         return true;
114     }
116     public function get_validation_error(array $response) {
117         if (!$this->is_gradable_response($response)) {
118             return get_string('pleaseenterananswer', 'qtype_numerical');
119         }
121         list($value, $unit) = $this->ap->apply_units($response['answer']);
122         if (is_null($value)) {
123             return get_string('invalidnumber', 'qtype_numerical');
124         }
126         if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
127             return get_string('invalidnumbernounit', 'qtype_numerical');
128         }
130         if ($this->has_separate_unit_field() && empty($response['unit'])) {
131             return get_string('unitnotselected', 'qtype_numerical');
132         }
134         if ($this->ap->contains_thousands_seaparator($response['answer'])) {
135             return get_string('pleaseenteranswerwithoutthousandssep', 'qtype_numerical',
136                     $this->ap->get_separator());
137         }
139         return '';
140     }
142     public function is_same_response(array $prevresponse, array $newresponse) {
143         if (!question_utils::arrays_same_at_key_missing_is_blank(
144                 $prevresponse, $newresponse, 'answer')) {
145             return false;
146         }
148         if ($this->has_separate_unit_field()) {
149             return question_utils::arrays_same_at_key_missing_is_blank(
150                 $prevresponse, $newresponse, 'unit');
151         }
153         return true;
154     }
156     public function get_correct_response() {
157         $answer = $this->get_correct_answer();
158         if (!$answer) {
159             return array();
160         }
162         $response = array('answer' => str_replace('.', $this->ap->get_point(), $answer->answer));
164         if ($this->has_separate_unit_field()) {
165             $response['unit'] = $this->ap->get_default_unit();
166         } else if ($this->unitdisplay == qtype_numerical::UNITINPUT) {
167             $response['answer'] = $this->ap->add_unit($answer->answer);
168         }
170         return $response;
171     }
173     /**
174      * Get an answer that contains the feedback and fraction that should be
175      * awarded for this resonse.
176      * @param number $value the numerical value of a response.
177      * @param number $multiplier for the unit the student gave, if any. When no
178      *      unit was given, or an unrecognised unit was given, $multiplier will be null.
179      * @return question_answer the matching answer.
180      */
181     public function get_matching_answer($value, $multiplier) {
182         if (is_null($value) || $value === '') {
183             return null;
184         }
186         if (!is_null($multiplier)) {
187             $scaledvalue = $value * $multiplier;
188         } else {
189             $scaledvalue = $value;
190         }
191         foreach ($this->answers as $aid => $answer) {
192             if ($answer->within_tolerance($scaledvalue)) {
193                 $answer->unitisright = !is_null($multiplier);
194                 return $answer;
195             } else if ($answer->within_tolerance($value)) {
196                 $answer->unitisright = false;
197                 return $answer;
198             }
199         }
201         return null;
202     }
204     public function get_correct_answer() {
205         foreach ($this->answers as $answer) {
206             $state = question_state::graded_state_for_fraction($answer->fraction);
207             if ($state == question_state::$gradedright) {
208                 return $answer;
209             }
210         }
211         return null;
212     }
214     /**
215      * Adjust the fraction based on whether the unit was correct.
216      * @param number $fraction
217      * @param bool $unitisright
218      * @return number
219      */
220     public function apply_unit_penalty($fraction, $unitisright) {
221         if ($unitisright) {
222             return $fraction;
223         }
225         if ($this->unitgradingtype == qtype_numerical::UNITGRADEDOUTOFMARK) {
226             $fraction -= $this->unitpenalty * $fraction;
227         } else if ($this->unitgradingtype == qtype_numerical::UNITGRADEDOUTOFMAX) {
228             $fraction -= $this->unitpenalty;
229         }
230         return max($fraction, 0);
231     }
233     public function grade_response(array $response) {
234         if ($this->has_separate_unit_field()) {
235             $selectedunit = $response['unit'];
236         } else {
237             $selectedunit = null;
238         }
239         list($value, $unit, $multiplier) = $this->ap->apply_units(
240                 $response['answer'], $selectedunit);
242         $answer = $this->get_matching_answer($value, $multiplier);
243         if (!$answer) {
244             return array(0, question_state::$gradedwrong);
245         }
247         $fraction = $this->apply_unit_penalty($answer->fraction, $answer->unitisright);
248         return array($fraction, question_state::graded_state_for_fraction($fraction));
249     }
251     public function classify_response(array $response) {
252         if (empty($response['answer'])) {
253             return array($this->id => question_classified_response::no_response());
254         }
256         if ($this->has_separate_unit_field()) {
257             $selectedunit = $response['unit'];
258         } else {
259             $selectedunit = null;
260         }
261         list($value, $unit, $multiplier) = $this->ap->apply_units($response['answer'], $selectedunit);
262         $ans = $this->get_matching_answer($value, $multiplier);
264         $resp = $response['answer'];
265         if ($this->has_separate_unit_field()) {
266             $resp = $this->ap->add_unit($resp, $unit);
267         }
269         if (!$ans) {
270             return array($this->id => new question_classified_response(0, $resp, 0));
271         }
273         return array($this->id => new question_classified_response($ans->id,
274                 $resp,
275                 $this->apply_unit_penalty($ans->fraction, $ans->unitisright)));
276     }
278     public function check_file_access($qa, $options, $component, $filearea, $args,
279             $forcedownload) {
280         if ($component == 'question' && $filearea == 'answerfeedback') {
281             $currentanswer = $qa->get_last_qt_var('answer');
282             if ($this->has_separate_unit_field()) {
283                 $selectedunit = $qa->get_last_qt_var('unit');
284             } else {
285                 $selectedunit = null;
286             }
287             list($value, $unit, $multiplier) = $this->ap->apply_units(
288                     $currentanswer, $selectedunit);
289             $answer = $this->get_matching_answer($value, $multiplier);
290             $answerid = reset($args); // itemid is answer id.
291             return $options->feedback && $answer && $answerid == $answer->id;
293         } else if ($component == 'question' && $filearea == 'hint') {
294             return $this->check_hint_file_access($qa, $options, $args);
296         } else {
297             return parent::check_file_access($qa, $options, $component, $filearea,
298                     $args, $forcedownload);
299         }
300     }
304 /**
305  * Subclass of {@link question_answer} with the extra information required by
306  * the numerical question type.
307  *
308  * @copyright  2009 The Open University
309  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
310  */
311 class qtype_numerical_answer extends question_answer {
312     /** @var float allowable margin of error. */
313     public $tolerance;
314     /** @var integer|string see {@link get_tolerance_interval()} for the meaning of this value. */
315     public $tolerancetype = 2;
317     public function __construct($id, $answer, $fraction, $feedback, $feedbackformat, $tolerance) {
318         parent::__construct($id, $answer, $fraction, $feedback, $feedbackformat);
319         $this->tolerance = abs($tolerance);
320     }
322     public function get_tolerance_interval() {
323         if ($this->answer === '*') {
324             throw new coding_exception('Cannot work out tolerance interval for answer *.');
325         }
327         // Smallest number that, when added to 1, is different from 1.
328         $epsilon = pow(10, -1 * ini_get('precision'));
330         // We need to add a tiny fraction depending on the set precision to make
331         // the comparison work correctly, otherwise seemingly equal values can
332         // yield false. See MDL-3225.
333         $tolerance = abs($this->tolerance) + $epsilon;
335         switch ($this->tolerancetype) {
336             case 1: case 'relative':
337                 $range = abs($this->answer) * $tolerance;
338                 return array($this->answer - $range, $this->answer + $range);
340             case 2: case 'nominal':
341                 $tolerance = $this->tolerance + $epsilon * max(abs($this->tolerance), abs($this->answer), $epsilon);
342                 return array($this->answer - $tolerance, $this->answer + $tolerance);
344             case 3: case 'geometric':
345                 $quotient = 1 + abs($tolerance);
346                 return array($this->answer / $quotient, $this->answer * $quotient);
348             default:
349                 throw new coding_exception('Unknown tolerance type ' . $this->tolerancetype);
350         }
351     }
353     public function within_tolerance($value) {
354         if ($this->answer === '*') {
355             return true;
356         }
357         list($min, $max) = $this->get_tolerance_interval();
358         return $min <= $value && $value <= $max;
359     }