`truncate-to` is confusing and should be replaced by `trunc-date`

[jubilatious1]

https://docs.raku.org/routine/truncated-to

truncate-to is an unfortunately-named function, since truncate is a common term and truncate-to gives no hint that DateTime is involved.

Perl reference: https://perldoc.perl.org/functions/truncate

A much better name would be trunc-date, possibly with a :to named-parameter.

(migrating from: https://www.nntp.perl.org/group/perl.perl6.users/2025/09/msg11503.html).

[jubilatious1]

A much better name would be trunc-date, possibly with a :to named-parameter.

[arkiuat]

Strictly speaking, it's a method, and the name is DateTime.truncated-to(). It's not as if you're able to accidentally call it as a free-standing routine with no DateTime object attached. I don't really see the advantage of this proposal.

[jubilatious1]

Apparently there's a system truncate, which Perl truncate appears to mirror:

https://unix.stackexchange.com/questions/1279/how-can-i-edit-a-large-file-in-place/1305#1305

Also, Perl truncate seems powerful, and yet no Raku truncate exists? Why not?

https://unix.stackexchange.com/questions/11067/is-there-a-way-to-modify-a-file-in-place/204378#204378
https://unix.stackexchange.com/questions/56841/deleting-specific-lines-and-duplicates-from-a-11gb-wordlist-text-file/56863#56863

---

SO why not:

1. ADD a Perl-like truncate function/method/routine for use on filehandles/Bufs/Blobs,
2. For Date/DateTime objects, ELIMINATE Raku truncate-to (the -to is confusing anyway),
3. For Date/DateTime objects, ADD the much more concise trunc-date function/method/routine.

[raiph]

Perl truncate seems powerful, and yet no Raku truncate exists? Why not?

I'm not sure, but here I'll argue that it might be as follows.

Raku makes it easy for devs to call C functions, including OS system calls. Why not just call the truncate system call?

Perl's truncate is a thin wrapper for the underlying OS's truncate system call. If the OS doesn't support truncate there's a fatal error. If the specified length is greater than the file's current size the behavior is undefined. If you try to truncate files over 4GB you may get a failure or error message. If the file is open in append mode on Windows it'll fail. Etc. In summary, Perl's truncate is just a wrapper, a thin one that provides no portability or defenses against things like common run-time errors or undefined behavior.

There was justification for Perl including such a weak truncate wrapper: calling a C function from Perl was too dauntingly complex, and the community presumably decided that if they introduced a thin wrapper they could then improve it over the years.

But that justification disappears in the context of Raku because it has a nice system for calling C functions, so adding a weak wrapper in core presumably makes no sense.

And knowing that the Perl community has been too stretched to sufficiently improve their truncate wrapper over the years could lead one to ask if Raku core devs should invest their precious time on taking on the heavy commitment of introducing a core truncate.

The foregoing is just a line of argument that I think is well-founded, but is perhaps not. As such it might be helpful if you rebutted any or all of it as you see fit.

[jubilatious1]

@raiph Two notes, in no particular order:

1. Typing man truncate at the MacOS command line brings up a truncate utility with the history: The truncate utility first appeared in FreeBSD 4.2. FreeBSD 4.2 was released in Nov. 2000. Elsewhere (Linux man pages) you'll see references to POSIX: POSIX.1-2001, 4.4BSD, SVr4 (first appeared in 4.2BSD).

2. One of the most popular Unix & Linux StackExchange posts (34 Upvotes) uses Perl's truncate, not system (i.e. POSIX) truncate. See: https://unix.stackexchange.com/questions/11067/is-there-a-way-to-modify-a-file-in-place/204378#204378

If Perl's truncate is so bad, why do sysadmins recommend it on Unix & Linux StackExchange? There must be something that keeps people using Perl's version (which is why Raku should have truncate as well).

[raiph]

@jubilatious1

1. Typing man truncate at the MacOS command line brings up a truncate utility with the history: "The truncate utility first appeared in FreeBSD 4.2". FreeBSD 4.2 was released in Nov. 2000. Elsewhere (Linux man pages) you'll see references to POSIX: POSIX.1-2001, 4.4BSD, SVr4 (first appeared in 4.2BSD).

OK. Given that you said it's a utility then it's presumably a truncate(1) (a binary supplied by the FreeBSD platform that wraps the underlying truncate(2) syscall), right? If so, my guess is Perl's truncate ignores it, and you could trivially call it using Raku. (Either way, I don't yet understand how it is relevant.)

2. One of the most popular Unix & Linux StackExchange posts (34 Upvotes) uses Perl's truncate, not system (i.e. POSIX) truncate.

That makes sense.

