Permalink
Browse files

Create documentation for Object Usage.

This defines the design and syntax for how objects can be used.
  • Loading branch information...
LadyCailin committed Nov 26, 2018
1 parent 33140f6 commit 1ff50aabe859962b3b34cfa810c92f131a44b251
Showing with 103 additions and 0 deletions.
  1. +103 −0 src/main/resources/docs/ObjectUsage
@@ -0,0 +1,103 @@
Creating an object and using an existing one are two different topics, and are thus given separate
treatments. This article discusses the usage of objects, rather than how they are created, for that
discussion, see [Classes].
== Using instances ==
An instance of an object is some concrete instance of a Class definition. You can think of a Class as
a blueprint, and an instance as the building itself. Many buildings can be built from the same blueprint,
and each will have their own slightly different properties, of which can also change over time. Manipulation
of one of these instances will not affect the others. A variable contains an instance of some class, though
it can change as well. A variable with a type, for instance <%CODE|int @a;%> can only contain an int, though
that int can start out as 5, and be changed to 8 later. While this is a simple example, it is important to
understand that there is a difference between what is currently stored in a variable, and what an instance
is. Normally, when using an instance, you will not need to understand static members, which are elements
(fields or methods) that are shared across all instances of that particular object, as so in this section,
we will only discuss objects that do not have static methods. In order to access an instance method or field,
we use the arrow operator <%PRE|->%>. This is a binary operator, meaning that there must be something on both
the right and left of the operator. The thing on the left is the instance that we are wanting to operate on,
and the right is the name of the method or field that we want to access. The left hand side may be either an
object itself, or a variable containing some instance.
<%CODE|
int @value = 10;
string @s = 5->toString(); // "5"
string @r = @value->toString(); // "10"
%>
Both of these examples call the method "toString", which is defined in the int class. The first example calls
it directly on an instance of the object, the second calls it on the variable, which in this case contains
an instance of the int value 10.
Fields are accessed the same way, but without the () at the end. Methods can be chained as well, the return value
on the first is used in the second, and so on.
<%CODE|
array @value = array('VALUE', 'value');
string @lowercased = @value->toString()->toLowerCase();
%>
In this example, the intermediate string is directly used again. This is the same as writing:
<%CODE|
array @value = array('VALUE', 'value');
string @valueString = @value->toString();
string @lowercased = @valueString->toLowerCase();
%>
== Static Elements ==
Static elements of a class are things that are associated with the class itself, not the instances (if any) of
the class. The general principals work more or less the same, but there is slightly different syntax to access
the methods or fields, <%PRE|::%> is used instead, and the value on the left hand side must be a ClassType value.
<%CODE|
int @max = int::GetMax(); // This returns the maximum allowed integer value
%>
Just like with instances, the value on the left may be a variable, though the variable must be holding a ClassType
for this to work.
<%CODE|
auto @i = int;
int @max = @i::GetMax();
%>
This feature is not strictly useful though, and for more strict programming styles, this is not recommended as such.
However, the ClassType definition can accept a constrained type, which is discussed in the next section.
== ClassType ==
Using [Generics] and ClassType variables, it is possible to do more interesting things with static methods. Taking
the previous example, using ClassType instead, let's take a look at a different example.
<%CODE|
ClassType<int> @i = int;
int @max = @i::GetMax();
%>
In this example, we specifically define ''@i'' as ''ClassType&lt;int&gt;'', which is the precise type of ''int''. This
is the equivalent of the previous example, without auto typing. While this is possible, there are not many cases where
this is useful, because the only thing that can be assigned in this value is ''int'', so it would be easier to use
that value directly. However, the generic parameter can be less restricted and still correct, which may lead to more
useful scenarios.
<%CODE|
ClassType<? extends MySuperclass> @i = MySubclass;
@i::StaticMethod();
%>
In this example, @i could be any subclass of MySuperclass (or MySuperclass itself). Assuming MySuperclass defines
a method named StaticMethod, then this becomes useful if MySubclass may or may not override that static method.
<%TAKENOTE|Overriding static methods is beyond the scope of this article, see the article about [Classes] for
a further discussion.%>
It is worth pointing out that ClassTypes are themselves instances, and have instance methods, thus the need for
different operators for accessing instance methods vs static methods. To access the instance methods defined in
ClassType itself, use the -&gt; operator.
<%CODE|
msg(int->getSuperclasses()); // Accesses the instance method getSuperclasses defined in ClassType
msg(int::GetMax()); // Access the static method GetMax defined in int
%>

0 comments on commit 1ff50aa

Please sign in to comment.