1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
/*
* Copyright (c) 2017 Cisco and/or its affiliates.
* 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.
*/
/**
* @file longBow_String.h
* @brief <#Brief Description#>
*
* <#Detailed Description#>
*
*/
#ifndef __LongBow__longBow_String__
#define __LongBow__longBow_String__
#include <stdbool.h>
#include <stdio.h>
#include <LongBow/private/longBow_ArrayList.h>
struct longbow_String;
typedef struct longbow_string LongBowString;
/**
* Create a LongBowString
*
* <#Paragraphs Of Explanation#>
*
* @param [in] initialSize The initial buffer size to allocate for the string.
*
* @return non-NULL A pointer to a valid LongBowString instance.
* @return NULL Memory could not be allocated.
*
*/
LongBowString *longBowString_Create(const size_t initialSize);
/**
* Create a `LongBowString` instance containing the formatted result of the given format string and parameters.
*
* @param [in] format A pointer to a valid LongBowString instance.
*
* @return The a LongBowString instance that must be deallocated via longBowString_Deallocate.
*/
LongBowString *longBowString_CreateFormat(const char *format, ...) __attribute__((format(printf, 1, 2)));
/**
* Destroy a LongBowString instance.
*
* The pointer will be set to zero on return.
*
* @param [in,out] stringPtr A pointer to a valid LongBowString instance.
*/
void longBowString_Destroy(LongBowString **stringPtr);
/**
* Append to the given LongBowString instance the formatted result of the given format string and parameters.
*
* @param [in] string A pointer to a valid LongBowString instance.
*
* @return The value of @p string
*/
LongBowString *longBowString_Format(LongBowString *string, const char *format, ...) __attribute__((format(printf, 2, 3)));
/**
* Determine if a string begins with a specific prefix.
*
* @param [in] string A nul-terminated C string.
* @param [in] prefix A nul-terminated C string.
*
* @return true The value of @p string starts with @p prefix.
* @return false The value of @p string does not start with @p prefix.
*
* Example:
* @code
* {
* bool result = longBowString_StartsWith("Hello World", "Hello");
* }
* @endcode
*/
bool longBowString_StartsWith(const char *string, const char *prefix);
/**
* Determine if a nul-terminated C string is equal to another.
*
* @param [in] string A nul-terminated C string.
* @param [in] other A nul-terminated C string.
*
* @return true The value of @p string starts with @p prefix.
* @return false The value of @p string does not start with @p prefix.
*
* Example:
* @code
* {
* bool result = longBowString_StartsWith("Hello World", "Hello");
* }
* @endcode
*/
bool longBowString_Equals(const char *string, const char *other);
/**
* Produce a LongBowArrayList containing the tokens for the given @p string
* where each token is separated by characters in the string @p separators.
*
* @param [in] string A nul-terminated C string.
* @param [in] separators A nul-terminated C string containing the characters that separate the tokens.
*
* @return non-NULL A valid LongBowArrayList containing the tokens of the string.
* @return NULL Memory could not be allocated.
*
* Example:
* @code
* {
* LongBowArrayList *result = longBowString_Tokenise("Hello World", " ");
* ....
* longBowArrayList_Destroy(&result);
* }
* @endcode
*/
LongBowArrayList *longBowString_Tokenise(const char *string, const char *separators);
/**
* Produce a nul-terminated C string from the given LongBowString instance.
*
* @param [in] string A pointer to a valid LongBowString instance.
*
* @return non-NULL A pointer to a nul-terminated C string that must be deallocated via free(3).
*/
char *longBowString_ToString(const LongBowString *string);
/**
* Write the contents of the given LongBowString instance to the specified FILE output stream.
*
* @param [in] string A pointer to a valid LongBowString instance.
* @param [in] fp A pointer to a valid FILE instance.
*
* @return true All of the string was successfully written.
* @return false All of the string was not successfully written.
*/
bool longBowString_Write(const LongBowString *string, FILE *fp);
#endif /* defined(__LongBow__longBow_String__) */
|
