001/*
002 * SPDX-License-Identifier: Apache-2.0
003 *
004 * Copyright 2025-2026 The Enola <https://enola.dev> Authors
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     https://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package dev.enola.common.string2long;
019
020/// Bidirectional map for common "Symbol" String to Long.
021///
022/// Useful e.g. for "compressing" client-server I/O, or persistent storage; not needed in-memory.
023///
024/// Enola can use this e.g. for Thing IRI, including Datatype IRI, but also e.g. Language Codes.
025///
026/// See also string2long.ts
027public interface StringToLongBiMap {
028
029    interface LongOrStringConsumer {
030        void longID(long id);
031
032        void string(String symbol);
033    }
034
035    // For what we intend to use this for (e.g. JSON gen, or oneof Proto), this signature is much
036    // better than Object getOrSame(String) & Object getOrSame(long) [which would lead to
037    // instanceof], or Optional<Long> getOptional(String) & Optional<String> getOptional(long)
038    // [which would constantly "double look-up" instead of this much more efficient single op].
039    void get(String symbol, LongOrStringConsumer consumer);
040
041    String get(long id) throws IllegalArgumentException;
042
043    long size();
044
045    /** Symbols, ordered by their Long ID. */
046    Iterable<String> symbols();
047
048    // skipcq: JAVA-E0169
049    interface Builder extends dev.enola.common.Builder<StringToLongBiMap> {
050        long put(String symbol);
051    }
052}