sdl.error source code

1 /*
2     DSDL
3     Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay>
4 
5     This software is provided 'as-is', without any express or implied
6     warranty.  In no event will the authors be held liable for any damages
7     arising from the use of this software.
8 
9     Permission is granted to anyone to use this software for any purpose,
10     including commercial applications, and to alter it and redistribute it
11     freely, subject to the following restrictions:
12 
13     1. The origin of this software must not be misrepresented; you must not
14         claim that you wrote the original software. If you use this software
15         in a product, an acknowledgment in the product documentation would be
16         appreciated but is not required.
17     2. Altered source versions must be plainly marked as such, and must not be
18         misrepresented as being the original software.
19     3. This notice may not be removed or altered from any source distribution.
20 
21     ==========================================================================
22 
23     Simple DirectMedia Layer
24     Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
25 
26     This software is provided 'as-is', without any express or implied
27     warranty.  In no event will the authors be held liable for any damages
28     arising from the use of this software.
29 
30     Permission is granted to anyone to use this software for any purpose,
31     including commercial applications, and to alter it and redistribute it
32     freely, subject to the following restrictions:
33 
34     1. The origin of this software must not be misrepresented; you must not
35         claim that you wrote the original software. If you use this software
36         in a product, an acknowledgment in the product documentation would be
37         appreciated but is not required.
38     2. Altered source versions must be plainly marked as such, and must not be
39         misrepresented as being the original software.
40     3. This notice may not be removed or altered from any source distribution.
41 */
42 
43 /**
44     SDL Error Handling
45 
46     See_Also:
47         $(LINK2 https://wiki.libsdl.org/SDL3/CategoryError, SDL3 Error Documentation)
48     
49     Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga
50     License: Subject to the terms of the Zlib License, as written in the LICENSE file.
51     Authors: 
52         Luna Nielsen
53 */
54 module sdl.error;
55 import sdl.stdc;
56 
57 extern(C) nothrow @nogc:
58 
59 /**
60     Set the SDL error message for the current thread.
61 
62     Calling this function will replace any previous error message that was set.
63 
64     Examples:
65         This function always returns false, since SDL frequently uses false to
66         signify a failing result, leading to this idiom:
67 
68         ---
69         if (error_code) {
70             return SDL_SetError("This operation has failed: %d", error_code);
71         }
72         ---
73 
74     Params:
75         fmt =   a printf()-style message format string.
76         ... =   additional parameters matching % tokens in the `fmt` string, if
77                 any.
78     
79     Returns:
80         false
81 
82     Threadsafety:
83         It is safe to call this function from any thread.
84 
85     See_Also:
86         $(D SDL_ClearError)
87         $(D SDL_GetError)
88 */
89 extern bool SDL_SetError(const(char)* fmt, ...);
90 
91 /**
92     Set an error indicating that memory allocation failed.
93 
94     This function does not do any memory allocation.
95 
96     Returns:
97         false
98 
99     Threadsafety:
100         It is safe to call this function from any thread.
101 */
102 extern bool SDL_OutOfMemory();
103 
104 /**
105     Retrieve a message about the last error that occurred on the current
106     thread.
107 
108     It is possible for multiple errors to occur before calling SDL_GetError().
109     Only the last error is returned.
110 
111     The message is only applicable when an SDL function has signaled an error.
112     You must check the return values of SDL function calls to determine when to
113     appropriately call SDL_GetError(). You should *not* use the results of
114     SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
115     an error string even when reporting success.
116 
117     SDL will *not* clear the error string for successful API calls. You *must*
118     check return values for failure cases before you can assume the error
119     string applies.
120 
121     Error strings are set per-thread, so an error set in a different thread
122     will not interfere with the current thread's operation.
123 
124     The returned value is a thread-local string which will remain valid until
125     the current thread's error string is changed. The caller should make a copy
126     if the value is needed after the next SDL API call.
127 
128     Returns:
129         a message with information about the specific error that occurred,
130         or an empty string if there hasn't been an error message set since
131         the last call to SDL_ClearError().
132 
133     Threadsafety:
134         It is safe to call this function from any thread.
135 
136     See_Also:
137         $(D SDL_ClearError)
138         $(D SDL_SetError)
139 */
140 extern const(char)*  SDL_GetError();
141 
142 /**
143     Clear any previous error message for this thread.
144 
145     Returns:
146         true
147 
148     Threadsafety:
149         It is safe to call this function from any thread.
150 
151     See_Also:
152         $(D SDL_GetError)
153         $(D SDL_SetError)
154 */
155 extern bool SDL_ClearError();