| Type | Wish | Status | complete | Date | 16-Feb-2010 15:56 |
|---|---|---|---|---|---|
| Version | alpha 97 | Category | Documentation | Submitted by | abolka |
| Platform | All | Severity | text | Priority | low |
| Summary | Reword the docstrings of EQUAL? and STRICT-EQUAL? |
|---|---|
| Description |
Currently, the docstrings of EQUAL? and STRICT-EQUAL? (or = and ==, respectively) are as follows: =: Returns TRUE if the values are equal. ==: Returns TRUE if the values are equal and of the same datatype. I suggest mentioning the behaviour regarding case sensitivity as well, as case sensitivity is, next to datatype-strictness, one of the primary reasons one would need == over =. Here's a concrete rewording suggestion: =: Returns TRUE for equal values. Case insensitive. ==: Returns TRUE for equal values that are of the same datatype. Case sensitive. |
| Example code |
| Assigned to | n/a | Fixed in | alpha 98 | Last Update | 8-May-2010 18:26 |
|---|
| Comments | |
|---|---|
|
(0002034)
abolka 16-Feb-2010 19:31 |
Another suggestion, inspired by Gregg: Do not mention any specifics of how strict equality is defined:
==: Returns TRUE if the values are strictly equal. This way, an interested user would have to look up more details on strict equality in any case (using HELP/doc, for example) and can not be fooled into thinking that the docstring fully defines the meaning of strict equality. |
|
(0002036)
BrianH 17-Feb-2010 02:32 |
I can see the point to "strictly equal". Another suggestion for the STRICT-EQUAL? doc string would be this:
"Returns TRUE if the values are equal and of the same datatype, case." Reasonably good English and it's concise, only 68 characters. Conciseness is important. The doc string for STRICT-NOT-EQUAL? would be: "Returns FALSE if the values are equal and of the same datatype, case." Or the ", " in both could be " & " and they would still fit. The trick to these is that EQUAL? is kind of approximate: - Datatypes are ignored within the same general category (string, number, word). - Decimal comparison only uses 15 digits rather than 17, which glosses over IEEE754 encoding errors. - String comparison is case-insensitive. - Word comparison ignores binding, datatype and case. So it's not just case-insensitivity. EQUIV? uses 17 digit decimal comparison and pays attention to word binding. STRICT-EQUAL? adds datatype and case comparison to what EQUIV? checks for - the suggestion above mentions those factors. The doc strings of EQUAL?, EQUIV?, STRICT-EQUAL? and SAME? are best looked at as a group, since the differences between them are relative, and in a progression of increasingly strict equivalence. |
|
(0002038)
Ladislav 17-Feb-2010 11:02 |
"Returns TRUE if the values are strictly equal." - I prefer this one, taking into account that case and datatype do not completely describe the strict equality anyway, which means that the same complaint is likely to occur again. |
|
(0002043)
BrianH 21-Feb-2010 23:03 |
I agree, Ladislav. Though case and datatype are the only differences between STRICT-EQUAL? and EQUIV?, that doesn't cover the differences between EQUIV? and EQUAL?. It would probably be best to just put the details on the web site instead of the doc string, which isn't supposed to be comprehensive documentation anyways. |
|
(0002286)
Carl 1-May-2010 00:17 |
Agreed per above. "Returns TRUE if the values are strictly equal." |
| Date | User | Field | Action | Change |
|---|---|---|---|---|
| 25-Sep-2013 09:29 | Ladislav | Comment : 0002038 | Modified | - |
| 25-Sep-2013 09:29 | Ladislav | Comment : 0002038 | Modified | - |
| 8-May-2010 18:26 | abolka | Status | Modified | tested => complete |
| 6-May-2010 09:27 | BrianH | Status | Modified | built => tested |
| 1-May-2010 00:17 | carl | Comment : 0002286 | Added | - |
| 1-May-2010 00:17 | carl | Status | Modified | reviewed => built |
| 1-May-2010 00:17 | carl | Fixedin | Modified | => alpha 98 |
| 21-Feb-2010 23:03 | BrianH | Comment : 0002043 | Added | - |
| 18-Feb-2010 09:13 | Ladislav | Comment : 0002038 | Modified | - |
| 17-Feb-2010 11:02 | Ladislav | Comment : 0002038 | Added | - |
| 17-Feb-2010 02:34 | BrianH | Status | Modified | submitted => reviewed |
| 17-Feb-2010 02:33 | BrianH | Comment : 0002036 | Modified | - |
| 17-Feb-2010 02:32 | BrianH | Comment : 0002036 | Added | - |
| 16-Feb-2010 19:32 | abolka | Comment : 0002034 | Modified | - |
| 16-Feb-2010 19:31 | abolka | Description | Modified | - |
| 16-Feb-2010 19:31 | abolka | Summary | Modified | Reword the docstrings of EQUAL? and STRICT-EQUAL? to mention case sensitivity => Reword the docstrings of EQUAL? and STRICT-EQUAL? |
| 16-Feb-2010 19:31 | abolka | Comment : 0002034 | Added | - |
| 16-Feb-2010 15:56 | abolka | Ticket | Added | - |