REQS_MaxChars - wrong documentation?

This forum is for general developer support questions.
Post Reply
softwarefailure
Posts: 112
Joined: Fri Feb 14, 2014 10:29 pm

REQS_MaxChars - wrong documentation?

Post by softwarefailure »

I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.
xenic
Posts: 1185
Joined: Sun Jun 19, 2011 12:06 am

Re: REQS_MaxChars - wrong documentation?

Post by xenic »

softwarefailure wrote:I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.
I don't see the problem. If you set REQS_MaxChars to 11 then you need to set your buffer size to 12 or larger. OS4 is subject to change in future versions so it's better to abide by the rule and have the extra byte in the buffer than to risk future failure of your program.
AmigaOne X1000 with 2GB memory - OS4.1 FE
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 530
Joined: Sat Jun 18, 2011 3:12 pm
Location: Finland
Contact:

Re: REQS_MaxChars - wrong documentation?

Post by salass00 »

If REQS_MaxChars has worked like it does now since the beginning and it's not just a recent bug then the more appropriate action would be to correct the documentation. Less chance of breaking existing programs that way.

BTW the autodoc entry for STRINGA_MaxChars doesn't mention at all whether the nul-terminator should be included in the value or not (it should). This should be clarified as well given that the tag name implies otherwise.

I'll fix both entries later today if someone else doesn't do it first.
softwarefailure
Posts: 112
Joined: Fri Feb 14, 2014 10:29 pm

Re: REQS_MaxChars - wrong documentation?

Post by softwarefailure »

xenic wrote: I don't see the problem.
The problem is that the documentation is wrong. Of course it would be utter non-sense to change the behaviour of REQS_MaxChars and break binary compatibility but the documentation needs to be fixed because what it currently states is wrong.
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 600
Joined: Sat Jun 18, 2011 2:40 am
Location: Portsmouth, UK
Contact:

Re: REQS_MaxChars - wrong documentation?

Post by broadblues »

softwarefailure wrote:I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.
No the REQS_MaxChars must as stated be no more than RQS_Buffer -1 this is not an error. The extra byte is for the terminating NULL as you might expect.

The confusion comes from the string.gadget needing 1 extra character to be able to enter a full length string, so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
softwarefailure
Posts: 112
Joined: Fri Feb 14, 2014 10:29 pm

Re: REQS_MaxChars - wrong documentation?

Post by softwarefailure »

broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 600
Joined: Sat Jun 18, 2011 2:40 am
Location: Portsmouth, UK
Contact:

Re: REQS_MaxChars - wrong documentation?

Post by broadblues »

softwarefailure wrote:
broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?
Because REQS_MaxChars must be a maximum of REQS_Buffer - 1

But the string gadget needs STRINGA_MaxChars to be 1 more than you need to enter (perhaps for the null or perhaps for a working byte) which might be argued to be bug, but is established behaviour for a long time.

Thus to ensure compatabilty there needs to be chars + 2 in the buffer
xenic
Posts: 1185
Joined: Sun Jun 19, 2011 12:06 am

Re: REQS_MaxChars - wrong documentation?

Post by xenic »

softwarefailure wrote:
broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?
Since '\0' is a char, the char count is 11 and the printable char count is 10.

Since we don't have access to the source code, we don't know what it does. Judging what it does based on "what works" could be wrong. I wrote a simple test program and set REQS_Maxchars to 12 and set REQS_Buffer size to 8. The program didn't bring up a Grim Reaper and didn't crash. However, I'm not going to assume that it should be done that way.
AmigaOne X1000 with 2GB memory - OS4.1 FE
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 530
Joined: Sat Jun 18, 2011 3:12 pm
Location: Finland
Contact:

Re: REQS_MaxChars - wrong documentation?

Post by salass00 »

broadblues wrote: Because REQS_MaxChars must be a maximum of REQS_Buffer - 1
That's what the autodoc said but it isn't true for any version of "requester.class" that is tagged in the SVN. Most likely the behaviour was changed very early on and the autodoc entry was simply not updated to reflect this.

I've fixed both STRINGA_MaxChars and REQS_MaxChars entries to make it clear that space for the nul-terminator needs to be included in the character count.
softwarefailure
Posts: 112
Joined: Fri Feb 14, 2014 10:29 pm

Re: REQS_MaxChars - wrong documentation?

Post by softwarefailure »

I've fixed both STRINGA_MaxChars and REQS_MaxChars entries to make it clear that space for the nul-terminator needs to be included in the character count.
In other words, both xenic and broadblues are wrong, just to make that clear again in case people dig up this thread later. No need to make things more complex than they are. It's a simple error in the doc, nothing to write home about.
Post Reply