Standard library

08-13-2008, 05:43 PM

There are a bunch of things that we do again and again, in almost every map. I was thinking we could get together and just put a bunch of these functions together and stop writing them again and again. It would also be useful if systems could stop implementing these and just say "requires standard lib".

Some things that should definitely be included:

Code:

H2I
always-true boolexpr
GetColoredName

Some things that would be nice to include:

Code:

floor
ceiling
round
between(a,b,c)
GetPlayerFromString

I'm sure there are plenty of others, so drop your suggestions along with your comments. Keep in mind we probably don't want full fledged systems in here. If people really want this, maybe we can convince vex to include it in newgen.

JASS:

/// still not run through a compiler, probably has silly errors
library STL initializer init
    globals
        boolexpr NO_FILTER = null
        
        private string array colors
        private constant integer COLORS_SIZE = 4
    endglobals
    private function initColor takes integer index, string clr, string name1, string name2, string name3 returns nothing
        set index = index*COLORS_SIZE
        set colors[index+0] = clr
        set colors[index+1] = name1
        set colors[index+2] = name2
        set colors[index+3] = name3
    endfunction
    private function initArrays takes nothing returns nothing
        call initColor(0, "FF0303", "red", null, null)
        call initColor(1, "0042FF", "blue", null, null)
        call initColor(2, "1CB619", "teal", null, null)
        call initColor(3, "540081", "purple", null, null)
        call initColor(4, "FFFF01", "yellow", null, null)
        call initColor(5, "FE8A0E", "orange", null, null)
        call initColor(6, "20C000", "green", null, null)
        call initColor(7, "E55BB0", "pink", null, null)
        call initColor(8, "959697", "gray", "grey", null)
        call initColor(9, "7EBFF1", "lightblue", "light blue", "lb")
        call initColor(10, "106246", "darkgreen", "dark green", "dg")
        call initColor(11, "4E2A04", "brown", null, null)
    endfunction
    
    ///=== Handles
    function H2I takes handle h returns integer
        return h
        return 0
    endfunction

    ///=== Players
    function GetColoredName takes player p returns string
        local string s = null
        local integer i = GetPlayerId(p)
        if p != null then
            set s = colors[i*COLORS_SIZE]
            if s == null then
                set s = "FFFFFF" //white
            endif
            set s = "|cFF" + s + GetPlayerName(p) + "|r"
        endif
        return s
    endfunction
    function GetPlayerFromString takes string s returns player
        local integer i
        local integer j
        set s = StringCase(s, false)
        
        //check against color names
        set i = 0
        loop
            exitwhen i >= 12
            set j = 1
            loop
                exitwhen j >= COLORS_SIZE
                if s == colors[i*COLORS_SIZE+j] then
                    return Player(i)
                endif
                set j = j + 1
            endloop
            set i = i + 1
        endloop
        
        //check against indexes
        set i = 0
        loop
            exitwhen i >= 12
            if s == I2S(i+1) then
                return Player(i)
            endif
            set i = i + 1
        endloop
        
        //check against names
        set i = 0
        loop
            exitwhen i >= 12
            if s == GetPlayerName(Player(i)) then
                return Player(i)
            endif
            set i = i + 1
        endloop
        
        //no matches found
        return null
    endfunction

    ///=== Rounding
    function Floor takes real r returns integer
        if r >= 0 then
            return R2I(r)
        else
            return -R2I(-r)
        endif
    endfunction
    function Ceiling takes real r returns integer
        if r <= 0 then
            return R2I(r)
        else
            return -R2I(-r)
        endif
    endfunction
    function Round takes real r returns integer
        if r >= 0 then
            return R2I(r+0.5)
        else
            return -R2I(-r+0.5)
        endif
    endfunction
    
    ///=== Bounding
    function BetweenR takes real r1, real r2, real r3 returns real
        //recursive sort
        if r1 > r2 then
            return betweenR(r2,r1, r3)
        elseif r2 > r3 then
            return betweenR(r1, r3,r2)
        endif
        //median
        return r2
    endfunction
    function BetweenI takes integer i1, integer i2, integer i3 returns integer
        //recursive sort
        if i1 > i2 then
            return betweenR(i2,i1, i3)
        elseif i2 > i3 then
            return betweenR(i1, i3,i2)
        endif
        //median
        return i2
    endfunction
    
    private function truth takes nothing returns boolean
        return true
    endfunction
    private function init takes nothing returns nothing
        call initArrays()
        set NO_FILTER = Condition(function truth)
    endfunction
endlibrary

08-13-2008, 05:48 PM

Troll-Brain

Here is mine :

JASS:

library CommonFunctions initializer init

    globals
        boolexpr B_TRUE
    endglobals
    
    function H2I takes handle h returns integer
        return h
        return 0
    endfunction
    
    function B2S takes boolean b returns string
        if b then
            return "true"
        endif
        return "false"
    endfunction
    
    function R32 takes real r returns real // for the cells
        return 32.0*R2I(r/32.0)
    endfunction
    
    private function FuncTrue takes nothing returns boolean
        return true
    endfunction

    public function init takes nothing returns nothing
        set B_TRUE= Condition(function FuncTrue)
    endfunction
    
endlibrary

08-13-2008, 06:34 PM	#3
Strilanc	That R32 one is pretty common, but it's not always 32. Maybe floorEx? JASS: function floorEx takes real r, real p returns real return floor(r/p)*p endfunction

