REQS_MaxChars - wrong documentation?

This forum is for general developer support questions.

REQS_MaxChars - wrong documentation?

Postby softwarefailure » Mon Sep 25, 2017 7:59 pm

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.
softwarefailure
 
Posts: 62
Joined: Fri Feb 14, 2014 11:29 pm

Re: REQS_MaxChars - wrong documentation?

Postby xenic » Tue Sep 26, 2017 12:56 am

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
xenic
 
Posts: 1020
Joined: Sun Jun 19, 2011 1:06 am

Re: REQS_MaxChars - wrong documentation?

Postby salass00 » Tue Sep 26, 2017 9:44 am

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.
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
 
Posts: 477
Joined: Sat Jun 18, 2011 4:12 pm
Location: Finland

Re: REQS_MaxChars - wrong documentation?

Postby softwarefailure » Tue Sep 26, 2017 5:13 pm

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.
softwarefailure
 
Posts: 62
Joined: Fri Feb 14, 2014 11:29 pm

Re: REQS_MaxChars - wrong documentation?

Postby broadblues » Tue Sep 26, 2017 6:23 pm

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 )
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
 
Posts: 461
Joined: Sat Jun 18, 2011 3:40 am
Location: Portsmouth, UK

Re: REQS_MaxChars - wrong documentation?

Postby softwarefailure » Tue Sep 26, 2017 7:02 pm

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?
softwarefailure
 
Posts: 62
Joined: Fri Feb 14, 2014 11:29 pm

Re: REQS_MaxChars - wrong documentation?

Postby broadblues » Tue Sep 26, 2017 8:27 pm

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
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
 
Posts: 461
Joined: Sat Jun 18, 2011 3:40 am
Location: Portsmouth, UK

Re: REQS_MaxChars - wrong documentation?

Postby xenic » Tue Sep 26, 2017 8:47 pm

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
xenic
 
Posts: 1020
Joined: Sun Jun 19, 2011 1:06 am

Re: REQS_MaxChars - wrong documentation?

Postby salass00 » Tue Sep 26, 2017 10:08 pm

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.
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
 
Posts: 477
Joined: Sat Jun 18, 2011 4:12 pm
Location: Finland

Re: REQS_MaxChars - wrong documentation?

Postby softwarefailure » Tue Sep 26, 2017 10:37 pm

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.
softwarefailure
 
Posts: 62
Joined: Fri Feb 14, 2014 11:29 pm


Return to General Developer Support

Who is online

Users browsing this forum: No registered users and 1 guest