Nice TWiki > Dev > UserManualOmissions (r1.35) TWiki webs:
Dev | Doc | Main | TWiki | Sandbox
Dev . { Changes | Index | Search | Go }
These are aspects of the language that are not covered by the User Manual, but that should be.

Aspects that should be updated:

Things that we can't do yet:

Things that have now been done:

Important

I'll be making another round of changes to the manual in the next few weeks, and I'm going to be looking at this page first when I decide what needs coverage. So if there's something important missing from the manual, please note it on this page ASAP. Your help means a better manual, and happier users.

Thanks.

-- BrynKeller - 01 Oct 2003


The documentation for || with nulls should explain the interaction between || and autoboxing. In particular, 1 || 2 seems to be the same as new Integer(1) || new Integer(2). (The compiler should also be able to detected the dead code in this situation: new Integer(1) can never be null, so new Integer(2) is never executed.) Also, the documentation should explain the way that || coexists with the nullness checking for fields as demonstrated at the end of this example:

    class A { ?Integer n; }

    void main(String [] args) {
        println(0 || 1);
        println(2 || 1);


        println(null           || new Integer(1));
        println(new Integer(2) || new Integer(1));

        let a1 = new A(n: null),
            a2 = new A(n: new Integer(2));

        println(a1.n || new Integer(1));
        println(a2.n || new Integer(1));

        Integer n1 = a2.n || new Integer(1);
        println(n1);

        // NOT equivalent to
        //    n2 = a2.n || new Integer(1);
        // error:
        //    The value if(`!=`(a2.n(), null))
        //                 a2.n()
        //              else
        //                 new Integer(1)
        //    cannot be assigned to n2 because it might be null.
        //
        // Integer n2 = a2.n != null ? a2.n : new Integer(1);
        // println(n2);

        // equivalent to
        //    n3 = a2.n || new Integer(1);
        ?Integer temp = a2.n;
        Integer n3 = temp != null ? temp : new Integer(1);

        println(n3);
    }
Output:
    0
    2
    1
    2
    1
    2
    2
    2


Why do you use Integer as type instead of int? What made you trying out all kinds of variations with the || operator?

I don't think users need to know about how autoboxing happens. -- ArjanB - 29 Jan 2004

It was mentioned in the ConstructorSyntax discussion I believe. I tried it out because it wasn't documented and I wanted to figure out the semantics. I think it is important to document the semantics explicitly. But I think that I may be wrong about autoboxing anyway; it is also not documented and I haven't been able to figure out the autoboxing semantics yet. Anyway, I think that operator || is simply mistyped and should not apply to int/byte/long/float/double since it doesn't make any sense for numeric types. Maybe the typing should be:

    <Any T, T U> !T `||`(#?T e1, !U e2) = inline nice.lang.inline.OptionOr();
    <Any T, T U> ?T `||`(#?T e1, ?U e2) = inline nice.lang.inline.OptionOr();
That is, somehow require that the first parameter be an option (nullable) type. The Nicec compiler doesn't accept this syntax but maybe there is another way? -- BrianSmith - 29 Jan 2004

The OptionOr? can make sense for numeric types too, example:

Map<String, int> map = new HashMap();
map["abc"] = 5;
int n1 = map["xyz"] || -1;
int n2 = map["abc"] || -1;
println(n1); //prints -1
println(n2); //prints 5

It's not possible to give OptionOr? a type so that it requires the first parameter to be an option type because of the typechecking rules for function application. But OptionOr? is an inlined operator so it would be possible to generate a warning when using it with a non option type first argument.

-- ArjanB - 29 Jan 2004

|| is a method defined in nice.lang, so I don't think it should be documented in the UserManual?. As soon as we have a working nicedoc, we'll publish the documentation for the standard libraries on the website.

The general question is to document when autoboxing happens. On the one hand, one can often see that as an implementation detail, but either when you use reference equality or for performance reasons, it is sometimes important to know. So yes, that should be better documented. I'm not sure if it should go in the UserManual?, or if we should have a different document for lower-level aspects like this (this does not really belong to the definition of Nice itself, it just happens to work like this when you compile to the JVM).

The rule is that when a primitive value is used when a generic type (T) or an Object is expected, the value is boxed. Unboxing happens as need when a boxed value is used where a primitive type is expected.

-- DanielBonniot - 30 Jan 2004

String Examples

The documentation mentions multi-line strings but it would be clearer to show how they would map to traditional syntax. For example, it is not clear how whitespace at the beginnning/end of an internal line works in a multi-line string.

    let greeting  = """
            Hello, world.
       You may be thinking, \"Why was I called here today?\"
       Well, there was a good reason. Honest.
      """;   
Is it equivalent to:
   let greeting  =   "Hello, world. "
                 + "You may be thinking, \"Why was I called here today?\" "
                 + "Well, there was a good reason. Honest.";
or:
   let greeting  =   "Hello, world.\n"
                 + "You may be thinking, \"Why was I called here today?\"\n"
                 + "Well, there was a good reason. Honest.";
or something else?

Hmmm maybe there's something to be said for being explicit, my guess would have been

   let greeting  =   "\nHello, world.\n"
                 + "You may be thinking, \"Why was I called here today?\"\n"
                 + "Well, there was a good reason. Honest.\n";
-- IsaacGouy - 08 Feb 2004

Topic UserManualOmissions . { Edit | Attach | Ref-By | Printable | Diffs | r1.43 | > | r1.42 | > | r1.41 | More }
Revision r1.35 - 08 Feb 2004 - 20:43 GMT - IsaacGouy
Parents: WebHome
Copyright © 1999-2003 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback.