# mval

**Repository Path**: zoppax/mval

## Basic Information

- **Project Name**: mval
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mval

Enhanced `any` type with ordered map support, inspired by bytedance/sonic's API style.

## Features

- **Ordered Map**: Native ordered map (Omap) type that preserves insertion order
- **JSON Unmarshal**: Auto-detects, if object is found, converts to Omap
- **JSON Marshal**: Maintains key order
- **Type Safe Conversions**: With default values for safe type casting
- **Chained Operations**: Support for chained Set() and Get() operations

## Install

```bash
go get gitee.com/zoppax/mval
```

## API

### Constants

- `var Null *Mval`: Pre-initialized nil Mval (from FromAny(nil))
- `var Err *Mval`: Pre-initialized error Mval (from FromAny(errors.New("Err")))

### Constructors

- `func NewRoot() *Mval`: Create root Mval with empty Omap
- `func FromAny(v any) *Mval`: Convert any value to Mval
- `func FromJSON(data []byte, errOut ...*error) *Mval`: Parse JSON data to Mval (returns Err on failure)
- `func FromJSONString(s string, errOut ...*error) *Mval`: Parse JSON string to Mval (returns Err on failure)

### Mval Type Checks

- `func (m *Mval) IsNull() bool`: Check if value is nil
- `func (m *Mval) IsBool() bool`: Check if value is bool
- `func (m *Mval) IsNumber() bool`: Check if value is number (int/float)
- `func (m *Mval) IsInt() bool`: Check if value is integer (int, int8-64, uint, uint8-64)
- `func (m *Mval) IsFloat() bool`: Check if value is float (float32, float64)
- `func (m *Mval) IsString() bool`: Check if value is string
- `func (m *Mval) IsArray() bool`: Check if value is array/slice
- `func (m *Mval) IsOmap() bool`: Check if Mval is ordered map
- `func (m *Mval) IsError() bool`: Check if value is error type

### Mval Type Conversions (with defaults)

- `func (m *Mval) Interface() any`: Get raw value
- `func (m *Mval) Any() any`: Get raw value (alias for Interface())
- `func (m *Mval) Bool(errOut ...*error) bool`: Convert to bool (false on failure)
- `func (m *Mval) Int(errOut ...*error) int64`: Convert to int64 (0 on failure, bool: true→1, false→0)
- `func (m *Mval) Float(errOut ...*error) float64`: Convert to float64 (0.0 on failure)
- `func (m *Mval) String(errOut ...*error) string`: Convert to string ("" on failure, int/uint series: convert to decimal string)
- `func (m *Mval) Array(errOut ...*error) []*Mval`: Convert to array (empty array []\*Mval{} on failure)
- `func (m *Mval) Omap(errOut ...*error) *Omap`: Convert to Omap (empty Omap on failure)
- `func (m *Mval) Index(n int, errOut ...*error) *Mval`: Access array element by index (chainable)
- `func (m *Mval) WhenOmap() *Omap`: Get Omap if present, otherwise new empty Omap (safe for chaining)

### Mval Omap Operations (Convenience Methods)

Convenience methods for rapid prototyping. These methods silently fail or return default values if Mval is not an Omap. Optional errOut parameter can be used to get error information. Set() returns \*Mval for chaining.

- `func (m *Mval) Set(key string, value any, errOut ...*error) *Mval`: Set key-value pair (chainable)
- `func (m *Mval) Get(key string, errOut ...*error) *Mval`: Get value by key (returns Null if not found)
- `func (m *Mval) Exists(key string, errOut ...*error) bool`: Check if key exists
- `func (m *Mval) Len(errOut ...*error) int`: Get map length
- `func (m *Mval) Keys(errOut ...*error) []string`: Get all keys (preserves insertion order)
- `func (m *Mval) Delete(key any, errOut ...*error) *Mval`: Delete key (string) or index (int) - no error if key not found, error if slice index out of range (chainable)

### Mval JSON Serialization

- `func (m *Mval) MarshalJSON() ([]byte, error)`: Implements json.MarshalJSON
- `func (m *Mval) UnmarshalJSON(data []byte) error`: Implements json.UnmarshalJSON

---

### Omap (Ordered Map)

**Omap Constructor**

- `func NewOmap() *Omap`: Create ordered map

**Omap Operations**

- `func (o *Omap) Set(key string, value any) *Omap`: Set key-value pair (supports chaining)
- `func (o *Omap) Get(key string) *Mval`: Get value by key (returns Null if not found)
- `func (o *Omap) Exists(key string) bool`: Check if key exists
- `func (o *Omap) Keys() []string`: Get all keys (preserves insertion order)
- `func (o *Omap) Len() int`: Get map length
- `func (o *Omap) Delete(key string) *Omap`: Delete key from Omap (no error if key not found, supports chaining)

**Omap JSON Serialization**

- `func (o *Omap) MarshalJSON() ([]byte, error)`: Implements json.MarshalJSON
- `func (o *Omap) UnmarshalJSON(data []byte) error`: Implements json.UnmarshalJSON

---

### RawSet Operations

Directly modify values at specified paths within the Mval's internal data structure. Supports nested access through arrays and maps.

- `func Path(segments ...any) []any`: Create a path from segments (strings for keys, ints for indices)
- `func (m *Mval) RawSet(path []any, value any, errOut ...*error) *Mval`: Set value at specified path (chainable)

**Supported path types:**

- `*Omap`: Access by string key
- `map[string]any`: Access by string key
- `[]any`, `[]string`, `[]int`, `[]int64`, `[]float64`, `[]bool`: Access by int index

## Usage

```go
import "gitee.com/zoppax/mval"

// Parse JSON
data := []byte(`{"name":"Alice","age":30,"active":true}`)
m := mval.FromJSON(data)

// Get values from Omap with type safety
name := m.WhenOmap().Get("name").String() // "Alice"
age := m.WhenOmap().Get("age").Int()       // 30
active := m.WhenOmap().Get("active").Bool() // true

// Create ordered map
o2 := mval.NewOmap()
o2.Set("z", 1).Set("a", 2).Set("m", 3)

// Get all keys (preserves insertion order)
keys := o2.Keys() // ["z", "a", "m"]

// JSON marshal (preserves order)
jsonData, _ := json.Marshal(o2) // {"z":1,"a":2,"m":3}

// Safe conditional operations with WhenOmap()
m3 := mval.FromAny(o2)
m3.WhenOmap().Set("newKey", "newValue").Set("anotherKey", 42)

// Convenience methods for rapid prototyping (chainable)
m4 := mval.NewRoot()
m4.Set("city", "Shanghai").Set("year", 2024)

city := m4.Get("city").String() // "Shanghai"
year := m4.Get("year").Int()     // 2024
exists := m4.Exists("city")      // true
count := m4.Len()                 // 2
allKeys := m4.Keys()              // ["city", "year"]

// Convenience methods with error checking
var err error
m5 := mval.NewRoot()
m5.Set("key", "value", &err)
if err != nil {
    // handle error
}

val := m5.Get("key", &err)
if err != nil {
    // handle error
}

// Modify nested array element
m6 := mval.FromAny([]any{
    map[string]any{"items": []any{1, 2, 3}},
})
m6.RawSet(mval.Path(0, "items", 1), 100)
// Result: [{"items": [1, 100, 3]}]

// Modify nested map value
m7 := mval.FromAny(map[string]any{
    "user": map[string]any{"name": "Alice"},
})
m7.RawSet(mval.Path("user", "name"), "Bob")
// Result: {"user": {"name": "Bob"}}

// Chain multiple modifications
m8 := mval.NewRoot()
m8.Set("data", map[string]any{"items": []any{1, 2}})
m8.RawSet(mval.Path("data", "items", 0), 10).
   RawSet(mval.Path("data", "items", 1), 20)
// Result: {"data": {"items": [10, 20]}}
```