quakeforge/doc/config/gib/list.gib

//      list.gib
//
//      "list" routines for GIB in QuakeForge 0.5.1
//
//      Copyright (C) 2002  Brian Koropoff
//
//	This library is free software; you can redistribute it and/or
//	modify it under the terms of the GNU Lesser General Public
//	License as published by the Free Software Foundation; either
//	version 2.1 of the License, or (at your option) any later version.
//
//	This library is distributed in the hope that it will be useful,
//	but WITHOUT ANY WARRANTY; without even the implied warranty of
//	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
//	Lesser General Public License for more details.
//
//	You should have received a copy of the GNU Lesser General Public
//	License along with this library; if not, write to the Free Software
//	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

// Hash-like functions

// Note: at first I thought using a bunch of cvars to
// hold lists was stupid, but then I realized that
// hashes are used for it internally anyway.  The only
// problem is that everything is in one namespace, increasing
// the number of collisions.  The hash size for cvars should
// probably be increased for this purpose

// ***************************************************************
// list_set
//	Sets the value of an element of a list with a certain key.
//	Usage: list_set list_name key value
//	Returns: Nothing.
// ***************************************************************

alias list_set {
	set qlist_${1}_${2} $3
}

// **********************************************************
// list_get
//	Fetches the value of an element of a list by its key.
//	Usage: list_get list_name key
//	Returns: the value of the element
// **********************************************************

alias list_get {
	return ${qlist_${1}_${2}}
}

// Array-like functions

// **********************************************************
// list_reset
//	Resets a list to zero-size (does not delete elements)
// **********************************************************

alias list_reset {
	set qlist_${1}_size 0;
}

// *****************************************************
// list_add
//	Adds an element to the end of an array-like list
// *****************************************************

alias list_add { // Drop something into the end of a list
	ifnot ${qlist_${1}_size} { // Make sure _size exists and has a numeric value
		set qlist_${1}_size 0
	}
	set qlist_${1}_size #{${qlist_${1}_size}+1}; // Increment size
	set qlist_${1}_${qlist_${1}_size} $2; // Set value
}

// *********************************************************
// list_remove
// 	Removes an element from an array-like list and moves
//	all elements after it down one.
//      FIXME:  Add list_insert and figure out some way
//	to delete old elements (cvar_delete?)
// *********************************************************

alias list_remove { // Remove something from a numbered list
	if #{~{list_get $1 size}==0} return;
	for {i = $2; #{$i<${qlist_${1}_size}}; i = #{$i+1}} {
		list_set $1 $i ~{list_get $1 #{$i+1}};
	};
	list_set $1 size #{~{list_get $1 size}-1};
}

// ****************************************************************
// list_find
//	Locates either the first element of a list that matches
//	a string or the first element starting at a specific index.
// ****************************************************************

alias list_find { // Returns the index of a string in a list
	ifnot ${qlist_${1}_size} {
		return 0;
	}
	// This is an evil for statement.  You have been warned.
	for {if #{$argn > 3} {i = $2} else {i = 1}; #{$i<=~{list_get $1 size}}; i = #{$i+1}} {
		if ~{streq $2 ~{list_get $1 $i}} {
			return $i;
		};
	};
	return 0;
}

// ************************************************************
// list_grab
//	Chooses and returns a random element from an array-like
//	list.  Fun, but not that useful.
// ************************************************************

alias list_grab { // Get a random element
	ifnot ${qlist_${1}_size} {
		return 0;
	}
	number = ~{randint 1 ~{list_get $1 size}};
	return ~{list_get $1 $number};
}