08-13-2008, 06:51 PM	#4
Troll-Brain	As i said it's just for a function using a cell ... Ofc we can discuss about his utility, i've, maybe you wont never us it. That's why i didn't post the other functions i have.

08-13-2008, 07:37 PM	#5
Blubb-Tec	I'm using Vex' ARGB together with this function: JASS: function GetPlayerNameColored takes player p returns string return ARGB.fromPlayer(p).str(GetPlayerName(p)) endfunction ARGB should get standard anyway, its pretty damn useful and fits for every situation in which you need colors.

08-13-2008, 07:51 PM

Anitarf

Some of these functions are easily implemented into systems as private functions, you can't seriously argue that H2I makes an average system appear bloated, an average system can do that quite fine on it's own; besides, you usualy need H2I only in storage systems so if your code needs H2I this means you're likely trying to embed a storage system into it instead of using an external one like normal people, if that's the case I don't think a standard library would help you not write ugly code.

Other functions are large enough to be their own libraries, I'm sure we already have some sort of an implementation of IsPointInTriangle out there somewhere, then there's ARGB as Blubb-Tec mentioned. If we put all these into one library we'd get precisely the kind of mess you want to avoid. Consider for a moment the caster-system effect. Many people didn't want to use it because they didn't want to import a huge bloated monstrosity just to use one small part of it's functionality. I don't see a standard library like you propose meeting any different fate.

08-13-2008, 07:56 PM	#7
TheDamien	As far as I can tell from the jasshelper manual, typecasting syntax for native types will be added in future versions.

08-13-2008, 08:23 PM

Strilanc

Quote:

Originally Posted by Anitarf

Maybe I shouldn't have mentioned systems, because that is not the main target here. I want a library of very commonly used, and useful, functions. I agree that we need to be careful not to include every function that seems useful (eg. Floor with a period argument). But I think we can make a good, useful library without being bloated.

I think GetColoredName is the perfect example of a function that should be standard. Every map should be using colored names when displaying player names, and most maps display player names at some point.

GetPlayerFromString is a different story. It's main use is for parsing commands (boot which player? ally with which player? etc), so maybe it belongs in a parsing library instead of here. I think it belongs here, but that doesn't mean I'll ignore you if you say it shouldn't.

Then there's the trivial 2-3 line functions, like floor and ceiling. The types of functions that should be in blizzard.j. There really aren't that many of these, but once again you need to weigh usage (eg. Floor probably belongs, FloorEx probably doesn't).

Deciding what goes in and what doesn't is difficult. That doesn't mean the library won't be useful. I think the main criteria for inclusion should be what percentage of maps would use the function, and the size of the function. Common is good, and small is good. For example I don't think IsPointInTriangle belongs here, because it isn't common enough.

Don't you have a personal 'common' library? What functions from it do you find yourself constantly using?

Quote:

Originally Posted by TheDamien

As far as I can tell from the jasshelper manual, typecasting syntax for native types will be added in future versions.

Do you mean H2I, I2Item, etc? (hurray!)
None of the other listed functions could really be called 'type casts'.

08-14-2008, 01:54 AM

Ammorth

Well we already have color-based libraries and we already have storage libraries. If you want, you can assemble a math library that most maps could use.

The idea about libraries was that you can have multiple systems running off other libraries and condensing the code by splitting larger systems into components (so users can only take what they need) and allowing many systems to use the same basic functions.

Creating one major library feels like a step back from something that vJass has pushed for.

08-14-2008, 02:20 AM

#10

Anitarf

Quote:

Originally Posted by Strilanc

Don't you have a personal 'common' library?

Not really, no. You haven't posted particularly many examples yourself. We already have a GetColoredName equivalent in ARGB, GetPlayerFromString isn't a particularly convincing example because I think chat game commands are an abomination, Floor and Ceiling I have never used in my life while Round can be simplified to R2I(r+0.5) and just inlined everywhere. I already explained why nobody in their right mind should be needing H2I or I2H anymore, and that's all of the examples you gave in your reply.

08-14-2008, 03:03 AM

#11

Strilanc

Quote:

Originally Posted by Anitarf

That formula for round won't work, because R2I doesn't floor, it truncates.
Round(-1.9) = -2
R2I(-1.9 + 0.5) = R2I(-1.4) = -1

I'm suggesting taking the common functions out of libraries like ARGB, not taking the uncommon ones (like extracting the red value) and putting that all together in one library. You know, so you don't have to include 20 systems with super simple functionality.

Wait... is there a way to import a library into a map when it's compiled?

08-14-2008, 03:27 AM

#12

Vexorian

STL stands for Standard Template Library.

I think common libraries were very good back in the time of the custom script section.

H2I? Well, a good map should only have one system that uses this function ,it would be ok for it to be there, we could make a whole library H2I but I doubt anyone would use it. If we add other functions to it and call it a common library, people would not feel like using the whole common library just for H2I. The same happens with player name colored and stuff like that, people would not want to include a whole standard library just to use one function from there that is full of unrelated stuff.

Standards never worked in this world of Jass. The best thing we ever achieved was H2I becoming the name for that function.

08-14-2008, 03:59 AM	#13
Strilanc	Well we do have other standards, like newgen. I guess it really comes down to: how many functions actually deserve to get in? Thinking about it more, I'm not sure I can justify a library for so few functions.

08-14-2008, 04:18 AM	#14
Blubb-Tec	Also remembering the WEU, it also had kind of a "standard" library, which was/is still used although it was/is extremely outdated, simply because there were things in it that people wanted. I fear that might happen aswell with this one..