First, Perl is available on many systems (even though that pervasiveness has declined a bit this century, eg iirc it's harder to get at on MacOS).

Second, Perl is a proverbial swiss army chainsaw utility (binary) that one off scripts can not only use if it's available on a system a script is run on, but "neatly" covers a ton of useful things that pretty much no other utility does.

Thus, for a simple answer that's got a good chance of solving an asker's problem on the U&L SE that can't be covered with simpler utilities, Perl this-or-that was and remains a go-to choice.

I can imagine use of Perl's truncate making sense for two scenarios involving Raku:

1. A simple shell solution that might work for an asker might call the Perl truncate to do that particular bit. Short, sharp, simple. (Use Raku to do whatever it's better for than Perl.)

2. A simple Raku solution that might work for an asker might call the Perl truncate to do that particular bit. Again, short, sharp, simple, and you can use Raku to do whatever it's better for than Perl.

I can imagine use of Perl's truncate not making sense if the answer is supposed to deal with the various weaknesses in Perl's truncate (which is to say the things that can go wrong with the underlying truncate(2) syscall that Perl's truncate fails to address by improving its wrapper complexity).

In such a scenario a reasonable thing to do might be to write a better truncate wrapper, and to do that in Raku.

(But that's a very different thing from saying core devs should use their precious time and effort on writing it. Some Rakoon who cares to create a better truncate solution than Perl's, and perhaps FreeBSD's and others, could write it, and that, of course, would be a reasonable thing for them to try if they wanted to write it.)

If Perl's truncate is so bad, why do sysadmins recommend it on Unix & Linux StackExchange?

If someone wants to truncate in the context of a throw away script, or a script or program such that there's no justification for spending time to do better than Perl's truncate, and it's known that Perl might be available, and that nothing better than Perl's truncate is available, then it may well make sense to at least suggest that Perl's truncate is the best available option.

There must be something that keeps people using Perl's version

A) It's available. B) It's better than nothing.

(which is why Raku should have truncate as well)

I will argue it's a reason why Raku should not have truncate.

In the context of a throw away shell script, if an existing acceptable solution is available, then use it. For example, if Perl's available, and its truncate is acceptable, then use it. If Perl's not available, or its solution isn't acceptable, then use what is available and acceptable. For example, on MacOS / FreeBSD 4.2+, maybe using the truncate(1) utility you mentioned as point 1 does something better than some other way of wrapping the underlying truncate(2) syscall, and that improvement makes it acceptable.

Of course, if someone prefers to use Raku in some scenario, then there's arguably a much better option than using whatever utility is available (eg Perl, or some other truncate capable utility); write the Raku code that calls the underlying truncate(2) syscall, and defends against whatever problems that the likes of Perl's truncate (and perhaps FreeBSD's truncate(1)?) don't defend against that make them unacceptable or worthwhile outperforming.

(And better yet, pop that in a userland module so others can just use a Raku truncate function in that module that calls the truncate(2) syscall. And then we can start pointing out to folk that Raku has a better truncate function than Perl's or MacOS's. Furthermore, if some Rakoon does the work to introduce a superior truncate, then, after it's proven its quality for a few years, Rakoons could lobby for it to be merged into core.)

---

As a last couple notes:

• While I'm playing devil's advocate in response to your rationale, I am not attached to any particular position, just exploring writing an answer to your "Why not?" question.

• I feel I've engaged with your view enough to provide some balance for you and others to consider. I plan to stop at this stage. Please interpret me not commenting further in this issue as a desire for your side to get more room to breath after my long expositions, and to point out what I've got wrong.

[anjohnson]

The link in the first line of this issue shows that the method name is actually truncated-to (is that a past participle? My grammar is terrible), not truncate-to. It’s only one letter but IMHO that’s quite a difference, and that particular name makes perfect sense as the documented operation if you go read the link. No change is necessary to my mind.

[jubilatious1]

@anjohnson your grammar may be terrible, but how is your funny bone?

trunc-date is a play-on-words. You won't likely forget what kind of object trunc-date accepts.

(...and Raku can gain a file truncate method/routine without too much confusion).

@thoughtstream
@pmichaud
@TimToady

[jubilatious1]

@raiph

Perl's truncate is a thin wrapper for the underlying OS's truncate system call. If the OS doesn't support truncate there's a fatal error.

YES and NO. If Perl is calling system truncate, it is certainly going above and beyond that limited functionality. Quoting:

"Some systems have a truncate command that truncates files to a number of bytes (not characters). ... I don't know of any that truncate to a number of characters... ."

The author goes on to show how Per's truncate can be used to truncate files to a defined number of characters, not just bytes:

https://unix.stackexchange.com/a/459528/227738

Sounds like a great idea for a Raku function!

(&& let's please call it truncate to keep from confusing folks. Thx).

[arkiuat]

This change would break existing code, right? That is, it would force some existing code either to be revised or else to require using an older version of Raku from before this suggested change will have been made.

The advantages of a proposed change need to be pretty compelling to pass that bar.

[raiph]

@jubilatious1

Perl's truncate is a thin wrapper for the underlying OS's truncate system call. If the OS doesn't support truncate there's a fatal error.

YES and NO.

I'm confused by your answer. Is the YES applying to the first statement, the NO to the second one? Or are you saying you think "YES and NO" to both sentences? Or something else?

If Perl is calling system truncate, it is certainly going above and beyond that limited functionality.

Are you saying that it does that even If the OS doesn't support truncate?

I don't know of any that truncate to a number of characters, though you could resort to perl which is installed by default on most systems

I think the author makes clear several distinct but individually important points:

1. A problem with the truncate found on most systems is that it truncates based on bytes, not "characters".

2. perl is installed by default on many systems.

3. perl is able to truncate based on "characters" as well as bytes.

4. Specifically, when using perl, with -Mopen=locale, we use the locale's notion of what "characters" are (so in locales using the UTF-8 charset, that's UTF-8 encoded "characters")

My view on the foregoing begins with the following two fold approach:

1. It may well be smart to use perl if doing so gives a developer convenient support for the notion of what "characters" are that serves their purposes, and it's available by default on their target systems, because it has a built in truncate function that can truncate based on "characters".

2. It may well be smart to use Raku if doing so gives a developer convenient support for the notion of what "characters" are that serves their purposes, and they're willing to install it on their target systems, and it either has a built in truncate function that can truncate based on the relevant notion of "characters" (currently, it does not have any function of that ilk) or they're willing to code it up by taking advantage of one of Raku's relevant notions of "characters".

Raku's natural notion of "characters" is what a user thinks of as "characters". This is NOT the notion of "characters" used in the stackexchange discussion you linked. As such, Raku makes a strikingly odd choice for addressing those particular examples, but I've allowed that someone might want to trunctate based on what a user thinks of as "characters" in my point 2 above.

Sounds like a great idea for a Raku function!

As I've noted before, if you're willing to code it up and put it in a library, or persuade some other dev to do it for you, and then at some later point non-negligible demand emerges from the community of script writers for it to be part of standard Raku, then the time would be ripe for considering creation of a PR to make it so.

(&& let's please call it truncate to keep from confusing folks. Thx).

If someone adds it, then they can call it whatever they want, surely?

One of the things that most confused me about this issue was its title. It's no longer confusing to me, but I suspect it will confuse others. Which is ironic, at best, and now slightly irritating to me given that it's never been corrected. To mitigate the irritation I'll cover this aspect too in what follows.

First, the truncated-to method in the Date and DateTime classes are the only uses of that routine name in the entire of standard Raku. It is imo perfectly named. It returns a new value that's been truncated (hence the truncated part of its name). It takes a single positional argument that specifies the unit (second, minute, hour, day, month, year; clearly someone could add week, and perhaps decade and even century) that the new Date / DateTime value is to be truncated to (hence the -to part of its name).

Second, this issue is essentially about an entirely unrelated feature in systems (not Raku) that are to do with truncating a file. And quite reasonably, given that this feature alters the file in place, and that, when the feature was first introduced into systems, there was only one logical unit, namely bytes, which didn't need to be passed as an argument, it was called just truncate. Nice and simple.

[jubilatious1]

One of the things that most confused me about this issue was its title. It's no longer confusing to me, but I suspect it will confuse others. Which is ironic, at best, and now slightly irritating to me given that it's never been corrected. To mitigate the irritation I'll cover this aspect too in what follows.

truncate-to gives no hint that the invocant/object/substrate/thingy it is supposed to act on is a Date and/or DateTime.

trunc-date is a much better name, in part because truncate-to is name-squatting on any developer who wants to add a file-truncating utility to Raku.

[raiph]

I just googled Do you think that a method name should or should not try to hint what classes are valid as invocants via that method's name?. It returned a summary answer that began:

No, a method name should not try to hint at the class of the invocant; the class name already provides this context.

---

truncate-to is name-squatting on any developer who wants to add a file-truncating utility to Raku.

There is no Raku method named truncate-to. So it can't be name-squatting.

There is a Raku method named truncate. I would have thought you'd be more concerned about that.

But again, it isn't name-squatting. You, or any other developer, are free to add a file-truncating utility to Raku.

And if you or anyone else wanted to call it truncate that would be perfectly cromulent.

And imo the latter would be true whether or not it were to end up in core.

[jubilatious1]

@raiph I'm quite sure that when I started looking at these "naming" issues in Raku, there was no truncate method in Raku.

Possibly by now this has been many years ago. Can you tell me when Raku's truncate was added?

Also, now looking at Raku's truncate I see it generally takes an invocant number, described as "Rounds the number towards zero" (in Role Real) and also "Coerces the invocant (or in sub form, its argument) to Numeric, and rounds it towards zero" (in Cool).

Both descriptions use the verb round. So why isn't this method called round?