The new time API

[Laurent]

You missed the point. I don't care whether it's static or not. It's all about the very name

Ok, I get it now.
But, seriously, what could sf::Seconds(n) return, other than a time value of n seconds? In actual code, the context will make it even more obvious. Seconds are time, it's implicit. "TimeFromSeconds" even looks weird, because seconds are already time. If sf::Seconds returned something else than a time value, ok, it would be very confusing. But it doesn't.
So do we really need all this extra verbosity? I don't think so.

Er, what do you mean?

You said that the STL API was clearer because std::seconds is a class. It's true: if the function that you're calling expects a std::seconds argument, it's clear that you must construct a std::seconds instance. But if it expects a std::duration<...>, a std::milliseconds or whatever other than std::seconds (which is likely to happen), then it's not clearer than SFML's solution, you still need to read the documentation to figure out what to do.

[Silvah]

But, seriously, what could sf::Seconds(n) return, other than a time value of n seconds?

In fact, I have a hard time getting its meaning. I can't think of any thing that call could do. Including returning a time of n seconds. It's just too imprecise.

Seconds are time, it's implicit. "TimeFromSeconds" even looks weird, because seconds are already time.

That's disputable, actually. The definition of time is very abstract and vague. The definition of second is very precise. You know, the second is a unit of measurement of time (defined to, well, something). So, you have a number of seconds (a specific thing), and convert it to some abstract thing (namely, to time). Makes some sense, given that the end user isn't supposed to know how the time is defined internally (just like we don't how the universe represents the time internally)

You said that the STL API was clearer because std::seconds is a class. It's true: if the function that you're calling expects a std::seconds argument, it's clear that you must construct a std::seconds instance. But if it expects a std::duration<...>, a std::milliseconds or whatever other than std::seconds (which is likely to happen), then it's not clearer than SFML's solution, you still need to read the documentation to figure out what to do.

The first thing one would try is probably to construct a std::seconds object and let the compiler worry about the (implicit) conversion. And this really works. But I don't see what does it have to do with what we're talking about. Its name is clearer because it's a class; the fact that it's in fact a typedef to a template has some nasty implications, that's right, but these are beyond the scope of what we're currently focusing on.


As an aside, a minor nitpick that's not meant to be treated very seriously (it just shows how relative things that we think are obvious can be): what's the result of "an hour + two minutes"? Sixty-two minutes? Why not fifty-eight minutes? In some cultures, the past is in front of you (because you can see it) and the future is behind you (because you can't). And you add, so you go forward, so you effectively subtract the time

[Laurent]

In fact, I have a hard time getting its meaning. I can't think of any thing that call could do. Including returning a time of n seconds. It's just too imprecise.

If you think of it as a named constructor for a time class (whether it is named sf::Seconds of sf::Time doesn't really matter), I think it's clear enough. It's not a function that does something.

That's disputable, actually. The definition of time is very abstract and vague. The definition of second is very precise. You know, the second is a unit of measurement of time (defined to, well, something). So, you have a number of seconds (a specific thing), and convert it to some abstract thing (namely, to time). Makes some sense, given that the end user isn't supposed to know how the time is defined internally (just like we don't how the universe represents the time internally)

You want a certain amount of seconds -> you call sf::Seconds. I think it's really straightforward. Adding "Time" to the function name would add confusion. At least that's my opinion and I'm not convinced by your arguments so far

The first thing one would try is probably to construct a std::seconds object and let the compiler worry about the (implicit) conversion.

How does the user know about the std::seconds class if it doesn't appear in the function prototype?

But I don't see what does it have to do with what we're talking about.

You said that SFML tries to mimic the STL in a bad (or less clear) way. I think it's wrong, the same issues apply with the STL API.

As an aside, a minor nitpick that's not meant to be treated very seriously (it just shows how relative things that we think are obvious can be): what's the result of "an hour + two minutes"? Sixty-two minutes? Why not fifty-eight minutes? In some cultures, the past is in front of you (because you can see it) and the future is behind you (because you can't). And you add, so you go forward, so you effectively subtract the time

I think it's simpler than what you think: if you add two values of a certain unit, you must use mathematical addition. And you end up with a new value of the same unit which is the sum of both operands.
If I understand correctly, your point would apply if we tried to add a time span to a time point (like "what's the result of 11:52 plus 2 minutes?). But here we add a time span to another time span -- we get a bigger time span.

[Mario]

I think I know what Silvah is trying to point out (correct me if I'm wrong):

A "time" could be several things. It could mean a duration as well as a specific point in time (as in 5:00 pm). That's more or less ambiguous.

What I'd be doing would be calling the basic time object Duration and then renaming Clock to Stopwatch.

---

Actually, thinking about it, it could get even more interesting and making the rework even more awesome:

sf::Duration: Defines a specific duration like 5 seconds, 10 minutes or 50 µs.

sf::Clock: Abstract base class for the following classes (not sure about this one).

sf::Stopwatch: Essentially the current sf::Clock class. It allows you to start a timer and then determine the amount of time that has passed.

sf::Timer: A class allowing you to start a timer that will trigger a new event once some specific time has passed. The event data includes a pointer (or reference?) to this object, allowing identification/control. I'm not really sure how this should work, to be honest, it might as well be some extension to windows instead (window.SetTimeout(myidentifier,somedurationobject)).

[Laurent]

A "time" could be several things. It could mean a duration as well as a specific point in time (as in 5:00 pm). That's more or less ambiguous.

There's absolutely no concept of time point in SFML, so the ambiguity is very reduced.

What I'd be doing would be calling the basic time object Duration

I have no strong argument against it, but sf::Time looks better

and then renaming Clock to Stopwatch.

I recently learnt that StopWatch is a better name, but it seems that sf::Clock is ok too.

sf::Clock: Abstract base class for the following classes (not sure about this one).

An abstract class here? Why?

sf::Timer: A class allowing you to start a timer that will trigger a new event once some specific time has passed.

SFML doesn't support "events" (signals/slots). And it's too high level anyway, what we're talking about is a simple (and thus unique) way of measuring and handling time.

[Silvah]

It's not a function that does something.

But it is a function that does something, it returns an object

You want a certain amount of seconds -> you call sf::Seconds. I think it's really straightforward.

I think it's not, the name is too vague. But I guess I have said that already.

Adding "Time" to the function name would add confusion. At least that's my opinion and I'm not convinced by your arguments so far

Have I already said that you missed the point, by any chance?

But "Time::FromSeconds" (or "TimeFromSeconds" or anything that explicitly states what the function does) makes that clear from the beginning.

While I agree that the names I proposed aren't the most fortunate ones, they're not the only possibilities. Hopefully someone who knows English better than I do can come up with something better. So maybe we should focus on inventing better name instead?

How does the user know about the std::seconds class if it doesn't appear in the function prototype?

The user knows because it's the thing that one uses to store seconds. And then the user tries to pass it into something which expects other units. And lo! it happens to work. Hooray for trial and error!

You said that SFML tries to mimic the STL in a bad (or less clear) way. I think it's wrong, the same issues apply with the STL API.

These issues are not the same. They're related, yes, but they're slightly different and their causes have nothing to do with each other.

[Laurent]

Hmm... let's try to work differently

Who else has an opinion about the function names? Clear and concise, or too vague?

Who (native english speakers?) can suggest better names?

You'd better answer if you want to see SFML 2.0 soon :twisted: :lol:

[Tex Killer]

Who else has an opinion about the function names? Clear and concise, or too vague?

I think he has a point... Not a very strong one, but a point that counts towards the simplicity of trial and error...

You write sf::Time and hit the completion shortcut of your IDE: you get sf::TimeFromSeconds, sf::TimeFromMilliseconds and sf::TimeFromMicroseconds on the sugestion list.

But I wouldn't mind if it ends as you made so far.

[Hiura]

For what it is worth, here's my ideas.

First, it was proposed to change sf::Clock name (to StopWatch or something else). IMHO, I think it is NOT a good idea : sf::Clock came in SFML 1 and changing its name for something "only a little bit better" would confuse most people. There won't be any benefit.

Now, about the sf::Time class : I would suggest sf::TimeSpan instead. It's maybe not the most crucial thing here. However, these 4 last letters clearly state that you won't be able to get the current day or the week, or get the next leap year, etc...

There is also the problem of ToSeconds(), or, as proposed above, AsSeconds(). Personally, I would prefer TotalSeconds instead because there's no meaning of conversion : we only extract the number of seconds from the time span. In fact, this is how Microsoft does it in C# with TimeSpan.

You discussed about making Seconds(), Milliseconds(), and Microseconds() static functions of sf::Time or free function instead. Because I have relatively little experience on this topic I decided to look around what was the best and found this article :

[...]
This analysis applies to any kind of member functions, including static ones. Adding a static member function to a class when its functionality could be implemented as a non-friend non-member decreases encapsulation by exactly the same amount as does adding a non-static member function. One implication of this is that it's generally a bad idea to move a free function into a class as a static member just to show that it's related to the class. [...]

However, I 'm not sure what name fit the best. sf::TimeFromSeconds (or TimeSpanFronSeconds) is long but has no ambiguity and is straightforward. But Seconds seems enough in most context : like sf::Sleep(sf::Seconds(1)).

Sorry if I'm not focused on the real issue.

[Groogy]

You'd better answer if you want to see SFML 2.0 soon :twisted: :lol:

Damn you!

 I can understand his point. But I feel your arguments are more correct. Kind of hard to speak my mind from the phone. But take it as a base that I will always like the solution that makes it sound more like speech. Take time.As* for example.

I hope I count as well since I started with English around the age of 8.

EXPANSION:

Alright now that I'm on my Laptop instead I would like to expand this a little more.

From my understanding this is the proposed convention from Silvah:

Code: [Select]

time = sf::Time::FromSeconds(N);This to me reads as: "time equal to time from N seconds"
Could cut away the second time but it still become "time equal to from N seconds"

This is why I like Laurents version more as it becomes:

Code: [Select]

time = sf::Seconds(N); which in my eyes reads as "time equal to N seconds". And to me this feels a lot more natural.

And I can't see the ambiguity that other's see with having these functions in the global space. But since people are seeing things. It means that it isn't perfect. But I urge that you do something similar. I really love it when you can read the code as normal English speech and it goes hand in hand with readability, some programming paradigms like polymorphism and in some cases it can also solve ambiguity just as how it is solved in real life language. Though of course sometimes you can still be confused in real life because you missed the context as the sentence was said in. But doing that in code is much harder in my opinion because the text is there starring you in the face while words float away and you have to guess what you missed.

Just adding an example and "translating it":

Code: [Select]

sf::Time time = sf::Seconds( N  ); // time is equal to N seconds
printf( "%f", time.AsMicroSeconds() ); // Print the time as micro seconds
myCountDown -= clock.GetElapsedTime(); // The countdown is subtracted with the elapsed time.
if( myCountDown <= sf::Seconds( 0 ) ) // If the countdown is less or equal to 0 seconds then do stuff
    doStuff();


[model76]

I really like "AsSeconds", as Groogy suggested. It's short, and it explains what it does perfectly.
"TotalSeconds" is not only longer, but it also introduces ambiguity, as it could be understood as "the seconds component of the time duration".

I also see Silvah's point. TimeFromSeconds is self-explanatory, while Seconds is not. It is also a long name, but is that really such a big problem in this case? Is it likely to often be used in a context where the long name makes the code hard to read?

Also, I think I would personally find TimeFromSeconds easier to remember, because it starts with Time. I often have a hard time remembering names, so code completion helps me a lot.

[Ceylo]

So much discussion... for a little innocent name..

[model76]

You are right, it probably isn't that important, but Laurent is holding SFML 2.0 hostage!    :wink:

[Tex Killer]

Code: [Select]

if( myCountDown <= sf::Seconds( 0 ) ) // If the countdown is less or equal to 0 seconds then do stuff
    doStuff();


Not that it matters much, but I don't think this would work as I think you wanted it to... It would only check if the myCountDown clock haven't yet passed one single microsecond, as the time instance with 1 microsecond is bigger than the one with 0.

[Laurent]

Not that it matters much, but I don't think this would work as I think you wanted it to... It would only check if the myCountDown clock haven't yet passed one single microsecond, as the time instance with 1 microsecond is bigger than the one with 0.

As the name and comment imply, I think the myCountDown variable decreases until it reaches zero. So the code is ok.