KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
string.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 kos/string.h
4 Copyright (C) 2004 Megan Potter
5 Copyright (C) 2025 Falco Girgis
6*/
7
8/** \file kos/string.h
9 \brief Variants on standard block memory copy/set functions.
10 \ingroup system_types
11 \deprecated
12
13 This file contains variants on the standard block memory copy/set functions.
14 These variants copy/set memory in the specified block sizes, which may be
15 helpful for interacting with memory-mapped hardware.
16
17 \note
18 None of these routines are actually faster than using the equivalent
19 standard C functions such as memcpy() and memset()!
20
21 \warning
22 Due to the fact that it breaks C and C++'s strict aliasing rules, this
23 entire API is no longer safe to use, as its calls can get optimized away
24 and never happen with higher optimization levels!
25
26 \author Megan Potter
27*/
28
29#ifndef __KOS_STRING_H
30#define __KOS_STRING_H
31
32#include <sys/cdefs.h>
33__BEGIN_DECLS
34
35#include <string.h>
36
37/** \addtogroup system_types
38 @{
39*/
40
41/** \brief Copy a block of memory, 4 bytes at a time.
42 \deprecated Invokes undefined behavior. Use memcpy().
43
44 This function is identical to memcpy(), except it copies 4 bytes at a time.
45
46 \warning
47 This function breaks C/C++ strict aliasing rules and is no longer
48 considered safe to use. It's also slow.
49
50 \param dest The destination of the copy.
51 \param src The source to copy.
52 \param count The number of bytes to copy. This should be
53 divisible by 4 (and will be rounded down if not).
54 \return The original value of dest.
55*/
56void *memcpy4(void *dest, const void *src, size_t count)
57 __depr("Unsafe. Use memcpy().");
58
59/** \brief Set a block of memory, 4 bytes at a time.
60 \deprecated Invokes undefined behavior. Use memset().
61
62 This function is identical to memset(), except it sets 4 bytes at a time.
63 This implies that all 32-bits of c are used, not just the first 8 as in
64 memset().
65
66 \warning
67 This function breaks C/C++ strict aliasing rules and is no longer
68 considered safe to use.
69
70 \param s The destination of the set.
71 \param c The value to set to.
72 \param count The number of bytes to set. This should be
73 divisible by 4 (and will be rounded down if not).
74 \return The original value of dest.
75*/
76void *memset4(void *s, unsigned long c, size_t count)
77 __depr("Unsafe. Use memset().");
78
79/** \brief Copy a block of memory, 2 bytes at a time.
80 \deprecated Invokes undefined behavior. Use memcpy().
81
82 This function is identical to memcpy(), except it copies 2 bytes at a time.
83
84 \warning
85 This function breaks C/C++ strict aliasing rules and is no longer
86 considered safe to use. It's also slow.
87
88 \param dest The destination of the copy.
89 \param src The source to copy.
90 \param count The number of bytes to copy. This should be
91 divisible by 2 (and will be rounded down if not).
92 \return The original value of dest.
93*/
94void *memcpy2(void * dest, const void *src, size_t count)
95 __depr("Unsafe. Use memcpy().");
96
97/** \brief Set a block of memory, 2 bytes at a time.
98 \deprecated Invokes undefined behavior.
99
100 This function is identical to memset(), except it sets 2 bytes at a time.
101 This implies that all 16-bits of c are used, not just the first 8 as in
102 memset().
103
104 \warning
105 This function breaks C/C++ strict aliasing rules and is no longer
106 considered safe to use.
107
108 \param s The destination of the set.
109 \param c The value to set to.
110 \param count The number of bytes to set. This should be
111 divisible by 2 (and will be rounded down if not).
112 \return The original value of dest.
113*/
114void *memset2(void *s, unsigned short c, size_t count)
115 __depr("Unsafe.");
116
117/** @} */
118
119__END_DECLS
120
121#endif /* __KOS_STRING_H */
122
123
__depr
#define __depr(m)
Mark something as deprecated, with an informative message.
Definition cdefs.h:119
memcpy2
void * memcpy2(void *dest, const void *src, size_t count) __depr("Unsafe. Use memcpy().")
Copy a block of memory, 2 bytes at a time.
memcpy4
void * memcpy4(void *dest, const void *src, size_t count) __depr("Unsafe. Use memcpy().")
Copy a block of memory, 4 bytes at a time.
memset4
void * memset4(void *s, unsigned long c, size_t count) __depr("Unsafe. Use memset().")
Set a block of memory, 4 bytes at a time.
memset2
void * memset2(void *s, unsigned short c, size_t count) __depr("Unsafe.")
Set a block of memory, 2 bytes at a time.
string.h
Variants on standard block memory copy/set functions.