Programming in D - Member Functions

Member Functions

Although this chapter focuses only on structs, most of the information in this chapter is applicable to classes as well.

In this chapter we will cover member functions of structs and define the special toString() member function that is used for representing objects in the string format.

When a struct or class is defined, usually a number of functions are also defined alongside with it. We have seen examples of such functions in the earlier chapters: addDuration() and an overload of info() have been written specifically to be used with the TimeOfDay type. In a sense, these two functions define the interface of TimeOfDay.

The first parameter of both addDuration() and info() has been the TimeOfDay object that each function would be operating on. Additionally, just like all of the other functions that we have seen so far, both of the functions have been defined at the module level, outside of any other scope.

The concept of a set of functions determining the interface of a struct is very common. For that reason, functions that are closely related to a type can be defined within the body of that type.

Defining member functions

Functions that are defined within the curly brackets of a struct are called member functions:

struct SomeStruct {
    void member_function(/* the parameters of the function */) {
        // ... the definition of the function ...
    }

    // ... the other members of the struct ...
}

Member functions are accessed the same way as member variables, separated from the name of the object by a dot:

    object.member_function(arguments);

We have used member functions before when specifying stdin and stdout explicitly during input and output operations:

    stdin.readf(" %s", &number);
    stdout.writeln(number);

The readf() and writeln() above are member function calls, operating on the objects stdin and stdout, respectively.

Let's define info() as a member function. Its previous definition has been the following:

void info(TimeOfDay time) {
    writef("%02s:%02s", time.hour, time.minute);
}

Making info() a member function is not as simple as moving its definition inside the struct. The function must be modified in two ways:

struct TimeOfDay {
    int hour;
    int minute;

    void info() {    // (1)
        writef("%02s:%02s", hour, minute);    // (2)
    }
}

The member function does not take the object explicitly as a parameter.
For that reason, it refers to the member variables simply as hour and minute.

This is because member functions are always called on an existing object. The object is implicitly available to the member function:

    auto time = TimeOfDay(10, 30);
    time.info();

The info() member function is being called on the time object above. The members hour and minute that are referred to within the function definition correspond to the members of the time object, specifically time.hour and time.minute.

The member function call above is almost the equivalent of the following regular function call:

    time.info();    // member function
    info(time);     // regular function (the previous definition)

Whenever a member function is called on an object, the members of the object are implicitly accessible by the function:

    auto morning = TimeOfDay(10, 0);
    auto evening = TimeOfDay(22, 0);

    morning.info();
    write('-');
    evening.info();
    writeln();

When called on morning, the hour and minute that are used inside the member function refer to morning.hour and morning.minute. Similarly, when called on evening, they refer to evening.hour and evening.minute:

10:00-22:00

`toString()` for `string` representations

We have discussed the limitations of the info() function in the previous chapter. There is at least one more inconvenience with it: Although it prints the time in human-readable format, printing the '-' character and terminating the line still needs to be done explicitly by the programmer.

However, it would be more convenient if TimeOfDay objects could be used as easy as fundamental types as in the following code:

    writefln("%s-%s", morning, evening);

In addition to reducing four lines of code to one, it would also allow printing objects to any stream:

    auto file = File("time_information", "w");
    file.writefln("%s-%s", morning, evening);

The toString() member function of user-defined types is treated specially: It is called automatically to produce the string representations of objects. toString() must return the string representation of the object.

Without getting into more detail, let's first see how the toString() function is defined:

import std.stdio;

struct TimeOfDay {
    int hour;
    int minute;

    string toString() {
        return "todo";
    }
}

void main() {
    auto morning = TimeOfDay(10, 0);
    auto evening = TimeOfDay(22, 0);

    writefln("%s-%s", morning, evening);
}

toString() does not produce anything meaningful yet, but the output shows that it has been called by writefln() twice for the two object:

todo-todo

Also note that info() is not needed anymore. toString() is replacing its functionality.

The simplest implementation of toString() would be to call format() of the std.string module. format() works in the same way as the formatted output functions like writef(). The only difference is that instead of printing variables, it returns the formatted result in string format.

toString() can simply return the result of format() directly:

import std.string;
// ...
struct TimeOfDay {
// ...
    string toString() {
        return format("%02s:%02s", hour, minute);
    }
}

Note that toString() returns the representation of only this object. The rest of the output is handled by writefln(): It calls the toString() member function for the two objects separately, prints the '-' character in between, and finally terminates the line:

10:00-22:00

