Module stash 

GridCraft data kept in hidden workbook-scope defined names, so that it travels inside the xlsx file.

An item key is stored as names _gc_<key>_0, _gc_<key>_1, …, each a formula of string literals joined with &: "…"&"…". Excel limits a string literal to 255 characters and a formula to 8,192, so a long value is split over as many names as it needs and the file stays one that Excel accepts. Older items (custom views, scripts, the watch list and scenarios) keep one name each, _sc_<key>; reading accepts that form as well, so those items can move to this format later, and a write of the same key replaces it.

XML can’t carry every character (controls other than tab, line feed and carriage return, and U+FFFE and U+FFFF), and the xlsx writer drops those. In _gc_ items each of them, and the marker itself, is written as ESCAPE followed by its code as four upper-case hex digits (U+0001 becomes \u{FDD0}0001), and reading turns them back. The marker is a Unicode noncharacter, which XML carries but real text does not use, so the escape costs nothing on ordinary text. Legacy _sc_ items are read as they are.

Structs

Listing

What a listing found: the first MAX_ITEMS items or keys, and how many more there were.

Constants

ESCAPE

Starts an escaped character in a _gc_ item: U+FDD0, a noncharacter.

MAX_ITEMS

The most items items and keys return: the first this many keys in sorted order. A file can carry any number of hidden names; the rest are not listed.

MAX_ITEM_CHARS

The longest item: 4,194,304 characters.

Functions

chunk_formulas

text as name formulas: string literals of at most 255 characters joined with &, each formula at most 8,192 characters, with the characters XML can’t carry escaped (see ESCAPE). Concatenating string_literals of each and turning the escapes back gives text back.

get

The item text stored under key, or None when there is none (or it is over the size limit).

get_json

The item under key as JSON (None when missing or not JSON).

holds_item

Whether the workbook holds an item under name (compared without case): a hidden workbook-scope _gc_<key>_<k> name, or a workbook-scope legacy _sc_<key> name, which is read whether or not it is hidden. A visible _gc_ name is the person’s own.

item_key

The item a hidden name belongs to, lower-cased: _gc_<key>_<k> and _sc_<key> give <key>.

items

The items whose key starts with prefix ("macro_"), by lower-cased key, read in one pass over the names: the first MAX_ITEMS items that can be read, and the count of the readable ones past them. An item over the size limit is neither listed nor counted, so it takes no place another item could have. (keys lists keys without reading the items.)

keys

The keys of the items stored in the workbook that start with prefix ("macro_"), sorted and lower-cased: the first MAX_ITEMS of them. To read them all, items takes one pass where a get per key would take one each.

remove

Removes the item stored under key.

set

Stores text under key, replacing what was there (in either format). Empty text removes it.

set_json

set_many

Stores every (key, text) of items as set would, with the checks done before anything changes and one pass over the names for all of them, so writing a thousand items into a workbook with many thousands of names stays near-linear.

string_literals

Concatenates the string literals of a "a"&"b""c" formula (anything outside them is ignored).