Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate
Photo

Choose naming and syntax for built-in Extract/InsertInteger


  • Please log in to reply
100 replies to this topic

Poll: Pass "VarOrAddress, Offset" (20% faster and possibly less error-prone) vs. "&Var + Offset" (fewer parameters and more pure)? (13 member(s) have cast votes)

Pass "VarOrAddress, Offset" (20% faster and possibly less error-prone) vs. "&Var + Offset" (fewer parameters and more pure)?

  1. I strongly prefer passing the single parameter: &Var + Offset (0 votes [0.00%])

    Percentage of vote: 0.00%

  2. I slightly prefer passing the single parameter: &Var + Offset (3 votes [23.08%])

    Percentage of vote: 23.08%

  3. I strongly prefer passing two parameters: VarOrAddress, Offset (4 votes [30.77%])

    Percentage of vote: 30.77%

  4. I slightly prefer passing two parameters: VarOrAddress, Offset (3 votes [23.08%])

    Percentage of vote: 23.08%

  5. No preference. (3 votes [23.08%])

    Percentage of vote: 23.08%

Vote Guests cannot vote
Chris
  • Administrators
  • 10727 posts
  • Last active:
  • Joined: 02 Mar 2004
Here is the planned syntax (I used Laszlo's names for now):
GetNum(VarOrAddress, Offset = 0, SignedOrFloat? = 0, Size = 4)
PutNum(Number, VarOrAddress, Offset = 0, Size = 4)  ; Best parameter order?
If the caller passes in a variable for VarOrAddress, that variable's address is used as the base. Otherwise, the value is assumed to be a numeric address. If you think about it, this is weird/inconsistent; but it helps user-friendliness (since caller doesn't need to use & or + operators) and it benchmarks 15% faster compared to passing something like "&var + 4". This also explains the Offset parameter (i.e. it's faster and more user-friendly).

The whole reason to support raw addresses instead of simply address-of-variables is flexibility: it seems conceivable the caller may have a raw address from somewhere but not know which variable it points into.

SignedOrFloat defaults to 0 (unsigned), but it can be 2 for floats or 1 (or any other value) for signed integers.

PutNum() could auto-detect floating point numbers by the presence of a decimal point. However, floats are so rarely used with PutNum() that auto-truncation-to-integer might be preferable, in which case an additional parameter could be added to specify "treat this as a floating point number".

Please let me know if you have any comments on the above, or can think of any improvements to: [*:1rfd01v0]Parameter ordering.
[*:1rfd01v0]PutNum's return value (if any). Maybe it should be Address+Offset+Size so that the caller can pass it to the next call to PutNum (i.e. for adjacent fields in a struct).
[*:1rfd01v0]Default mode is "unsigned" for GetNum. Unsigned seems more common than signed?
[*:1rfd01v0]Default size of 8 (double) for floating point numbers under the assumption that 64-bit (double) is more common than 32-bit (float).Edit: Added a new poll to choose among the ones that had the most votes in the previous poll.

SKAN
  • Administrators
  • 9115 posts
  • Last active:
  • Joined: 26 Dec 2005
I have voted for GetNum / PutNum, them being shorter ( and sounds better than NumGet / NumPut ).

Thanks :)

Laszlo
  • Moderators
  • 4713 posts
  • Last active: Mar 31 2012 03:17 AM
  • Joined: 14 Feb 2005
I voted for NumGet / NumPut, because of their shortness, and also starting with Num makes them to appear next to each other in the Help Index, sorted alphabetically.

I prefer a string parameter "UInt" or "Double" (as in dllcalls) to SignedOrFloat? = 0, Size = 4. It makes the syntax consistent, easier to remember than passing a 2 in SignedOrFloat. Also, I have to remember that Short is 2 bytes, Float is 4 bytes, etc., which could be looked up in the function. These functions are almost always used in connection with dllcalls, so similar parameters make sense.

VarOrAddress is confusing. I often have an address extracted to a variable, which I cannot use directly in the proposed syntax (need some unintuitive trick, like "var+0"). If somebody uses these functions in a loop, they can assign the address to a variable, and increment it with ++, or something similar. Outside of loops the speed difference does not matter.

It looks useful, if NumPut's return value is Address+Size (no offset should be used). It simplifies code, e.g. setting up a Unicode string structure:
NumPut(NumPut(NumPut(&UString,len,Short),maxlen,Short),&Buffer,UInt)

SKAN
  • Administrators
  • 9115 posts
  • Last active:
  • Joined: 26 Dec 2005

VarOrAddress is confusing. I often have an address extracted to a variable, which I cannot use directly in the proposed syntax (need some unintuitive trick, like "var+0")


I had thought %var% would suffice :roll:

PS: I googled for GetNum PutNum : BLISS (programming language) :)

Laszlo
  • Moderators
  • 4713 posts
  • Last active: Mar 31 2012 03:17 AM
  • Joined: 14 Feb 2005
It is even more confusing. %var% is dynamic variable reference in function parameters, but here it means the variable itself.

SKAN
  • Administrators
  • 9115 posts
  • Last active:
  • Joined: 26 Dec 2005
Thinking again about the function names,
for Others I would suggest: NumIns / NumExt

Sounds good when spelt "Neumins" and "Neumext"

:)

polyethene
  • Members
  • 5519 posts
  • Last active: May 17 2015 06:39 AM
  • Joined: 26 Oct 2012