The definition of toString() that is explained above does not take any parameters; it simply produces a string and returns it. An alternative definition of toString() takes a delegate parameter. We will see that definition later in the Function Pointers, Delegates, and Lambdas chapter.

Example: `increment()` member function

Let's define a member function that adds a duration to TimeOfDay objects.

Before doing that, let's first correct a design flaw that we have been living with. We have seen in the Structs chapter that adding two TimeOfDay objects in addDuration() is not a meaningful operation:

TimeOfDay addDuration(TimeOfDay start,
                      TimeOfDay duration) {  // meaningless
    // ...
}

What is natural to add to a point in time is duration. For example, adding the travel duration to the departure time would result in the arrival time.

On the other hand, subtracting two points in time is a natural operation, in which case the result would be a duration.

The following program defines a Duration struct with minute-precision, and an addDuration() function that uses it:

struct Duration {
    int minute;
}

TimeOfDay addDuration(TimeOfDay start,
                      Duration duration) {
    // Begin with a copy of start
    TimeOfDay result = start;

    // Add the duration to it
    result.minute += duration.minute;

    // Take care of overflows
    result.hour += result.minute / 60;
    result.minute %= 60;
    result.hour %= 24;

    return result;
}

unittest {
    // A trivial test
    assert(addDuration(TimeOfDay(10, 30), Duration(10))
           == TimeOfDay(10, 40));

    // A time at midnight
    assert(addDuration(TimeOfDay(23, 9), Duration(51))
           == TimeOfDay(0, 0));

    // A time in the next day
    assert(addDuration(TimeOfDay(17, 45), Duration(8 * 60))
           == TimeOfDay(1, 45));
}

Let's redefine a similar function this time as a member function. addDuration() has been producing a new object as its result. Let's define an increment() member function that will directly modify this object instead:

struct Duration {
    int minute;
}

struct TimeOfDay {
    int hour;
    int minute;

    string toString() {
        return format("%02s:%02s", hour, minute);
    }

    void increment(Duration duration) {
        minute += duration.minute;

        hour += minute / 60;
        minute %= 60;
        hour %= 24;
    }

    unittest {
        auto time = TimeOfDay(10, 30);

        // A trivial test
        time.increment(Duration(10));
        assert(time == TimeOfDay(10, 40));

        // 15 hours later must be in the next day
        time.increment(Duration(15 * 60));
        assert(time == TimeOfDay(1, 40));

        // 22 hours 20 minutes later must be midnight
        time.increment(Duration(22 * 60 + 20));
        assert(time == TimeOfDay(0, 0));
    }
}

increment() increments the value of the object by the specified amount of duration. In a later chapter we will see how the operator overloading feature of D will make it possible to add a duration by the += operator syntax:

    time += Duration(10);    // to be explained in a later chapter

Also note that unittest blocks can be written inside struct definitions as well, mostly for testing member functions. It is still possible to move such unittest blocks outside of the body of the struct:

struct TimeOfDay {
    // ... struct definition ...
}

unittest {
    // ... struct tests ...
}

Exercises

Add a decrement() member function to TimeOfDay, which should reduce the time by the specified amount of duration. Similar to increment(), it should overflow to the previous day when there is not enough time in the current day. For example, subtracting 10 minutes from 00:05 should result in 23:55.

In other words, implement decrement() to pass the following unit tests:

struct TimeOfDay {
    // ...

    void decrement(Duration duration) {
        // ... please implement this function ...
    }

    unittest {
        auto time = TimeOfDay(10, 30);

        // A trivial test
        time.decrement(Duration(12));
        assert(time == TimeOfDay(10, 18));

        // 3 days and 11 hours earlier
        time.decrement(Duration(3 * 24 * 60 + 11 * 60));
        assert(time == TimeOfDay(23, 18));

        // 23 hours and 18 minutes earlier must be midnight
        time.decrement(Duration(23 * 60 + 18));
        assert(time == TimeOfDay(0, 0));

        // 1 minute earlier
        time.decrement(Duration(1));
        assert(time == TimeOfDay(23, 59));
    }
}

Convert Meeting, Meal, and DailyPlan overloads of info() to toString() member functions as well. (See the exercise solutions of the Function Overloading chapter for their info() overloads.)
You will notice that in addition to making their respective structs more convenient, the implementations of the toString() member functions will all consist of single lines.

... the solutions

[ ↢ Prev ] [ Next ↣ ]

Member Functions

Defining member functions

toString() for string representations

Example: increment() member function

Exercises

`toString()` for `string` representations

Example: `increment()` member function