[vJass].allocate()

[~GaLs~]

What is .allocate()?
How do we use it?

 

[Uberplayer]

It's explained in JassHelper manual, under Static methods.

 

[~GaLs~]

Well, if I do understand that manual, I dont need to get help here.
If everyone understands JASS, there is no need for all those Tutorial around.

 

[Uberplayer]

Then, maybe, you could tell us what part of the explanation you don't understand. It's pretty damn fine English, if we don't count few typos.

 

[~GaLs~]

Why we are using .allocate() instead of .create()?

I saw something in TH, Hive and Wc3c.

• ".allocate() is private, it should always in a struct"
• ".allocate() gets a uniqed id for the struct"
• "If the JassHelper processor detects none of these method being created, it will automatically create 1, refering to which method you using"
• ".allocate() should always used inside a struct, but you may use it outside a struct too"

 

[Rheias]

From my understanding (I haveyet to use advanced structs) .allocate gives the struct his special ID, kind of like .create. However, you can replace .create with other method, so you'll need to use allocate. For example

struct r
    static method create takes nothing returns r
        return r.allocate()
    endmethod
endstruct

I'm pretty sure I'm wrong, so don't count on me. Maybe Überplayer would be kind enough to share his knowledge.

 

[Uberplayer]

This might be wrong or totally wrong, and of course, this has a chance to be correct. I quote jass helper in this few times.

Things that I have to say before anything else is:
-structure is an integer
-think method as a function, which can take and return values

Example code:

struct ourStruct
    static method create takes nothing returns ourStruct
        local ourStruct data = ourStruct.allocate()
        return ourStruct
    endmethod
endstruct

function createNewStructure takes nothing returns nothing
    local ourStruct data = ourStruct.create()
endfunction

When a struct does not have an specific create method declared, jasshelper will use allocate directly when .create is called.

Now that doesn't happen as we have a new create method inside our structure, so we have to create the structure by ourselves (not fully of course). .allocate() method creates us a unique INTEGER, which nothing else uses.

So basically, when we create a structure which contains static method create, .create() calls the method like a function. And that method returns us our structure.

This is quite unfinished.. As I'm gonna eat .. you should ask.

 

[TheDamien]

.allocate does basically the same thing as .create, and is useful if you want to define a custom create method for a struct.

 

[Rheias]

Oh so it seems like I wasn't wrong.

static method create takes nothing returns r
    return r.allocate()
endmethod

Can we do that? Or we must do:

static method create takes nothing returns r
    local r returned = r.allocate()
    return returned
endmethod

 

[Uberplayer]

Both are fine.

 

[Vexorian]

When you are using a "normal" struct withot a custom create method you call baba.create() this generates a unique id (if available) that you can use.

But then people wanted to customize create, by adding arguments or maybe just initializing values that can't be initialized that easily by = in member declarations, you could even customize it to the extend of not using vJass' usual allocation ways...

When people want to customize .create we run into a problem, since you need to ask vJass to generate a unique id for you, but you can't just call create() as usual because you are redefining it.

So, the solution was to add allocate() to the language, allocate() is just what a normal create() does, only that you cannot override it, it is also private which means you cannot use it outside an struct's methods.

 

[~GaLs~]

We cant define allocate as a method in struct...too?

 

[Doomhammer]

See structs as what they are after the preprocessor pass: global arrays connected by an integer. To make those arrays work, some sort of controller has been implemented: this makes sure that the arrays are initialized and connected correctly, and that you get a message on overflow
Ok, so let's look at an example of a simple allocator: that's my wrapper struct ) for the DestroyEffectTimed function after preprocessing:

globals //pasted to show struct-generated globals
    integer si__tfx_F=0
    integer si__tfx_I=0
    integer array si__tfx_V
    effect array s__tfx_fx
endglobals

//Generated allocator of tfx
function s__tfx__allocate takes nothing returns integer
 local integer this=si__tfx_F
    if (this!=0) then
        set si__tfx_F=si__tfx_V[this]
    else
        set si__tfx_I=si__tfx_I+1
        set this=si__tfx_I
    endif
    if (this>8190) then
        call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,1000.,"Unable to allocate id for an object of type: tfx")
        return 0
    endif

    set si__tfx_V[this]=-1
 return this
endfunction

After this little procedure, it returns your struct, i.e. your unique struct id. this is your struct, get it now? Same principle, complementary procedure: what happens to structname.destroy() ?

//Generated destructor of tfx
function sc__tfx_destroy takes integer this returns nothing
    if this==null then
            call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,1000.,"Attempt to destroy a null struct of type: tfx")
        return
    elseif (si__tfx_V[this]!=-1) then
            call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,1000.,"Double free of type: tfx")
        return
    endif
    set f__arg_this=this
    call TriggerEvaluate(st__tfx_onDestroy)
    set si__tfx_V[this]=si__tfx_F
    set si__tfx_F=this
endfunction

 

[Uberplayer]

You cannot override it

That's what he said. And what would you even do with it x)

What would happen if the structure had same id?

globals
    ourStruct array ourStruct_ar
    integer totalStructs = 0
endglobals

struct ourStruct
    string value
    static method create takes nothing returns ourStruct
        return ourStruct.allocate()
    endmethod
endstruct

function createNewStructure takes nothing returns nothing
    local ourStruct data = ourStruct.create()
    local integer index = 0
    set data.value = "Value of this struct is: "+I2S(GetRandomInt(0, 999))
    set ourStruct_ar[totalStructs] = data
    set totalStructs = totalStructs + 1
    loop
        exitwhen (index == totalStructs)
        set ourStruct_ar[index] = 0
        set index = index + 1 
    endloop
    set index = 0
    loop
        exitwhen (index == totalStructs)
        call BJDebugMsg(data.value)
        set index = index + 1 
    endloop
endfunction

I wrote that as fast as I could, and what it does.. is what you see in the code. It makes every structure exactly same

 

[SFilip]

What's the point of overloading create if you're only going to return allocate()?
Actually what's the point of ourStruct_ar? You first set it and then revert to 0. Structs are pointers so it doesn't matter what you do with variables that hold them.

> We cant define allocate as a method in struct...too?
No, why would you ever need that?

 

[~GaLs~]

>>No, why would you ever need that?
Nope, just asking

Conclusion
.allocate() is as same as .create().
Might use any of these 2 when create method is not customly defined.
When create method is defined, it'll need .allocate() to replace it when doing local StructName Namez = StructName.create().

Thats it.

Correct me if I am wrong. I do doubt my explaination

 

[Uberplayer]

>No, why would you ever need that?
I answered the exact same thing. Yeah, and that my example was just a test.. Nothing.. just forget it

>.allocate() is as same as .create().
Not exactly.. You are able to override ".create()", but not ".allocate()". They work differently. ".create()" just automatically does ".allocate()", if you don't have your own static method create inside the struct, if you do have, then you need to do the allocating yourself.

 

[~GaLs~]

>>Not exactly.. You are able to override ".create()", but not ".allocate()". They work differently. ".create()" just automatically does ".allocate()", if you don't have your own static method create inside the struct, if you do have, then you need to do the allocating yourself.
What i mean same is its function, what it does. (Creating a struct)

 

[Uberplayer]

.create() automatically calls .allocate(), if you don't use your own static method create. That's basically the answer to you question.

And also, when we say creates a structure.. well..