mirror of
https://github.com/libretro/scummvm.git
synced 2025-01-26 04:35:16 +00:00
DOXYGEN: updates in first header files
Add and improve doxygen blocks in header files: - achievements.h - algorithm.h - archive.h - array.h - bitstream.h
This commit is contained in:
Bartosz Gentkowski
Eugene Sandulenko
parent
d3dc102b6a
commit
59fce86705
@ -51,58 +51,135 @@ enum AchievementsPlatform {
|
||||
|
||||
|
||||
/**
|
||||
* Per-game achievements information structure item.
|
||||
* Information structure for game-specific achievements.
|
||||
*/
|
||||
struct AchievementDescription {
|
||||
const char *id; // achievement internal id, e.g. "ACHIEVEMENT_TIMING"
|
||||
bool isHidden; // achievement is hidden
|
||||
const char *title; // achievement displayed text, e.g. "Marathon Runner"
|
||||
const char *comment; // optional achievement hint / comment, e.g. "Finish the game in less than 4 hours"
|
||||
const char *id; //!< Achievement internal ID, such as "ACHIEVEMENT_TIMING".
|
||||
bool isHidden; //!< Whether the achievement is hidden.
|
||||
const char *title; //!< Achievement displayed text, such as "Marathon Runner".
|
||||
const char *comment; //!< Optional achievement hint or comment, such as "Finish the game in less than 4 hours".
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
* Per-game achievements information structure item.
|
||||
* Information structure for platform-specific achievements.
|
||||
*/
|
||||
struct AchievementsInfo {
|
||||
Common::AchievementsPlatform platform; // achievements platform, e.g. STEAM_ACHIEVEMENTS
|
||||
Common::String appId; // achievements application ID of given platform
|
||||
Common::Array<AchievementDescription> descriptions; // descriptions of all game achievements
|
||||
Common::AchievementsPlatform platform; //!< Achievements platform, such as "STEAM_ACHIEVEMENTS".
|
||||
Common::String appId; //!< Achievements application ID of the given platform.
|
||||
Common::Array<AchievementDescription> descriptions; //!< Descriptions of all game achievements.
|
||||
|
||||
AchievementsInfo() {platform = Common::UNK_ACHIEVEMENTS;}
|
||||
};
|
||||
|
||||
/**
|
||||
* Class for manipulating the achievements.
|
||||
*
|
||||
* Use the Achievements Manager class to edit the in-game achievements.
|
||||
*/
|
||||
|
||||
class AchievementsManager : public Singleton<AchievementsManager> {
|
||||
public:
|
||||
AchievementsManager();
|
||||
~AchievementsManager();
|
||||
|
||||
|
||||
/**
|
||||
* Set a platform and application ID as active domain.
|
||||
*
|
||||
* @param[in] platform Achievements platform.
|
||||
* @param[in] appId Achievements application ID of the given platform.
|
||||
*/
|
||||
bool setActiveDomain(AchievementsPlatform platform, const String &appId);
|
||||
bool unsetActiveDomain();
|
||||
bool isReady() { return _iniFile != nullptr; }
|
||||
bool unsetActiveDomain(); //!< Unset the current active domain.
|
||||
bool isReady() { return _iniFile != nullptr; } //!< Check whether the domain is ready.
|
||||
|
||||
/**
|
||||
* @name Methods for manipulating individual achievements
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** Set an achievement.
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
* @param[in] displayedMessage Message displayed when the achievement is achieved.
|
||||
*/
|
||||
|
||||
// Methods to manipulate individual achievements
|
||||
bool setAchievement(const String &id, const String &displayedMessage);
|
||||
|
||||
/**
|
||||
* Set an achievement as achieved.
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
*/
|
||||
|
||||
bool isAchieved(const String &id);
|
||||
|
||||
/**
|
||||
* Clear an achieved achievement.
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
*/
|
||||
|
||||
bool clearAchievement(const String &id);
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @name Methods for manipulating individual statistics
|
||||
* @{
|
||||
*/
|
||||
|
||||
// Methods to manipulate individual statistics
|
||||
/**
|
||||
* Get a statistic (integer).
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
*/
|
||||
|
||||
int getStatInt(const String &id);
|
||||
|
||||
/**
|
||||
* Set a statistic to an integer number.
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
* @param[in] value Value to which the statistic is set.
|
||||
*/
|
||||
|
||||
bool setStatInt(const String &id, int value);
|
||||
|
||||
/**
|
||||
* Get a statistic (float).
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
*/
|
||||
|
||||
float getStatFloat(const String &id);
|
||||
|
||||
/**
|
||||
* Set a statistic to a float number.
|
||||
*
|
||||
* @param[in] id Internal ID of the achievement.
|
||||
* @param[in] value Value to which the statistic is set.
|
||||
*/
|
||||
|
||||
bool setStatFloat(const String &id, float value);
|
||||
|
||||
// Methods to reset everything
|
||||
bool resetAllAchievements();
|
||||
bool resetAllStats();
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @name Methods for resetting achievements and statistics
|
||||
* @{
|
||||
*/
|
||||
bool resetAllAchievements(); //!< Reset all achievements.
|
||||
bool resetAllStats(); //!< Reset all statistics.
|
||||
|
||||
/** @} */
|
||||
|
||||
private:
|
||||
INIFile *_iniFile;
|
||||
String _iniFileName;
|
||||
};
|
||||
|
||||
/** Shortcut for accessing the achievements manager. */
|
||||
/** Shortcut for accessing the Achievements Manager. */
|
||||
#define AchMan Common::AchievementsManager::instance()
|
||||
|
||||
/** @} */
|
||||
|
||||
@ -39,8 +39,14 @@ namespace Common {
|
||||
*/
|
||||
|
||||
/**
|
||||
* Copies data from the range [first, last) to [dst, dst + (last - first)).
|
||||
* It requires the range [dst, dst + (last - first)) to be valid.
|
||||
* @name Copy templates
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Copy data from the range [first, last) to [dst, dst + (last - first)).
|
||||
*
|
||||
* The function requires the range [dst, dst + (last - first)) to be valid.
|
||||
* It also requires dst not to be in the range [first, last).
|
||||
*/
|
||||
template<class In, class Out>
|
||||
@ -51,11 +57,12 @@ Out copy(In first, In last, Out dst) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies data from the range [first, last) to [dst - (last - first), dst).
|
||||
* It requires the range [dst - (last - first), dst) to be valid.
|
||||
* Copy data from the range [first, last) to [dst - (last - first), dst).
|
||||
*
|
||||
* The function requires the range [dst - (last - first), dst) to be valid.
|
||||
* It also requires dst not to be in the range [first, last).
|
||||
*
|
||||
* Unlike copy copy_backward copies the data from the end to the beginning.
|
||||
* Unlike copy, copy_backward copies the data from the end to the beginning.
|
||||
*/
|
||||
template<class In, class Out>
|
||||
Out copy_backward(In first, In last, Out dst) {
|
||||
@ -65,11 +72,12 @@ Out copy_backward(In first, In last, Out dst) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies data from the range [first, last) to [dst, dst + (last - first)).
|
||||
* It requires the range [dst, dst + (last - first)) to be valid.
|
||||
* Copy data from the range [first, last) to [dst, dst + (last - first)).
|
||||
*
|
||||
* The function requires the range [dst, dst + (last - first)) to be valid.
|
||||
* It also requires dst not to be in the range [first, last).
|
||||
*
|
||||
* Unlike copy or copy_backward it does not copy all data. It only copies
|
||||
* Unlike copy or copy_backward, it does not copy all data. It only copies
|
||||
* a data element when operator() of the op parameter returns true for the
|
||||
* passed data element.
|
||||
*/
|
||||
@ -83,23 +91,51 @@ Out copy_if(In first, In last, Out dst, Op op) {
|
||||
return dst;
|
||||
}
|
||||
|
||||
// Our 'specialized' 'fill' template for char, signed char and unsigned char arrays.
|
||||
// Since C++ doesn't support partial specialized template functions (currently) we
|
||||
// are going this way...
|
||||
// With this we assure the usage of memset for those, which should be
|
||||
// faster than a simple loop like for the generic 'fill'.
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @name Fill templates
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* A 'fill' template for signed char arrays.
|
||||
*
|
||||
* Since C++ does not currently support partial specialized template functions,
|
||||
* this solution is implemented.
|
||||
* With this template, the usage of memset is assured, which is
|
||||
* faster than a simple loop like for the generic 'fill'.
|
||||
*/
|
||||
template<class Value>
|
||||
signed char *fill(signed char *first, signed char *last, Value val) {
|
||||
memset(first, (val & 0xFF), last - first);
|
||||
return last;
|
||||
}
|
||||
|
||||
/**
|
||||
* A 'fill' template for unsigned char arrays.
|
||||
*
|
||||
* Since C++ does not currently support partial specialized template functions,
|
||||
* this solution is implemented.
|
||||
* With this template, the usage of memset is assured, which is
|
||||
* faster than a simple loop like for the generic 'fill'.
|
||||
*/
|
||||
template<class Value>
|
||||
unsigned char *fill(unsigned char *first, unsigned char *last, Value val) {
|
||||
memset(first, (val & 0xFF), last - first);
|
||||
return last;
|
||||
}
|
||||
|
||||
/**
|
||||
* A 'fill' template for char arrays.
|
||||
*
|
||||
* Since C++ does not currently support partial specialized template functions,
|
||||
* this solution is implemented.
|
||||
* With this template, the usage of memset is assured, which is
|
||||
* faster than a simple loop like for the generic 'fill'.
|
||||
*/
|
||||
template<class Value>
|
||||
char *fill(char *first, char *last, Value val) {
|
||||
memset(first, (val & 0xFF), last - first);
|
||||
@ -107,7 +143,16 @@ char *fill(char *first, char *last, Value val) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets all elements in the range [first, last) to val.
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @name Range templates
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Set all elements in the range [first, last) to val.
|
||||
*/
|
||||
template<class In, class Value>
|
||||
In fill(In first, In last, const Value &val) {
|
||||
@ -117,8 +162,8 @@ In fill(In first, In last, const Value &val) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds the first data value in the range [first, last) matching v.
|
||||
* For data comperance it uses operator == of the data elements.
|
||||
* Find the first data value in the range [first, last) matching v.
|
||||
* For data comparison, it uses operator == of the data elements.
|
||||
*/
|
||||
template<class In, class T>
|
||||
In find(In first, In last, const T &v) {
|
||||
@ -131,7 +176,7 @@ In find(In first, In last, const T &v) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds the first data value in the range [first, last) for which
|
||||
* Find the first data value in the range [first, last), for which
|
||||
* the specified predicate p returns true.
|
||||
*/
|
||||
template<class In, class Pred>
|
||||
@ -145,7 +190,7 @@ In find_if(In first, In last, Pred p) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Applies the function f on all elements of the range [first, last).
|
||||
* Apply the function f on all elements from the range [first, last).
|
||||
* The processing order is from beginning to end.
|
||||
*/
|
||||
template<class In, class Op>
|
||||
@ -155,6 +200,10 @@ Op for_each(In first, In last, Op f) {
|
||||
return f;
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
template<typename T>
|
||||
unsigned int distance(T *first, T *last) {
|
||||
return last - first;
|
||||
@ -205,12 +254,18 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple sort function, modeled after std::sort.
|
||||
* It compares data with the given comparator object comp.
|
||||
* @name Sorting templates
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Simple sorting function, modeled after std::sort.
|
||||
*
|
||||
* Like std::sort this is not guaranteed to be stable.
|
||||
* This function compares data with the given comparator object comp.
|
||||
*
|
||||
* Two small quotes from wikipedia about stability:
|
||||
* Like std::sort, this is not guaranteed to be stable.
|
||||
*
|
||||
* Two quotes from Wikipedia about stability:
|
||||
*
|
||||
* Stable sorting algorithms maintain the relative order of records with
|
||||
* equal keys.
|
||||
@ -218,11 +273,16 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
|
||||
* Unstable sorting algorithms may change the relative order of records with
|
||||
* equal keys, but stable sorting algorithms never do so.
|
||||
*
|
||||
* For more information on that topic check out:
|
||||
* For more information, see:
|
||||
* http://en.wikipedia.org/wiki/Sorting_algorithm#Stability
|
||||
*
|
||||
* NOTE: Actually as the time of writing our implementation is unstable.
|
||||
* @note Currently, this implementation is unstable.
|
||||
*
|
||||
* @param[in] first First element to sort.
|
||||
* @param[in] last Last element to sort.
|
||||
* @param[in] comp Comparator object.
|
||||
*/
|
||||
|
||||
template<typename T, class StrictWeakOrdering>
|
||||
void sort(T first, T last, StrictWeakOrdering comp) {
|
||||
if (first == last)
|
||||
@ -235,7 +295,10 @@ void sort(T first, T last, StrictWeakOrdering comp) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple sort function, modeled after std::sort.
|
||||
* Simple sorting function, modeled after std::sort.
|
||||
*
|
||||
* @param[in] first First element to sort.
|
||||
* @param[in] last Last element to sort.
|
||||
*/
|
||||
template<typename T>
|
||||
void sort(T *first, T *last) {
|
||||
@ -247,6 +310,10 @@ void sort(T first, T last) {
|
||||
sort(first, last, Less<typename T::ValueType>());
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
// MSVC is complaining about the minus operator being applied to an unsigned type
|
||||
// We disable this warning for the affected section of code
|
||||
#if defined(_MSC_VER)
|
||||
@ -255,7 +322,7 @@ void sort(T first, T last) {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Euclid's algorithm to compute the greatest common divisor.
|
||||
* Euclidean algorithm to compute the greatest common divisor.
|
||||
*/
|
||||
template<class T>
|
||||
T gcd(T a, T b) {
|
||||
@ -301,10 +368,10 @@ T nextHigher2(T v) {
|
||||
*
|
||||
* Replaces all occurrences of "original" in [begin, end) with occurrences of "replaced".
|
||||
*
|
||||
* @param[in, out] begin: First element to be examined.
|
||||
* @param[in] end: Last element in the seubsection. Not examined.
|
||||
* @param[in] original: Elements to be replaced.
|
||||
* @param[in] replaced: Element to replace occurrences of "original".
|
||||
* @param[in,out] begin First element to be examined.
|
||||
* @param[in] end Last element in the subsection. Not examined.
|
||||
* @param[in] original Elements to be replaced.
|
||||
* @param[in] replaced Element to replace occurrences of @p original.
|
||||
*
|
||||
* @note Usage examples and unit tests may be found in "test/common/algorithm.h"
|
||||
*/
|
||||
@ -319,7 +386,6 @@ void replace(It begin, It end, const Dat &original, const Dat &replaced) {
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
} // End of namespace Common
|
||||
|
||||
#endif
|
||||
|
||||
@ -34,25 +34,23 @@ namespace Common {
|
||||
* @defgroup common_arch Archive
|
||||
* @ingroup common
|
||||
*
|
||||
* @brief The Archive module allows managing the member of arbitrary containers in a uniform
|
||||
* @brief The Archive module allows for managing the members of arbitrary containers in a uniform
|
||||
* fashion.
|
||||
* It also supports looking up by names and file names, opening a file, and returning usable input stream.
|
||||
*
|
||||
* It also supports looking up by names and file names, opening a file, and returning a usable input stream.
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
class FSNode;
|
||||
class SeekableReadStream;
|
||||
|
||||
|
||||
/**
|
||||
* ArchiveMember is an abstract interface to represent elements inside
|
||||
* implementations of Archive.
|
||||
* The ArchiveMember class is an abstract interface to represent elements inside
|
||||
* implementations of an archive.
|
||||
*
|
||||
* Archive subclasses must provide their own implementation of ArchiveMember,
|
||||
* and use it when serving calls to listMembers() and listMatchingMembers().
|
||||
* Alternatively, the GenericArchiveMember below can be used.
|
||||
* and use it when serving calls to @ref Archive::listMembers and @ref Archive::listMatchingMembers.
|
||||
* Alternatively, you can use the @ref GenericArchiveMember.
|
||||
*/
|
||||
class ArchiveMember {
|
||||
public:
|
||||
@ -93,9 +91,9 @@ public:
|
||||
|
||||
|
||||
/**
|
||||
* Archive allows managing of member of arbitrary containers in a uniform
|
||||
* fashion, allowing lookup by (file)names.
|
||||
* It also supports opening a file and returning an usable input stream.
|
||||
* The Archive class allows for managing the members of arbitrary containers in a uniform
|
||||
* fashion, allowing lookup by (file) names.
|
||||
* It also supports opening a file and returning a usable input stream.
|
||||
*/
|
||||
class Archive {
|
||||
public:
|
||||
@ -109,40 +107,42 @@ public:
|
||||
virtual bool hasFile(const String &name) const = 0;
|
||||
|
||||
/**
|
||||
* Add all members of the Archive matching the specified pattern to list.
|
||||
* Add all members of the Archive matching the specified pattern to the list.
|
||||
* Must only append to list, and not remove elements from it.
|
||||
*
|
||||
* @return the number of members added to list
|
||||
* @return The number of members added to list.
|
||||
*/
|
||||
virtual int listMatchingMembers(ArchiveMemberList &list, const String &pattern) const;
|
||||
|
||||
/**
|
||||
* Add all members of the Archive to list.
|
||||
* Add all members of the Archive to the list.
|
||||
* Must only append to list, and not remove elements from it.
|
||||
*
|
||||
* @return the number of names added to list
|
||||
* @return The number of names added to list.
|
||||
*/
|
||||
virtual int listMembers(ArchiveMemberList &list) const = 0;
|
||||
|
||||
/**
|
||||
* Returns a ArchiveMember representation of the given file.
|
||||
* Return an ArchiveMember representation of the given file.
|
||||
*/
|
||||
virtual const ArchiveMemberPtr getMember(const String &name) const = 0;
|
||||
|
||||
/**
|
||||
* Create a stream bound to a member with the specified name in the
|
||||
* archive. If no member with this name exists, 0 is returned.
|
||||
* @return the newly created input stream
|
||||
*
|
||||
* @return The newly created input stream.
|
||||
*/
|
||||
virtual SeekableReadStream *createReadStreamForMember(const String &name) const = 0;
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
* SearchSet enables access to a group of Archives through the Archive interface.
|
||||
* The SearchSet class enables access to a group of Archives through the Archive interface.
|
||||
*
|
||||
* Its intended usage is a situation in which there are no name clashes among names in the
|
||||
* contained Archives, hence the simplistic policy of always looking for the first
|
||||
* match. SearchSet *DOES* guarantee that searches are performed in *DESCENDING*
|
||||
* match. SearchSet does guarantee that searches are performed in DESCENDING
|
||||
* priority order. In case of conflicting priorities, insertion order prevails.
|
||||
*/
|
||||
class SearchSet : public Archive {
|
||||
@ -161,8 +161,7 @@ class SearchSet : public Archive {
|
||||
ArchiveNodeList::iterator find(const String &name);
|
||||
ArchiveNodeList::const_iterator find(const String &name) const;
|
||||
|
||||
// Add an archive keeping the list sorted by descending priority.
|
||||
void insert(const Node& node);
|
||||
void insert(const Node& node); //!< Add an archive keeping the list sorted by descending priority.
|
||||
|
||||
bool _ignoreClashes;
|
||||
|
||||
@ -176,58 +175,56 @@ public:
|
||||
void add(const String& name, Archive *arch, int priority = 0, bool autoFree = true);
|
||||
|
||||
/**
|
||||
* Create and add a FSDirectory by name
|
||||
* Create and add a FSDirectory by name.
|
||||
*/
|
||||
void addDirectory(const String &name, const String &directory, int priority = 0, int depth = 1, bool flat = false);
|
||||
|
||||
/**
|
||||
* Create and add a FSDirectory by FSNode
|
||||
* Create and add a FSDirectory by FSNode.
|
||||
*/
|
||||
void addDirectory(const String &name, const FSNode &directory, int priority = 0, int depth = 1, bool flat = false);
|
||||
|
||||
/**
|
||||
* Create and add a sub directory by name (caseless).
|
||||
* Create and add a subdirectory by name (caseless).
|
||||
*
|
||||
* It is also possible to add sub directories of sub directories (of any depth) with this function.
|
||||
* The path seperator for this case is SLASH for *all* systems.
|
||||
* It is also possible to add subdirectories of subdirectories (of any depth) with this function.
|
||||
* The path seperator for this case is SLASH for all systems.
|
||||
*
|
||||
* An example would be:
|
||||
* Example:
|
||||
*
|
||||
* "game/itedata"
|
||||
*
|
||||
* In this example the code would first try to search for all directories matching
|
||||
* In this example, the code first tries to search for all directories matching
|
||||
* "game" (case insensitive) in the path "directory" first and search through all
|
||||
* of the matches for "itedata" (case insensitive too).
|
||||
*
|
||||
* Note that it will add *all* matches found!
|
||||
* Note that it will add all matches found!
|
||||
*
|
||||
* Even though this method is currently implemented via addSubDirectoriesMatching it is not safe
|
||||
* Even though this method is currently implemented via addSubDirectoriesMatching, it is not safe
|
||||
* to assume that this method is using anything other than a simple case insensitive compare.
|
||||
* Thus do not use any tokens like '*' or '?' in the "caselessName" parameter of this function!
|
||||
* Thus, do not use any tokens like '*' or '?' in the "caselessName" parameter of this function.
|
||||
*/
|
||||
void addSubDirectoryMatching(const FSNode &directory, const String &caselessName, int priority = 0, int depth = 1, bool flat = false) {
|
||||
addSubDirectoriesMatching(directory, caselessName, true, priority, depth, flat);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create and add sub directories by pattern.
|
||||
* Create and add subdirectories by pattern.
|
||||
*
|
||||
* It is also possible to add sub directories of sub directories (of any depth) with this function.
|
||||
* The path seperator for this case is SLASH for *all* systems.
|
||||
* It is also possible to add subdirectories of subdirectories (of any depth) with this function.
|
||||
* The path seperator for this case is SLASH for all systems.
|
||||
*
|
||||
* An example would be:
|
||||
* Example:
|
||||
*
|
||||
* "game/itedata"
|
||||
*
|
||||
* In this example the code would first try to search for all directories matching
|
||||
* In this example, the code first tries to search for all directories matching
|
||||
* "game" in the path "directory" first and search through all of the matches for
|
||||
* "itedata". If "ingoreCase" is set to true, the code would do a case insensitive
|
||||
* "itedata". If "ingoreCase" is set to true, the code does a case insensitive
|
||||
* match, otherwise it is doing a case sensitive match.
|
||||
*
|
||||
* This method works of course also with tokens. For a list of available tokens
|
||||
* see the documentation for Common::matchString.
|
||||
*
|
||||
* @see Common::matchString
|
||||
* This method also works with tokens. For a list of available tokens,
|
||||
* see @ref Common::matchString.
|
||||
*/
|
||||
void addSubDirectoriesMatching(const FSNode &directory, String origPattern, bool ignoreCase, int priority = 0, int depth = 1, bool flat = false);
|
||||
|
||||
@ -242,7 +239,7 @@ public:
|
||||
bool hasArchive(const String &name) const;
|
||||
|
||||
/**
|
||||
* Empties the searchable set.
|
||||
* Empty the searchable set.
|
||||
*/
|
||||
virtual void clear();
|
||||
|
||||
@ -258,14 +255,14 @@ public:
|
||||
virtual const ArchiveMemberPtr getMember(const String &name) const;
|
||||
|
||||
/**
|
||||
* Implements createReadStreamForMember from Archive base class. The current policy is
|
||||
* Implement createReadStreamForMember from the Archive base class. The current policy is
|
||||
* opening the first file encountered that matches the name.
|
||||
*/
|
||||
virtual SeekableReadStream *createReadStreamForMember(const String &name) const;
|
||||
|
||||
/**
|
||||
* Ignore clashes when adding directories. For more details see the corresponding parameter
|
||||
* in FSDirectory documentation
|
||||
* Ignore clashes when adding directories. For more details, see the corresponding parameter
|
||||
* in FSDirectory documentation.
|
||||
*/
|
||||
void setIgnoreClashes(bool ignoreClashes) { _ignoreClashes = ignoreClashes; }
|
||||
};
|
||||
@ -275,7 +272,7 @@ class SearchManager : public Singleton<SearchManager>, public SearchSet {
|
||||
public:
|
||||
|
||||
/**
|
||||
* Resets the search manager to the default list of search paths (system
|
||||
* Reset the Search Manager to the default list of search paths (system
|
||||
* specific dirs + current dir).
|
||||
*/
|
||||
virtual void clear();
|
||||
@ -285,7 +282,7 @@ private:
|
||||
SearchManager();
|
||||
};
|
||||
|
||||
/** Shortcut for accessing the search manager. */
|
||||
/** Shortcut for accessing the Search Manager. */
|
||||
#define SearchMan Common::SearchManager::instance()
|
||||
|
||||
/** @} */
|
||||
|
||||
@ -38,17 +38,15 @@ namespace Common {
|
||||
* @defgroup common_array Arrays
|
||||
* @ingroup common
|
||||
*
|
||||
* @brief Functions for working on arrays.
|
||||
*
|
||||
* @brief Functions for replacing std arrays.
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* This class implements a dynamically sized container, which
|
||||
* can be accessed similar to a regular C++ array. Accessing
|
||||
* can be accessed similarly to a regular C++ array. Accessing
|
||||
* elements is performed in constant time (like with plain arrays).
|
||||
* In addition, one can append, insert and remove entries (this
|
||||
* In addition, you can append, insert, and remove entries (this
|
||||
* is the 'dynamic' part). Doing that in general takes time
|
||||
* proportional to the number of elements in the array.
|
||||
*
|
||||
@ -74,7 +72,7 @@ public:
|
||||
Array() : _capacity(0), _size(0), _storage(nullptr) {}
|
||||
|
||||
/**
|
||||
* Constructs an array with `count` default-inserted instances of T. No
|
||||
* Construct an array with `count` default-inserted instances of @p T. No
|
||||
* copies are made.
|
||||
*/
|
||||
explicit Array(size_type count) : _size(count) {
|
||||
@ -84,7 +82,7 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* Constructs an array with `count` copies of elements with value `value`.
|
||||
* Construct an array with `count` copies of elements with value `value`.
|
||||
*/
|
||||
Array(size_type count, const T &value) : _size(count) {
|
||||
allocCapacity(count);
|
||||
@ -134,7 +132,7 @@ public:
|
||||
_capacity = _size = 0;
|
||||
}
|
||||
|
||||
/** Appends element to the end of the array. */
|
||||
/** Append an element to the end of the array. */
|
||||
void push_back(const T &element) {
|
||||
if (_size + 1 <= _capacity)
|
||||
new ((void *)&_storage[_size++]) T(element);
|
||||
@ -150,7 +148,7 @@ public:
|
||||
insert_aux(end(), array.begin(), array.end());
|
||||
}
|
||||
|
||||
/** Removes the last element of the array. */
|
||||
/** Remove the last element of the array. */
|
||||
void pop_back() {
|
||||
assert(_size > 0);
|
||||
_size--;
|
||||
@ -158,35 +156,35 @@ public:
|
||||
_storage[_size].~T();
|
||||
}
|
||||
|
||||
/** Returns a pointer to the underlying memory serving as element storage. */
|
||||
/** Return a pointer to the underlying memory serving as element storage. */
|
||||
const T *data() const {
|
||||
return _storage;
|
||||
}
|
||||
|
||||
/** Returns a pointer to the underlying memory serving as element storage. */
|
||||
/** Return a pointer to the underlying memory serving as element storage. */
|
||||
T *data() {
|
||||
return _storage;
|
||||
}
|
||||
|
||||
/** Returns a reference to the first element of the array. */
|
||||
/** Return a reference to the first element of the array. */
|
||||
T &front() {
|
||||
assert(_size > 0);
|
||||
return _storage[0];
|
||||
}
|
||||
|
||||
/** Returns a reference to the first element of the array. */
|
||||
/** Return a reference to the first element of the array. */
|
||||
const T &front() const {
|
||||
assert(_size > 0);
|
||||
return _storage[0];
|
||||
}
|
||||
|
||||
/** Returns a reference to the last element of the array. */
|
||||
/** Return a reference to the last element of the array. */
|
||||
T &back() {
|
||||
assert(_size > 0);
|
||||
return _storage[_size-1];
|
||||
}
|
||||
|
||||
/** Returns a reference to the last element of the array. */
|
||||
/** Return a reference to the last element of the array. */
|
||||
const T &back() const {
|
||||
assert(_size > 0);
|
||||
return _storage[_size-1];
|
||||
@ -204,7 +202,7 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* Inserts element before pos.
|
||||
* Insert an element before @p pos.
|
||||
*/
|
||||
void insert(iterator pos, const T &element) {
|
||||
insert_aux(pos, &element, &element + 1);
|
||||
@ -377,7 +375,7 @@ protected:
|
||||
* Unlike std::vector::insert, this method does not accept
|
||||
* arbitrary iterators, mainly because our iterator system is
|
||||
* seriously limited and does not distinguish between input iterators,
|
||||
* output iterators, forward iterators or random access iterators.
|
||||
* output iterators, forward iterators, or random access iterators.
|
||||
*
|
||||
* So, we simply restrict to Array iterators. Extending this to arbitrary
|
||||
* random access iterators would be trivial.
|
||||
@ -404,7 +402,7 @@ protected:
|
||||
uninitialized_copy(oldStorage, oldStorage + idx, _storage);
|
||||
// Copy the data we insert
|
||||
uninitialized_copy(first, last, _storage + idx);
|
||||
// Afterwards copy the old data from the position where we
|
||||
// Afterwards, copy the old data from the position where we
|
||||
// insert.
|
||||
uninitialized_copy(oldStorage + idx, oldStorage + _size, _storage + idx + n);
|
||||
|
||||
@ -442,7 +440,7 @@ protected:
|
||||
};
|
||||
|
||||
/**
|
||||
* Double linked list with sorted nodes.
|
||||
* Doubly linked list with sorted nodes.
|
||||
*/
|
||||
template<class T, typename CompareArgType = const void *>
|
||||
class SortedArray : public Array<T> {
|
||||
@ -456,7 +454,7 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* Inserts element at the sorted position.
|
||||
* Insert an element at the sorted position.
|
||||
*/
|
||||
void insert(const T &element) {
|
||||
if (!this->_size) {
|
||||
|
||||
@ -49,19 +49,19 @@ namespace Common {
|
||||
* gives access to their bits, one at a time.
|
||||
*
|
||||
* For example, a bit stream with the layout parameters 32, true, false
|
||||
* for valueBits, isLE and isMSB2LSB, reads 32bit little-endian values
|
||||
* for valueBits, isLE and isMSB2LSB, reads 32-bit little-endian values
|
||||
* from the data stream and hands out the bits in the order of LSB to MSB.
|
||||
*/
|
||||
template<class STREAM, int valueBits, bool isLE, bool MSB2LSB>
|
||||
class BitStreamImpl {
|
||||
private:
|
||||
STREAM *_stream; ///< The input stream.
|
||||
DisposeAfterUse::Flag _disposeAfterUse; ///< Should we delete the stream on destruction?
|
||||
STREAM *_stream; //!< The input stream.
|
||||
DisposeAfterUse::Flag _disposeAfterUse; //!< Whether to delete the stream on destruction.
|
||||
|
||||
uint64 _bitContainer; ///< The currently available bits.
|
||||
uint8 _bitsLeft; ///< Number of bits currently left in the bit container.
|
||||
uint32 _size; ///< Total bitstream size (in bits)
|
||||
uint32 _pos; ///< Current bitstream position (in bits)
|
||||
uint64 _bitContainer; //!< The currently available bits.
|
||||
uint8 _bitsLeft; //!< Number of bits currently left in the bit container.
|
||||
uint32 _size; //!< Total bit stream size (in bits).
|
||||
uint32 _pos; //!< Current bit stream position (in bits).
|
||||
|
||||
/** Read a data value. */
|
||||
inline uint32 readData() {
|
||||
@ -85,7 +85,7 @@ private:
|
||||
return 0;
|
||||
}
|
||||
|
||||
/** Fill the container with at least min bits. */
|
||||
/** Fill the container with at least @p min bits. */
|
||||
inline void fillContainer(size_t min) {
|
||||
while (_bitsLeft < min) {
|
||||
|
||||
@ -93,11 +93,11 @@ private:
|
||||
if (_pos + _bitsLeft + valueBits <= _size) {
|
||||
data = readData();
|
||||
} else {
|
||||
// Peeking data out of bounds is well defined and returns 0 bits.
|
||||
// Peeking data out of bounds is well-defined and returns 0 bits.
|
||||
// This is for convenience when using speed-up techniques reading
|
||||
// more bits than actually available. Users should call eos() to
|
||||
// check if data was actually read out of bounds. Peeking out of
|
||||
// bounds does not set the eos flag.
|
||||
// more bits than actually available. Call eos() to check if data
|
||||
// was actually read out of bounds. Peeking out of bounds does not
|
||||
// set the eos flag.
|
||||
data = 0;
|
||||
}
|
||||
|
||||
@ -111,7 +111,7 @@ private:
|
||||
}
|
||||
}
|
||||
|
||||
/** Get n bits from the bit container. */
|
||||
/** Get @p n bits from the bit container. */
|
||||
inline static uint32 getNBits(uint64 value, size_t n) {
|
||||
if (n == 0)
|
||||
return 0;
|
||||
@ -183,7 +183,7 @@ public:
|
||||
/**
|
||||
* Read a multi-bit value from the bit stream, without changing the stream's position.
|
||||
*
|
||||
* The bit order is the same as in getBits().
|
||||
* The bit order is the same as in @ref getBits().
|
||||
*/
|
||||
uint32 peekBits(size_t n) {
|
||||
if (n > 32)
|
||||
@ -196,12 +196,12 @@ public:
|
||||
/**
|
||||
* Read a multi-bit value from the bit stream.
|
||||
*
|
||||
* The value is read as if just taken as a whole from the bitstream.
|
||||
* The value is read as if just taken as a whole from the bit stream.
|
||||
*
|
||||
* For example:
|
||||
* Reading a 4-bit value from an 8-bit bitstream with the contents 01010011:
|
||||
* If the bitstream is MSB2LSB, the 4-bit value would be 0101.
|
||||
* If the bitstream is LSB2MSB, the 4-bit value would be 0011.
|
||||
* Reading a 4-bit value from an 8-bit bit stream with the contents 01010011:
|
||||
* If the bit stream is MSB2LSB, the 4-bit value would be 0101.
|
||||
* If the bit stream is LSB2MSB, the 4-bit value would be 0011.
|
||||
*/
|
||||
uint32 getBits(size_t n) {
|
||||
if (n > 32)
|
||||
@ -218,12 +218,12 @@ public:
|
||||
* Add a bit to the value x, making it an n+1-bit value.
|
||||
*
|
||||
* The current value is shifted and the bit is added to the
|
||||
* appropriate place, dependant on the stream's bitorder.
|
||||
* appropriate place, depending on the stream's bit order.
|
||||
*
|
||||
* For example:
|
||||
* A bit y is added to the value 00001100 with size 4.
|
||||
* If the stream's bitorder is MSB2LSB, the resulting value is 0001100y.
|
||||
* If the stream's bitorder is LSB2MSB, the resulting value is 000y1100.
|
||||
* If the stream's bit order is MSB2LSB, the resulting value is 0001100y.
|
||||
* If the stream's bit order is LSB2MSB, the resulting value is 000y1100.
|
||||
*/
|
||||
void addBit(uint32 &x, uint32 n) {
|
||||
if (n >= 32)
|
||||
@ -244,7 +244,7 @@ public:
|
||||
_pos = 0;
|
||||
}
|
||||
|
||||
/** Skip the specified amount of bits. */
|
||||
/** Skip the specified number of bits. */
|
||||
void skip(uint32 n) {
|
||||
while (n > 32) {
|
||||
fillContainer(32);
|
||||
@ -428,8 +428,10 @@ public:
|
||||
|
||||
};
|
||||
|
||||
|
||||
// typedefs for various memory layouts.
|
||||
/**
|
||||
* @name Typedefs for various memory layouts
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** 8-bit data, MSB to LSB. */
|
||||
typedef BitStreamImpl<SeekableReadStream, 8, false, true > BitStream8MSB;
|
||||
@ -481,6 +483,8 @@ typedef BitStreamImpl<BitStreamMemoryStream, 32, false, false> BitStreamMemory32
|
||||
|
||||
/** @} */
|
||||
|
||||
/** @} */
|
||||
|
||||
} // End of namespace Common
|
||||
|
||||
#endif // COMMON_BITSTREAM_H
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user