Union

Forum for discussion about the documentation project.
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Union

Post by sancho3 »

Lets look at the Union help page.
In particular the example set.
First we have an example that sets bit fields. Nowhere on that page are bit fields talked about or explained.
The bitfields are talked about in the type page linked at the bottom, but a user has no indication that is where it is talked about.
So the user goes and searches "bitfield" and is presented with 5 links and only the very last one talks about them.
Ironically, the Type page that explains bitfields has an example of a Union using bitfields.
That is the very first example.
Wouldn't it make more sense that, instead of introducing something that must be researched on another page, the first example be the simplest form of a union you can present?

The second example presents a named union:

Code: Select all

Union AUnion
    a As UByte
    b As Integer
End Union
Literally the only other code related to that union demonstrates absolutely nothing about a union:

Code: Select all

Dim MyUnion As AUnion
...
' Can only set one value in union.
MyUnion.a = 128
...
Print "Union: ";MyUnion.a
" Can only set one value in union." What does that mean? The code certainly isn't showing me what this means. If in this code we exchanged Type for Union, we would get the exact same result.
What is this an example of? I think this bit of code should be either removed or fleshed out to the point where it is actually demonstrating something.

I really think this page needs an overhaul.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

At first:
KeyPgUnion → fxm [Added a first simple example]

At a given moment, it is relevant to set the value of only one data field in a Union block because all data fields share the same memory space (modify one data field impacts the other data fields value).
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Re: Union

Post by sancho3 »

Ok Example 0 is good.
Example 2 is now proven to be terrible.
How you describe it now is what proves it.
In the code comment the text says:
"Can only..."
That is completely different to:
"Its only relevant to..."
This example still demonstrates nothing and worse it probably confuses the issue.
If they understand example 0 they already know that setting both union members in the example is incorrect usage in most cases.
Certainly the example could be fleshed out to show why its useless to set both members to a value but it seems to me to be more reasonable just to turf it all together.
I would also copy the description of bit fields from Type to Union as well. That remains a hard description to find in the help files.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

KeyPgUnion → fxm [Just cleaned up examples 1 and 2]
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Re: Union

Post by sancho3 »

I am perplexed by this most recent edit.

Code: Select all

' One field set a priori.

Did you mean 'priority''? Are we really saving anything by not finishing 2 letters in the spelling?

In any case how about examples that break that rule?
I see no reason not to set multiple union members at the same time in the following example:

Code: Select all

Type ColorType 
	Union 
		As Ulong value 
		Type 
			blue As uByte 
			green As uByte 
			red As ubyte 
			a As Ubyte 
		End Type 
	End Union 
End Type

Dim As ColorType c1
dim As Ulong c2
c2 = Rgba(100, 40, 92, 255) 
c1.blue = 92 
c1.red = 100
c1.green = 40 
c1.a = 255
?c1.value, c2
sleep
How about using a union as a flag-setting system? I think this is a valid method of setting multiple flags.

Code: Select all

Type MyType 
	As integer x
	Union 
		flags As Ulong 
		Type 
			flagA As Ubyte 
			flagB As Ubyte 
			flagC As Ubyte 
			flagD As UByte
		End Type 
	End Union 
End Type

I realize this seems like stubbornness from me. Let me explain that I already knew what Unions where when I clicked on the help. I wasn't overly confident because I don't use them often/enough.
That page did nothing to help me understand them and left me confused.
Example 0 is going to help the next guy. If he stops reading there he should be alright. But if he checks out example 1, he, like me, will not know what a bit field is. That is the basis for confusion; not understanding.

And if he keeps reading example 2 will just throw him for a loop as he tries to figure out what is meant by that. Is it fair to say that example is actually even showing him something that is incorrect? To an extent, I think it is. Look at my previous two examples that break the priority suggestion/rule. I see that it is not exactly breaking the rule since the nested type is treating the ubytes as one member of the union but I think the point still stands.

This isn't a case where a beginner is asking for all the bases to be covered in the help file. In this case I am suggesting that misleading information (example 2) be removed and that the missing bit field information be supplied on that page as well. The latter since you can't even directly find that info via search.

At the very least un-perplex me and put the 'ty' in 'priority'. lol
Josep Roca
Posts: 564
Joined: Sep 27, 2016 18:20
Location: Valencia, Spain

Re: Union

Post by Josep Roca »

