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
152
153
154
155
156
157
158
159
160
161
|
/*
* Copyright (C) 2014-2021 Brian L. Browning
*
* This file is part of Beagle
*
* Beagle is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Beagle is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package beagleutil;
import java.util.Arrays;
/**
* <p>Class {@code SampleIds} is a singleton class that represents a
* list of sample identifiers.
* </p>
* The singleton instance of {@code SampleIds} is thread-safe.
*
* @author Brian L. Browning {@code <browning@uw.edu>}
*/
public final class SampleIds {
private static final SampleIds sampleIds = new SampleIds();
private final ThreadSafeIndexer<String> indexer;
private SampleIds() {
// private constructor to restrict instantiation.
int initCapacity = 5000;
this.indexer = new ThreadSafeIndexer<>(initCapacity);
}
/**
* Returns the singleton {@code SampleIds} instance.
* @return the singleton {@code SampleIds} instance
*/
public static SampleIds instance() {
return sampleIds;
}
/**
* Returns the index of the specified sample identifier. If
* the sample identifier is not yet indexed, the sample identifier
* will be indexed. Sample identifier indices are assigned in
* consecutive order beginning with 0.
* @param id a sample identifier
* @return the index of the specified sample identifier
* @throws IllegalArgumentException if {@code id.isEmpty()}
* @throws NullPointerException if {@code id == null}
*/
public int getIndex(String id) {
if (id.isEmpty()) {
throw new IllegalArgumentException("id.isEmpty()");
}
return indexer.getIndex(id);
}
/**
* Returns an array of sample identifier indices corresponding to the
* specified array of sample identifiers. If a sample identifier is
* not yet indexed, the sample identifier will be indexed. Sample
* identifier indices are assigned in increasing order starting with 0.
* @param ids an array of sample identifiers
* @return an array of sample identifier indices
* @throws IllegalArgumentException if there is a {@code j} satisfying
* {@code (0 <= j && j < ids.length) && ids[j].isEmpty()}
* @throws NullPointerException if {@code ids == null}
* @throws NullPointerException if there is a {@code j} satisfying
* {@code (0 <= j && j < ids.length) && (ids[j] == null)}
*/
public int[] getIndices(String[] ids) {
for (String id : ids) {
if (id.isEmpty()) {
throw new IllegalArgumentException("id.isEmpty()");
}
}
return indexer.getIndices(ids);
}
/**
* Returns the index of the specified sampled identifier, or returns
* {@code -1} if the specified sample identifier is not indexed.
*
* @param id a sample identifiers
* @return the index of the specified sampled identifier, or
* {@code -1} if the specified sample identifier is not indexed
*
* @throws IllegalArgumentException if {@code id.isEmpty()}
* @throws NullPointerException if {@code id == null}
*/
public int getIndexIfIndexed(String id) {
if (id.isEmpty()) {
throw new IllegalArgumentException("id.isEmpty()");
}
return indexer.getIndexIfIndexed(id);
}
/**
* Returns the number of indexed sample identifiers.
* @return the number of indexed samples identifiers
*/
public int size() {
return indexer.size();
}
/**
* Returns the sample identifier with the specified index.
* @param index a sample identifier index
* @return the specified sample identifier
* @throws IndexOutOfBoundsException if
* {@code index < 0 || index >= this.size()}
*/
public String id(int index) {
return indexer.item(index);
}
/**
* Returns a list of sample identifiers with the specified indices.
* @param indices an array of sample identifiers indices
* @return a list of sample identifiers with the specified indices
* @throws IndexOutOfBoundsException if there exists a {@code j} satisfying
* {@code (0 <= j && j < indices.length)
* && (indices[j] < 0 || indices[j] >= this.size())}
*/
public String[] ids(int[] indices) {
return indexer.items(indices).toArray(new String[0]);
}
/**
* Returns the list of indexed sample identifiers as an array.
* The returned array will have length {@code this.size()}, and
* it will satisfy
* {@code this.ids()[k].equals(this.id(k)) == true}
* for {@code 0 <= k && k < this.size()}.
*
* @return an array of sample identifiers
*/
public String[] ids() {
return indexer.items().toArray(new String[0]);
}
/**
* Returns {@code java.util.Arrays.toString(this.ids())}.
*
* @return a string representation of {@code this}
*/
@Override
public String toString() {
return Arrays.toString(this.ids());
}
}
|
