save.h File Reference

Utilities for querying and manipulating save file data. More...

Go to the source code of this file.

Functions
int32_t	AERSaveGetCurrentSlot (void)
	Query the index of the currently active save slot. More...
size_t	AERSaveGetKeys (size_t bufSize, const char **keyBuf)
	Query the keys of all values in the save file (belonging to the calling mod). More...
void	AERSaveDestroy (const char *key)
	Erase a value from the save file. More...
double	AERSaveGetDouble (const char *key)
	Query a double value from the save file. More...
void	AERSaveSetDouble (const char *key, double value)
	Set a double value in the save file. More...
const char *	AERSaveGetString (const char *key)
	Query a string value from the save file. More...
void	AERSaveSetString (const char *key, const char *value)
	Set a string value in the save file. More...

Detailed Description

Utilities for querying and manipulating save file data.

Save Key Namespacing

Each mod is given its own, unique namespace within the save file. That means two or more mods can use the same key without interfering with each other. That also means it is not possible to query/manipulate vanilla keys or the keys of other mods.

Note

The functions in this module automatically apply to the current save slot.

Since

1.2.0

Copyright

2021 the libaermre authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Function Documentation

AERSaveDestroy()

void AERSaveDestroy

(

const char *

key

)

Erase a value from the save file.

For information about key namespacing see Save Key Namespacing.

Note

Changes will take effect at next save point.

Parameters

[in]

key

Save key.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument key is NULL.
AER_FAILED_LOOKUP	if argument key is an invalid save key.

Since

1.2.0

AERSaveGetCurrentSlot()

int32_t AERSaveGetCurrentSlot

(

void

)

Query the index of the currently active save slot.

Bug:

When a save has not yet been loaded (such as is the case at the title screen), this function returns 0.

Returns

Save slot index or -1 if unsuccessful.

Exceptions

AER_SEQ_BREAK

if called outside action stage.

Since

1.2.0

AERSaveGetDouble()

double AERSaveGetDouble

(

const char *

key

)

Query a double value from the save file.

For information about key namespacing see Save Key Namespacing.

Parameters

[in]

key

Save key.

Returns

Value of the key or 0.0 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument key is NULL.
AER_FAILED_LOOKUP	if argument key is an invalid save key.
AER_FAILED_PARSE	if key does not contain a double value.

Since

1.2.0

See also

AERSaveSetDouble

AERSaveGetKeys()

size_t AERSaveGetKeys	(	size_t	bufSize,
		const char **	keyBuf
	)

Query the keys of all values in the save file (belonging to the calling mod).

For information about key namespacing see Save Key Namespacing.

Warning

The references returned by this function should be considered highly unstable. Consider deepcopying them if needed for later.

Argument keyBuf must be large enough to hold at least bufSize elements.

Note

Argument bufSize may be 0 in which case argument keyBuf may be NULL. This may be used to efficiently query the total number of keys contained in the save file (belonging to the calling mod).

Parameters

[in]	bufSize	Maximum number of elements to write to argument keyBuf.
[out]	keyBuf	Buffer to write keys to.

Returns

Total number of keys contained in save file or 0 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument keyBuf is NULL and argument bufSize is greater than 0.

Since

1.2.0

AERSaveGetString()

const char * AERSaveGetString

(

const char *

key

)

Query a string value from the save file.

For information about key namespacing see Save Key Namespacing.

Warning

The reference returned by this function should be considered highly unstable. Consider deepcopying it if needed for later.

Parameters

[in]

key

Save key.

Returns

Value of the key or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument key is NULL.
AER_FAILED_LOOKUP	if argument key is an invalid save key.
AER_FAILED_PARSE	if key does not contain a string value.

Since

1.2.0

See also

AERSaveSetString

AERSaveSetDouble()

void AERSaveSetDouble	(	const char *	key,
		double	value
	)

Set a double value in the save file.

This function can both create new and update existing entries in the save file (regardless of type).

For information about key namespacing see Save Key Namespacing.

Note

Changes will take effect at next save point.

Parameters

[in]	key	Save key.
[in]	value	Double save value.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument key is NULL.
AER_BAD_VAL	if argument value is Inf, -Inf or NaN.

Since

1.2.0

See also

AERSaveGetDouble

AERSaveSetString()

void AERSaveSetString	(	const char *	key,
		const char *	value
	)

Set a string value in the save file.

This function can both create new and update existing entries in the save file (regardless of type).

For information about key namespacing see Save Key Namespacing.

Note

Changes will take effect at next save point.

Parameters

[in]	key	Save key.
[in]	value	String save value.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument key or value is NULL.

Since

1.2.0

See also

AERSaveGetString