resetTablePicks: Difference between revisions

Revision as of 18:14, 9 August 2020

resetTablePicks() Function

Note: This function can only be used in a Trusted Macro

• Introduced in version 1.6.0

Resets the entries in a table that have been picked. The individual entries in a Pick Once table can only be randomly chosen once until the table is reset with this function. This can be used to simulate a deck of cards where a card picked is no longer available for future picks until the deck is re-shuffled. Note: When specifying specific entries to be reset, it is important to note that Pick Once tables behave a bit differently than regular tables. In particular, entries are identified and selected by list index (starting at 0), and do not take configured ranges into account. See examples for details.

Usage

resetTablePicks(tableName)

Options Coming in 1.8

resetTablePicks(tableName, entriesToReset)
resetTablePicks(tableName, entriesToReset, delim)
resetTablePicks(tableName, entriesToReset, "json")

Parameters

tableName - A string containing the name of the Table.
entriesToReset - Coming in 1.8. Identifies specific entries to be reset. Can be a String List using the provided delim (defaults to "," if no delim provided), or a JSON Array if delim is "json".
delim - Coming in 1.8. Custom delimiter for the `entriesToReset` param. Defaults to ",". Should be "json" if entriesToReset is a JSON Array instead of a String List.

Examples

[r:resetTablePicks("Poker Deck")]

Result: Table is reset so that all entries are available to be chosen again.

Changes Coming in 1.8

Consider this excerpt from the beginning of the "Standard" Default Table (containing 52 playing card images):

Default Table "Standard"
1	Ace of Clubs
2	Two of Clubs
3	Three of Clubs
...

If this table is set to Pick Once, then the Ace and Two of Clubs can be reset with any of:

[h:resetTablePicks("Standard", "0,1")]
[h:resetTablePicks("Standard", "0@1", "@")]
[h:resetTablePicks("Standard", json.append("", 0, 1), "json")]

Note that entries on Pick Once tables are identified by list index (starting at 0), and not by range as in normal tables. Take care to properly identify entries when resetting. For more info, see Introduction to Tables and the table() function.

Version Changes

1.8 - Added optional params to reset only specific entries

@@ Line 4: / Line 4: @@
 |trusted=true
 |description=
-Resets the entries in a table that have been picked.  The individual entries in a ''Pick Once'' table can only be randomly chosen once until the table is reset with this function.  This can be used to simulate a deck of cards where a card picked is no longer available for future picks until the deck is re-shuffled.
+Resets the entries in a table that have been picked.  The individual entries in a ''Pick Once'' table can only be randomly chosen once until the table is reset with this function.  This can be used to simulate a deck of cards where a card picked is no longer available for future picks until the deck is re-shuffled. '''Note:''' When specifying specific entries to be reset, it is important to note that ''Pick Once'' tables behave a bit differently than regular tables.  In particular, entries are identified and selected by list index (starting at 0), and do not take configured ranges into account.  See examples for details.
 |usage=
 <source lang="mtmacro" line>
 resetTablePicks(tableName)
+</source>
+==== Options Coming in 1.8 ====
+<source lang="mtmacro" line>
+resetTablePicks(tableName, entriesToReset)
+resetTablePicks(tableName, entriesToReset, delim)
+resetTablePicks(tableName, entriesToReset, "json")
 </source>
 '''Parameters'''
 {{param|tableName|A string containing the name of the Table.}}
+{{param|entriesToReset|'''Coming in 1.8'''.  Identifies specific entries to be reset.  Can be a [[String List]] using the provided delim (defaults to {{code|","}} if no delim provided), or a [[JSON Array]] if delim is {{code|"json"}}.}}
+{{param|delim|'''Coming in 1.8'''.  Custom delimiter for the `entriesToReset` param.  Defaults to {{code|","}}.  Should be {{code|"json"}} if entriesToReset is a [[JSON Array]] instead of a [[String List]].}}
 |examples=
 <source lang="mtmacro" line>
@@ Line 16: / Line 24: @@
 </source>
 '''Result:''' Table is reset so that all entries are available to be chosen again.
+==== Changes Coming in 1.8 ====
+Consider this excerpt from the beginning of the "Standard" Default Table (containing 52 playing card images):
+{{{!}} class="wikitable"
+!colspan="2"{{!}}Default Table "Standard"
+{{!}}-
+{{!}}1
+{{!}}Ace of Clubs
+{{!}}-
+{{!}}2
+{{!}}Two of Clubs
+{{!}}-
+{{!}}3
+{{!}}Three of Clubs
+{{!}}-
+{{!}}colspan="2" style="text-align:center"{{!}}...
+{{!}}}
+If this table is set to ''Pick Once'', then the Ace and Two of Clubs can be reset with any of:
+<source lang="mtmacro" line>
+[h:resetTablePicks("Standard", "0,1")]
+[h:resetTablePicks("Standard", "0@1", "@")]
+[h:resetTablePicks("Standard", json.append("", 0, 1), "json")]
+</source>
+'''Note''' that entries on ''Pick Once'' tables are identified by list index (starting at 0), and ''not'' by range as in normal tables.  Take care to properly identify entries when resetting.  For more info, see [[Introduction to Tables#Pick Once Tables|Introduction to Tables]] and the {{func|table}} function.
 |also=
 {{func|getTablePicksLeft}} {{func|setTablePickOnce}}
+|changes=
+* '''1.8''' - Added optional params to reset only specific entries
 }}
 [[Category:Table Function]]