I voted NumExtract / NumInsert because it looks more professional & meaningful than Get/Put and I've become quite used to Extract/InsertInteger. SetFormat uses 6 digits of float precision by default so I think these functions should be the same. Things will be more consistent that way too.

autohotkey.com/net Site Manager

 

Contact me by email (polyethene at autohotkey.net) or message tidbit


Chris
  • Administrators
  • 10727 posts
  • Last active:
  • Joined: 02 Mar 2004

Starting with Num makes them to appear next to each other in the Help Index, sorted alphabetically.

That's a good consideration, though GetNum/PutNum seem to have superior readability and ease of memorization. Let's see how the poll turns out.

I prefer a string parameter "UInt" or "Double" (as in dllcalls) to SignedOrFloat? = 0, Size = 4. It makes the syntax consistent, easier to remember than passing a 2 in SignedOrFloat. Also, I have to remember that Short is 2 bytes, Float is 4 bytes, etc., which could be looked up in the function. These functions are almost always used in connection with dllcalls, so similar parameters make sense.

That is a good idea. It would increase code and slightly decrease performance, but the added readability and simplicity might be worth it.

VarOrAddress is confusing. I often have an address extracted to a variable, which I cannot use directly in the proposed syntax (need some unintuitive trick, like "var+0"). If somebody uses these functions in a loop, they can assign the address to a variable, and increment it with ++, or something similar. Outside of loops the speed difference does not matter.

The big problem with accepting only an address is that it will probably cause a lot of script bugs due to people passing Var+N instead of &Var+N. I can seem myself making this error frequently even after a lot of practice. But maybe it's the lesser evil.

It looks useful, if NumPut's return value is Address+Size (no offset should be used). It simplifies code, e.g. setting up a Unicode string structure:
NumPut(NumPut(NumPut(&UString,len,Short),maxlen,Short),&Buffer,UInt)

Yes, I meant that the function should return the address immediately to the right of the item just written. If an offset is present, I think it must be applied as well (but maybe you meant that offset shouldn't even exist as a parameter).

Chris
  • Administrators
  • 10727 posts
  • Last active:
  • Joined: 02 Mar 2004

SetFormat uses 6 digits of float precision by default so I think these functions should be the same. Things will be more consistent that way too.

Yes, it's planned that NumExtract() will obey SetFormat.

Sean
  • Members
  • 2462 posts
  • Last active: Feb 07 2012 04:00 AM
  • Joined: 12 Feb 2007
I voted for NumDecode/NumEncode, but, I suppose it may not be that intuitive to many users.
As a matter of fact, name doesn't matter that much to me here, anything will be fine like NumDec/NumEnc, NumExt/NumIns, etc.
IMHO, however, NumGet/NumSet is the most intuitive one (:I prefer Set over Put as it seems to accord more with APIs. I don't think I saw the usage of Put over Set much, if any, except in COM).

And, I prefer the ordering like this:

NumSet(VarOrAddress, Offset = 0, Number = 0, Size = 4)
It appears to me more symmetric with NumGet.

Sean
  • Members
  • 2462 posts
  • Last active: Feb 07 2012 04:00 AM
  • Joined: 12 Feb 2007

VarOrAddress is confusing.

Hmm, when I saw it I just assumed it meant something like this:

addr := Var + 0 > 65535 ? Var : &Var
Maybe not...

Laszlo
  • Moderators
  • 4713 posts
  • Last active: Mar 31 2012 03:17 AM
  • Joined: 14 Feb 2005
The only problem with NumGet/NumSet is that they are too similar.

Sean
  • Members
  • 2462 posts
  • Last active: Feb 07 2012 04:00 AM
  • Joined: 12 Feb 2007

The only problem with NumGet/NumSet is that they are too similar.

Yes, as a matter of fact, that's the actual reason of my preference of Set. ;)
I admit it's only my personal taste, btw.

Chris
  • Administrators
  • 10727 posts
  • Last active:
  • Joined: 02 Mar 2004

I prefer the ordering like this:

NumSet(VarOrAddress, Offset = 0, Number = 0, Size = 4)
It appears to me more symmetric with NumGet.

Yes, but since Number will hardly ever be omitted, putting it to the right of Offset would prevent omitting Offset. In addition, the parameters Size and Type will probably be merged as Laszlo suggested, so the symmetry would be broken either way. So the best compromise might be:
NumGet(Address, Offset = 0, Type = "UInt") 
NumPut(Number, Address, Offset = 0, Type = "UInt")
And if only a pure address is accepted, the Offset parameter would be removed, leaving only:
NumGet(Address, Type = "UInt") 
NumPut(Number, Address, Type = "UInt")


Sean
  • Members
  • 2462 posts
  • Last active: Feb 07 2012 04:00 AM
  • Joined: 12 Feb 2007

I prefer the ordering like this:

NumSet(VarOrAddress, Offset = 0, Number = 0, Size = 4)
It appears to me more symmetric with NumGet.

Yes, but since Number will hardly ever be omitted, putting it to the right of Offset would prevent omitting Offset. In addition, the parameters Size and Type will probably be merged as Laszlo suggested, so the symmetry would be broken either way.

Sure, however, I suppose the Type/Size parameter is mostly omitted in actual usage.

NumSet(&var, 4, 0x8000)
NumGet(&var, 4)

And if only a pure address is accepted, the Offset parameter would be removed, leaving only:

Actually I prefer this. Then:

NumSet(&var + 4, 0x8000)
NumGet(&var + 4)