> At the very least un-perplex me and put the 'ty' in 'priority'. lol

This change will perplex the rest of us. I think that it is correct as is. "One field set a priority" doesn't make any sense in this context and also doesn't look as good English.

> I see no reason not to set multiple union members at the same time in the following example:

That union has not five members, as you seem to think, but two members: An Ulong value and an structure. You can set values to multiple members of the structure, but not of the union, because if after c1.blue = 92, c1.red = 100, c1.green = 40, you set a value to the other member of the union, value , the values that you have previously set will change.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

"a priori" is a Latin phrase much used in French, but perhaps not in English?
I could replace here the sentence by "One field is set without choice criterion".

In your first example, the Union block has only two elements: value and the unnamed Type (same remark for your second example). You only set the unnamed type.

I will see what I can do for examples 1 and 2!
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

fxm wrote:"a priori" is a Latin phrase much used in French, but perhaps not in English?
I could replace here the sentence by "One field is set without choice criterion".
@Josep Roca,
Now, what is your feeling about example 2?
(example 1 could be simply deleted, because example 0 is sufficient)
Josep Roca
Posts: 564
Joined: Sep 27, 2016 18:20
Location: Valencia, Spain

Re: Union

Post by Josep Roca »

"A priori" is also much used in Spanish (at least in Spain). Not suprisingly, since both French and Spanish come from Latin. In English you can use "beforehand". The OP is confusing "a priori" with priority and, after that, the nonsense begins...

> Now, what is your feeling about example 2?

It is perfectly understandable to someone that really knows what is an union, but it may be difficult to grasp to somebody that does not. I mean that it is a good example to show one of the things that you can do with an structure that includes an union, but not so good to help a beginner to understand what is an union. However, not eberybody is a beginner, so I will keep it and add before it something more easy to understand.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

Okay.
I will try to replace example 1 with an intermediate level example.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

KeyPgUnion → fxm [Changed example 1]
Josep Roca
Posts: 564
Joined: Sep 27, 2016 18:20
Location: Valencia, Spain

Re: Union

Post by Josep Roca »

An example that I think it is easy to understand:

Code: Select all

UNION BGRA_UNION
   color AS COLORREF
   TYPE
      blue  AS UBYTE
      green AS UBYTE
      red   AS UBYTE
      alpha AS UBYTE
   END TYPE
END UNION

DIM ubgra AS BGRA_UNION

' Setting the individual color values...
ubgra.red = &h33
ubgra.green = &hcc
ubgra.blue = &h66
' We can get a COLORREF value
print HEX(ubgra.color)

' Setting a COLORREF value...
ubgra.color = &h33cc66
' We can get the individual color values
print HEX(ubgra.red)
print HEX(ubgra.green)
print HEX(ubgra.blue)
If you want to work with ARGB colors, then you can use:

Code: Select all

UNION ARGB_UNION
   color AS COLORREF
   TYPE
      alpha AS UBYTE
      red   AS UBYTE
      green AS UBYTE
      blue  AS UBYTE
   END TYPE
END UNION
It is n alternate way to functions like MakeARGBColor, GetRValue, GetGValue and GetBValue.
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Union

Post by MrSwiss »

Josep Roca wrote:

Code: Select all

UNION ARGB_UNION
   color AS COLORREF
   TYPE
      alpha AS UBYTE
      red   AS UBYTE
      green AS UBYTE
      blue  AS UBYTE
   END TYPE
END UNION
COLORREF isn't a FB defined data-type, must be replaced with: ULong ...

Then, the UByte's are "top to bottom":
  • Blue (lsb)
    Green
    Red
    Alpha (msb)

Code: Select all

'' for little endian systems (big endian differs)
Union Color_u
    As ULong    clr     '' color
    Type
        As UByte b      '' blue
        As UByte g      '' green
        As UByte r      '' red
        As UByte a      '' alpha
    End Type
End Union
Last edited by MrSwiss on Sep 29, 2018 13:25, edited 1 time in total.
fxm
Moderator
Posts: 12083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Union

Post by fxm »

@Josep Roca,
I just modified your first example a bit by "coloring" it more FreeBASIC:
KeyPgUnion → fxm [Added one example]
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Union

Post by MrSwiss »

Using "keyword" Color in the Union, is a bad idea ...

Alternative (BE): Colour
Post Reply